feat: add markdown rendering support #16

Implemented full support for Gogs Markdown rendering APIs:
- Added render_markdown tool for GitHub Flavored Markdown with repository context
- Added render_markdown_raw tool for simple text-to-HTML conversion
- Created TypeScript types: GogsMarkdownRequest, GogsMarkdownMode
- Added renderMarkdown and renderMarkdownRaw methods to GogsClient
- Updated documentation in README.md and CLAUDE.md
- Added comprehensive usage examples and use cases

Features:
- Support for GitHub Flavored Markdown (GFM) and standard Markdown modes
- Repository context for issue/PR reference resolution
- Preview documentation and content before committing
- Useful for custom markdown editors and preview features

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -42,6 +42,7 @@ The server exposes tools in these categories:
 - **Deploy Key Management**: list_deploy_keys, get_deploy_key, create_deploy_key, delete_deploy_key
 - **Webhook Management**: list_hooks, create_hook, update_hook, delete_hook
 - **User Followers**: list_followers, list_following, check_following, follow_user, unfollow_user
+- **Markdown Rendering**: render_markdown, render_markdown_raw
 
 ## Development Commands
 

README.md

@@ -91,6 +91,12 @@ This MCP server provides tools to:
   - Follow a user
   - Unfollow a user
 
+- **Markdown Rendering**
+  - Render markdown text to HTML with GitHub Flavored Markdown (GFM) support
+  - Render raw markdown with simple text input
+  - Support repository context for issue/PR references
+  - Preview documentation and content before committing
+
 ## Installation
 
 ### Prerequisites
