mdgen-mcp 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# mdgen-mcp
+
+MCP server for [mdgen](https://mdgen.app) — read and write your mdgen documents from
+Claude Desktop, Claude Code, Codex CLI, and other MCP clients, using **your own**
+account. The AI runs on your subscription; mdgen never pays for generation.
+
+## What it does
+
+Exposes your saved mdgen documents (available to logged-in users) as MCP tools:
+
+| Tool | Description |
+|------|-------------|
+| `list_documents` | List your documents (id, title, mode, updatedAt) |
+| `read_document` | Get a document's full Markdown by id |
+| `create_document` | Create a new document (`markdown`, `title?`, `mode?`) |
+| `update_document` | Update a document (only provided fields change) |
+| `delete_document` | Delete a document by id |
+
+## Prerequisites
+
+1. A mdgen account (sign in at https://mdgen.app).
+2. A **personal access token (PAT)**: issue one from mdgen while logged in
+   (Menu → API tokens). Copy it — it is shown only once.
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MDGEN_TOKEN` | ✅ | — | Your mdgen personal access token |
+| `MDGEN_API_URL` | | `https://api.mdgen.app` | mdgen API base URL |
+
+## Client setup
+
+### Claude Desktop
+
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mdgen": {
+      "command": "npx",
+      "args": ["-y", "mdgen-mcp"],
+      "env": {
+        "MDGEN_TOKEN": "<your token>"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add mdgen --env MDGEN_TOKEN=<your token> -- npx -y mdgen-mcp
+```
+
+### Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.mdgen]
+command = "npx"
+args = ["-y", "mdgen-mcp"]
+env = { MDGEN_TOKEN = "<your token>" }
+```
+
+## Security
+
+- Your PAT is passed via your client's `env` and never leaves your machine except as a
+  `Authorization: Bearer` header to the mdgen API. It is **not** stored in this package.
+- The PAT grants access only to **your** documents. Revoke it anytime from mdgen.
+- Treat the token like a password. Do not commit it.
+
+## Development
+
+```bash
+pnpm install
+pnpm dev        # run from source (tsx)
+pnpm build      # emit dist/
+pnpm test       # unit tests
+```
+
+Related: mdgen issue #151.

package/dist/client.js

@@ -0,0 +1,95 @@
+// mdgen backend（documents API）を PAT（Bearer）で叩く薄いクライアント。
+// 認証・データ分離は API 側（#151 Phase 1）が担う。ここは HTTP 呼び出しとエラー整形のみ。
+/** API エラー。status と人間可読メッセージを持つ。 */
+export class MdgenApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "MdgenApiError";
+    }
+}
+function humanMessage(status, detail, retryAfter) {
+    switch (status) {
+        case 401:
+            return "Authentication failed. Check that MDGEN_TOKEN is a valid mdgen access token.";
+        case 404:
+            return "Document not found (it may not exist or belong to another user).";
+        case 422:
+            return "Limit reached (documents are capped at 50 per user).";
+        case 429:
+            return `Rate limit exceeded.${retryAfter ? ` Try again in ${retryAfter}s.` : " Please wait and retry."}`;
+        default:
+            return `mdgen API error (${status})${detail ? `: ${detail}` : ""}`;
+    }
+}
+export function createMdgenClient(baseUrl, token, fetchImpl = fetch) {
+    const base = baseUrl.replace(/\/$/, "");
+    async function request(path, init) {
+        const res = await fetchImpl(`${base}${path}`, {
+            ...init,
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json",
+                ...init?.headers,
+            },
+        });
+        if (!res.ok) {
+            let detail = "";
+            try {
+                const body = (await res.json());
+                detail = body.error ?? body.code ?? "";
+            }
+            catch {
+                // non-JSON error body
+            }
+            const retryAfter = res.status === 429 ? res.headers.get("retry-after") : null;
+            throw new MdgenApiError(res.status, humanMessage(res.status, detail, retryAfter));
+        }
+        return res;
+    }
+    return {
+        async listDocuments() {
+            const data = (await (await request("/api/documents")).json());
+            return data.items.map((d) => ({
+                id: d.id,
+                title: d.title,
+                mode: d.mode,
+                updatedAt: d.updatedAt,
+            }));
+        },
+        async readDocument(id) {
+            return (await request(`/api/documents/${encodeURIComponent(id)}`)).json();
+        },
+        async createDocument(input) {
+            const res = await request("/api/documents", {
+                method: "POST",
+                body: JSON.stringify({
+                    markdown: input.markdown,
+                    title: input.title ?? "",
+                    mode: input.mode ?? "pdf",
+                }),
+            });
+            return res.json();
+        },
+        // 指定フィールドのみ変更する。API の PUT は全項目を上書きするため、
+        // 既存を読んで未指定フィールドを保持してから送る（title/mode の消失を防ぐ）。
+        async updateDocument(id, patch) {
+            const current = (await (await request(`/api/documents/${encodeURIComponent(id)}`)).json());
+            await request(`/api/documents/${encodeURIComponent(id)}`, {
+                method: "PUT",
+                body: JSON.stringify({
+                    title: patch.title ?? current.title,
+                    markdown: patch.markdown ?? current.markdown,
+                    mode: patch.mode ?? current.mode,
+                    settings: current.settings ?? undefined,
+                }),
+            });
+        },
+        async deleteDocument(id) {
+            await request(`/api/documents/${encodeURIComponent(id)}`, {
+                method: "DELETE",
+            });
+        },
+    };
+}

