markdowntoimage-cn-mcp 1.0.2

package/README.md

@@ -0,0 +1,85 @@
+# markdowntoimage-cn-mcp
+
+MCP (Model Context Protocol) server for the [MarkdownToImage](https://markdowntoimage.cn) API. Convert Markdown to beautiful images directly from Claude, Cursor, or any MCP-compatible client.
+
+## Features
+
+- **generate_image** — Convert Markdown to PNG/JPEG/WebP images with themes, code highlighting, KaTeX math, and Mermaid diagrams
+- **get_usage** — Check your monthly API quota and credit balance
+
+## Quick Start
+
+### 1. Get an API Token
+
+Sign up at [markdowntoimage.cn](https://markdowntoimage.cn) and create a token at [Profile → API Tokens](https://markdowntoimage.cn/profile/api-tokens).
+
+### 2. Configure in Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "markdowntoimage": {
+      "command": "npx",
+      "args": ["-y", "markdowntoimage-cn-mcp"],
+      "env": {
+        "MTI_API_TOKEN": "mti_your_token_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Use It
+
+Ask Claude: *"Convert this markdown to an image: # Hello World"*
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MTI_API_TOKEN` | Yes | — | Your API token (starts with `mti_`) |
+| `MTI_BASE_URL` | No | `https://markdowntoimage.cn` | API base URL |
+
+## Tools
+
+### generate_image
+
+Convert Markdown text to an image.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `markdown` | string | Yes | Markdown content to convert |
+| `width` | number | No | Image width, 200-2560 (default: 800) |
+| `format` | string | No | `png`, `jpeg`, or `webp` (default: `png`) |
+| `quality` | number | No | Scale factor 1.0-3.0 (default: 2.0) |
+| `theme` | string | No | Theme ID (e.g. `minimal-dark`) |
+| `codeStyle` | string | No | Code highlight style (e.g. `nord`) |
+| `fontFamily` | string | No | Font ID (e.g. `inter`, `fira-code`) |
+| `mode` | string | No | `url` or `binary` (default: `url`) |
+
+### get_usage
+
+Check your current API usage statistics. No parameters required.
+
+## Quota & Pricing
+
+- **50 free requests/month** per account
+- After the free quota, each request costs **1 credit**
+- Users with credits always get **watermark-free** images
+- Purchase credits at [markdowntoimage.cn/profile/credits](https://markdowntoimage.cn/profile/credits)
+
+## Development
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const API_TOKEN = process.env.MTI_API_TOKEN;
+const BASE_URL = process.env.MTI_BASE_URL || 'https://markdowntoimage.cn';
+if (!API_TOKEN) {
+    process.stderr.write('Error: MTI_API_TOKEN environment variable is required.\n' +
+        'Get your API token at: https://markdowntoimage.cn/profile/api-tokens\n');
+    process.exit(1);
+}
+const server = new McpServer({
+    name: 'markdowntoimage',
+    version: '1.0.2',
+});
+// ── generate_image tool ──────────────────────────────────────────────
+server.registerTool('generate_image', {
+    description: 'Convert Markdown text to a beautiful image. Supports code highlighting, math formulas (KaTeX), Mermaid diagrams, and multiple themes/fonts.',
+    inputSchema: {
+        markdown: z.string().describe('The Markdown content to convert to an image'),
+        width: z
+            .number()
+            .min(200)
+            .max(2560)
+            .optional()
+            .describe('Image width in pixels (200-2560, default: 800)'),
+        format: z
+            .enum(['png', 'jpeg', 'webp'])
+            .optional()
+            .describe('Output image format (default: png)'),
+        quality: z
+            .number()
+            .min(1.0)
+            .max(3.0)
+            .optional()
+            .describe('Device scale factor for image quality (1.0-3.0, default: 2.0)'),
+        theme: z
+            .string()
+            .optional()
+            .describe('Theme ID. Available: light, dark, github, github-dark, nord, monokai, solarized, ' +
+            'dracula, one-dark, ocean, pastel, mint, lavender, purple-dream, midnight, forest, ' +
+            'sunset, transparent, transparent-dark'),
+        codeStyle: z
+            .string()
+            .optional()
+            .describe('Code highlight style. Available: nord, monokai, github, github-dark, atom-one-dark, ' +
+            'atom-one-light, vs, vs2015, xcode, solarized-dark, dracula, tomorrow-night, ' +
+            'tomorrow-night-blue, night-owl, shades-of-purple, a11y-dark, a11y-light, default'),
+        fontFamily: z
+            .string()
+            .optional()
+            .describe('Font family ID. Available: sans (Noto Sans), inter, serif (Noto Serif), fira (Fira Code), ' +
+            'jetbrains (JetBrains Mono), roboto, ubuntu, modern (Work Sans), elegant (Lora), ' +
+            'article (Source Sans), docs (Open Sans), japanese (Noto Sans JP), chinese (Noto Sans SC), ' +
+            'arabic (Noto Naskh Arabic), cyrillic (Noto Sans Cyrillic)'),
+        mode: z
+            .enum(['url', 'binary'])
+            .optional()
+            .describe('Response mode: "url" returns an image URL, "binary" returns raw image data (default: url)'),
+    },
+}, async (params) => {
+    try {
+        const res = await fetch(`${BASE_URL}/api/v1/images/generate`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${API_TOKEN}`,
+            },
+            body: JSON.stringify({
+                markdown: params.markdown,
+                width: params.width,
+                format: params.format,
+                quality: params.quality,
+                theme: params.theme,
+                codeStyle: params.codeStyle,
+                fontFamily: params.fontFamily,
+                mode: params.mode ?? 'url',
+            }),
+        });
+        if (!res.ok) {
+            const errorBody = await res.json().catch(() => null);
+            const msg = errorBody?.error?.message || `HTTP ${res.status}`;
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+        // binary mode → return image directly
+        if (params.mode === 'binary') {
+            const buffer = Buffer.from(await res.arrayBuffer());
+            const mimeType = res.headers.get('content-type') || 'image/png';
+            return {
+                content: [
+                    {
+                        type: 'image',
+                        data: buffer.toString('base64'),
+                        mimeType,
+                    },
+                ],
+            };
+        }
+        // url mode → return structured text
+        const json = await res.json();
+        const data = json.data;
+        const quota = json.meta?.quota;
+        let text = `Image generated successfully!\n\nURL: ${data.imageUrl}\nFormat: ${data.format}\nWidth: ${data.width}px`;
+        if (quota) {
+            text += `\n\nQuota: ${quota.freeRemaining} free requests remaining this month`;
+            if (quota.creditBalance !== undefined) {
+                text += `, ${quota.creditBalance} credits available`;
+            }
+        }
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: 'text', text: `Request failed: ${err.message}` }],
+            isError: true,
+        };
+    }
+});
+// ── get_usage tool ───────────────────────────────────────────────────
+server.registerTool('get_usage', {
+    description: 'Check your current API usage stats: monthly quota, credits balance, and reset date.',
+}, async () => {
+    try {
+        const res = await fetch(`${BASE_URL}/api/v1/account/usage`, {
+            headers: { Authorization: `Bearer ${API_TOKEN}` },
+        });
+        if (!res.ok) {
+            const errorBody = await res.json().catch(() => null);
+            const msg = errorBody?.error?.message || `HTTP ${res.status}`;
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+        const json = await res.json();
+        const d = json.data;
+        const text = [
+            'API Usage Statistics',
+            '',
+            `Monthly Quota: ${d.monthlyUsed} / ${d.monthlyQuota} used`,
+            `Free Remaining: ${d.monthlyRemaining}`,
+            `Credit Balance: ${d.creditBalance}`,
+            `Current Period: ${d.yearMonth}`,
+            `Resets On: ${d.resetDate}`,
+        ].join('\n');
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: 'text', text: `Request failed: ${err.message}` }],
+            isError: true,
+        };
+    }
+});
+// ── Start server ─────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`Failed to start MCP server: ${err}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "markdowntoimage-cn-mcp",
+  "version": "1.0.2",
+  "description": "MCP server for MarkdownToImage API - Convert Markdown to beautiful images",
+  "type": "module",
+  "bin": {
+    "markdowntoimage-cn-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "markdown",
+    "image",
+    "markdown-to-image",
+    "model-context-protocol",
+    "claude",
+    "ai"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "@types/node": "^22.15.21"
+  }
+}