@@ -917,6 +923,51 @@ Unfollow a user. The authenticated user will unfollow the target user.
 }
 ```
 
+### Markdown Rendering Tools
+
+These tools allow rendering markdown text to HTML without committing files, useful for previewing documentation, issue/comment content, and building custom markdown editors.
+
+#### `render_markdown`
+Render markdown text to HTML with support for GitHub Flavored Markdown (GFM) and repository context. This is the full-featured markdown rendering endpoint.
+- `text` (string, required): Markdown text to render
+- `mode` (string, optional): Rendering mode - either "gfm" (GitHub Flavored Markdown, default) or "markdown" (standard Markdown)
+- `context` (string, optional): Repository context in the format "owner/repo" for repository-aware rendering (e.g., for resolving issue references like #123)
+
+**Example:**
+```json
+{
+  "text": "# Hello World\n\nThis is **bold** and this is *italic*.\n\n- Item 1\n- Item 2\n\nSee issue #42 for details.",
+  "mode": "gfm",
+  "context": "myuser/myrepo"
+}
+```
+
+**Response:** Returns the rendered HTML as plain text.
+
+**Use cases:**
+- Preview README.md before committing
+- Render issue/comment markdown for display
+- Generate documentation from markdown sources
+- Build custom markdown editors with live preview
+
+#### `render_markdown_raw`
+Render raw markdown text to HTML using a simpler endpoint. This is a streamlined version that takes plain text input and returns HTML.
+- `text` (string, required): Raw markdown text to render to HTML
+
+**Example:**
+```json
+{
+  "text": "# Simple Heading\n\n**Bold text** and *italic text*."
+}
+```
+
+**Response:** Returns the rendered HTML as plain text.
+
+**Use cases:**
+- Quick markdown previews
+- Simple text-to-HTML conversion
+- When you don't need repository context or mode selection
+
 ## Documented but Not Yet Implemented API Endpoints
 
 The following Gogs API v1 endpoints are officially documented but not yet implemented in this MCP server. These represent potential features for future development:

src/gogs-client.ts

@@ -29,6 +29,8 @@ import type {
   GogsWebhookConfig,
   GogsFollower,
   GogsDeployKey,
+  GogsMarkdownRequest,
+  GogsMarkdownMode,
 } from './types.js';
 
 export class GogsClient {
@@ -885,4 +887,30 @@ export class GogsClient {
   async deleteDeployKey(owner: string, repo: string, keyId: number): Promise<void> {
     await this.client.delete(`/repos/${owner}/${repo}/keys/${keyId}`);
   }
+
+  /**
+   * Render markdown text to HTML
+   * Supports GitHub Flavored Markdown (GFM) and standard Markdown
+   */
+  async renderMarkdown(data: GogsMarkdownRequest): Promise<string> {
+    const response = await this.client.post<string>('/markdown', data, {
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+    return response.data;
+  }
+
+  /**
+   * Render raw markdown text to HTML
+   * Simpler endpoint that takes plain text and returns HTML
+   */
+  async renderMarkdownRaw(text: string): Promise<string> {
+    const response = await this.client.post<string>('/markdown/raw', text, {
+      headers: {
+        'Content-Type': 'text/plain',
+      },
+    });
+    return response.data;
+  }
 }

src/server.ts

@@ -446,6 +446,16 @@ const DeleteDeployKeySchema = z.object({
   keyId: z.number().describe('Deploy key ID to delete'),
 });
 
+const RenderMarkdownSchema = z.object({
+  text: z.string().describe('Markdown text to render'),
+  mode: z.enum(['gfm', 'markdown']).optional().describe('Rendering mode: "gfm" for GitHub Flavored Markdown (default) or "markdown" for standard Markdown'),
+  context: z.string().optional().describe('Repository context in the format "owner/repo" for repository-aware rendering (e.g., for issue references)'),
+});
+
+const RenderMarkdownRawSchema = z.object({
+  text: z.string().describe('Raw markdown text to render to HTML'),
+});
+
 /**
  * Create and configure an MCP server with all tools and handlers
  */
@@ -2107,6 +2117,43 @@ export function createMcpServer(gogsClient: GogsClient): Server {
             required: ['owner', 'repo', 'keyId'],
           },
         },
+        {
+          name: 'render_markdown',
+          description: 'Render markdown text to HTML with support for GitHub Flavored Markdown (GFM) and repository context',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              text: {
+                type: 'string',
+                description: 'Markdown text to render',
+              },
+              mode: {
+                type: 'string',
+                enum: ['gfm', 'markdown'],
+                description: 'Rendering mode: "gfm" for GitHub Flavored Markdown (default) or "markdown" for standard Markdown',
+              },
+              context: {
+                type: 'string',
+                description: 'Repository context in the format "owner/repo" for repository-aware rendering (e.g., for issue references)',
+              },
+            },
+            required: ['text'],
+          },
+        },
+        {
+          name: 'render_markdown_raw',
+          description: 'Render raw markdown text to HTML (simpler endpoint, plain text input)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              text: {
+                type: 'string',
+                description: 'Raw markdown text to render to HTML',
+              },
+            },
+            required: ['text'],
+          },
+        },
       ],
     };
   });
@@ -3157,6 +3204,36 @@ export function createMcpServer(gogsClient: GogsClient): Server {
           };
         }
 
+        case 'render_markdown': {
+          const { text, mode, context } = RenderMarkdownSchema.parse(args);
+          const html = await gogsClient.renderMarkdown({
+            text,
+            mode,
+            context,
+          });
+          return {
+            content: [
+              {
+                type: 'text',
+                text: html,
+              },
+            ],
+          };
+        }
+
+        case 'render_markdown_raw': {
+          const { text } = RenderMarkdownRawSchema.parse(args);
+          const html = await gogsClient.renderMarkdownRaw(text);
+          return {
+            content: [
+              {
+                type: 'text',
+                text: html,
+              },
+            ],
+          };
+        }
+
         default:
           throw new Error(`Unknown tool: ${name}`);
       }

src/types.ts

@@ -258,3 +258,15 @@ export interface GogsDeployKey {
   created_at: string;
   read_only: boolean;
 }
+
+export type GogsMarkdownMode = 'gfm' | 'markdown';
+
+export interface GogsMarkdownRequest {
+  text: string;
+  mode?: GogsMarkdownMode;
+  context?: string;
+}
+
+export interface GogsMarkdownResponse {
+  html: string;
+}