package/dist/index.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// mdgen MCP サーバ（#151）。
+// ユーザー自身の MCP クライアント（Claude Desktop / Claude Code / Codex 等）から、
+// ユーザーの PAT（MDGEN_TOKEN）で mdgen のドキュメントを読み書きする stdio サーバ。
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createMdgenClient, MdgenApiError } from "./client.js";
+const DEFAULT_API_URL = "https://api.mdgen.app";
+const apiUrl = process.env.MDGEN_API_URL ?? DEFAULT_API_URL;
+const token = process.env.MDGEN_TOKEN;
+if (!token) {
+    console.error("MDGEN_TOKEN is required. Create a token in mdgen (logged in) and set it as MDGEN_TOKEN.");
+    process.exit(1);
+}
+const client = createMdgenClient(apiUrl, token);
+/** ツールハンドラ共通: 例外を人間可読なエラー結果に変換する。 */
+async function run(fn) {
+    try {
+        return { content: [{ type: "text", text: await fn() }] };
+    }
+    catch (error) {
+        const message = error instanceof MdgenApiError
+            ? error.message
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        return { content: [{ type: "text", text: message }], isError: true };
+    }
+}
+const server = new McpServer({ name: "mdgen-mcp", version: "0.1.0" });
+server.registerTool("list_documents", {
+    title: "List documents",
+    description: "List the current user's saved mdgen documents (id, title, mode, updatedAt).",
+    inputSchema: {},
+}, async () => run(async () => {
+    const items = await client.listDocuments();
+    if (items.length === 0)
+        return "No documents.";
+    return JSON.stringify(items, null, 2);
+}));
+server.registerTool("read_document", {
+    title: "Read document",
+    description: "Get the full Markdown and metadata of a document by id.",
+    inputSchema: { id: z.string().describe("Document id") },
+}, async ({ id }) => run(async () => {
+    const doc = await client.readDocument(id);
+    return JSON.stringify({
+        id: doc.id,
+        title: doc.title,
+        mode: doc.mode,
+        markdown: doc.markdown,
+    }, null, 2);
+}));
+server.registerTool("create_document", {
+    title: "Create document",
+    description: "Create a new mdgen document. Returns the created document id.",
+    inputSchema: {
+        markdown: z.string().describe("Markdown body"),
+        title: z.string().optional().describe("Optional title"),
+        mode: z
+            .enum(["pdf", "slide"])
+            .optional()
+            .describe("Output mode (default: pdf)"),
+    },
+}, async ({ markdown, title, mode }) => run(async () => {
+    const doc = await client.createDocument({ markdown, title, mode });
+    return `Created document ${doc.id}.`;
+}));
+server.registerTool("update_document", {
+    title: "Update document",
+    description: "Update a document by id. Only the provided fields change; others are preserved.",
+    inputSchema: {
+        id: z.string().describe("Document id"),
+        markdown: z.string().optional().describe("New Markdown body"),
+        title: z.string().optional().describe("New title"),
+        mode: z.enum(["pdf", "slide"]).optional().describe("New output mode"),
+    },
+}, async ({ id, markdown, title, mode }) => run(async () => {
+    await client.updateDocument(id, { markdown, title, mode });
+    return `Updated document ${id}.`;
+}));
+server.registerTool("delete_document", {
+    title: "Delete document",
+    description: "Delete a document by id.",
+    inputSchema: { id: z.string().describe("Document id") },
+}, async ({ id }) => run(async () => {
+    await client.deleteDocument(id);
+    return `Deleted document ${id}.`;
+}));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// stdio サーバはここで待機する（プロセスは MCP クライアントが管理）。

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "mdgen-mcp",
+	"version": "0.1.0",
+	"description": "MCP server for mdgen — read/write your mdgen documents from Claude / Codex and other MCP clients",
+	"type": "module",
+	"bin": {
+		"mdgen-mcp": "dist/index.js"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsx src/index.ts",
+		"test": "vitest run",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "pnpm build"
+	},
+	"keywords": [
+		"mcp",
+		"modelcontextprotocol",
+		"mdgen",
+		"markdown",
+		"claude"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Shien-Inc/markdown-to-pdf.git",
+		"directory": "mcp"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.0",
+		"zod": "^3.24.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22",
+		"tsx": "^4.19.0",
+		"typescript": "~5.9.3",
+		"vitest": "^4.0.0"
+	}
+}