@pdfgen/mcp 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# PDFgen MCP server
+
+Let AI agents generate PDFs. This is a [Model Context Protocol](https://modelcontextprotocol.io)
+server that exposes the [PDFgen](https://pdfgen.com) API as tools, so Claude
+Desktop (and any other MCP client) can turn HTML, Markdown, or a saved template
+into a PDF and get back a hosted link.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `generate_pdf` | Generate a PDF from `html`, `markdown`, or a saved `template_id` (with optional `data` for Handlebars tokens). Returns a hosted, expiring URL. |
+| `list_templates` | List the saved templates on your PDFgen account. |
+| `create_template` | Create a reusable template from HTML; returns its `template_id`. |
+
+## Requirements
+
+- **Node.js 18 or newer** (the `npx` command and the server's `fetch` need it — check with `node -v`).
+- An **MCP client** such as Claude Desktop.
+- A **PDFgen API key** — sign in at [pdfgen.com](https://pdfgen.com) and copy a key from
+  [the Developer page](https://pdfgen.com/developer). It looks like `pdfg_live_...`.
+
+## Setup (Claude Desktop)
+
+Open your `claude_desktop_config.json` and add the `pdfgen` entry below. The file lives at:
+
+- **macOS** — `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows** — `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux** — `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "pdfgen": {
+      "command": "npx",
+      "args": ["-y", "@pdfgen/mcp"],
+      "env": {
+        "PDFGEN_API_KEY": "pdfg_live_xxx"
+      }
+    }
+  }
+}
+```
+
+**Fully quit and reopen Claude Desktop** (not just close the window). PDFgen is
+connected when the tools (🔨 icon) list `generate_pdf`, `list_templates`, and
+`create_template`.
+
+Then try:
+
+> *"Generate an invoice PDF for Acme Corp for $2,400 and give me the link."*
+
+A few more things to ask:
+
+- *"Create a reusable certificate template, then generate one for Maria González."*
+- *"List my PDFgen templates."*
+
+## Any MCP client
+
+The server speaks MCP over stdio. Run it with your key in the environment:
+
+```bash
+PDFGEN_API_KEY=pdfg_live_xxx npx -y @pdfgen/mcp
+```
+
+## Environment variables
+
+| Variable | Required | Default | Notes |
+|----------|----------|---------|-------|
+| `PDFGEN_API_KEY` | ✅ | — | Your `pdfg_live_...` API key. |
+| `PDFGEN_BASE_URL` | — | `https://pdfgen.com` | Override for self-hosted / staging. |
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| Tools don't appear in Claude | Make sure you **fully quit** and reopened the app, and that the JSON is valid (a trailing comma or missing brace silently disables the server). |
+| `missing PDFGEN_API_KEY` in logs | The `env.PDFGEN_API_KEY` value is empty or the key isn't set in your shell. Paste your real `pdfg_live_...` key. |
+| `PDFgen API 401` | The key is wrong, revoked, or for a different environment. Copy a fresh one from the [Developer page](https://pdfgen.com/developer). |
+| `npx: command not found` | Install Node.js 18+ (which ships `npx`) from [nodejs.org](https://nodejs.org). |
+| Renders are watermarked | The free tier watermarks output — upgrade your PDFgen plan to remove it. |
+
+## Local development
+
+```bash
+npm install
+npm run build      # compile src → dist
+PDFGEN_API_KEY=pdfg_live_xxx node dist/index.js
+```
+
+`stdout` is the MCP protocol channel, so all logs go to `stderr`.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * PDFgen MCP server (stdio).
+ *
+ * Exposes the PDFgen public API (POST /api/v1/...) as MCP tools so AI agents
+ * — Claude Desktop and any other MCP client — can generate PDFs and manage
+ * templates. Thin wrapper over the REST API; auth is a PDFgen API key.
+ *
+ * Env:
+ *   PDFGEN_API_KEY   (required)  your pdfg_live_... key
+ *   PDFGEN_BASE_URL  (optional)  defaults to https://pdfgen.com
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_KEY = process.env.PDFGEN_API_KEY;
+const BASE_URL = (process.env.PDFGEN_BASE_URL || "https://pdfgen.com").replace(/\/+$/, "");
+if (!API_KEY) {
+    // Fail fast with a clear message on the stderr channel (stdout is the MCP transport).
+    console.error("PDFgen MCP: missing PDFGEN_API_KEY environment variable.");
+    process.exit(1);
+}
+/** Call the PDFgen API with the configured key; returns parsed JSON or throws. */
+async function api(path, init = {}) {
+    const { json, ...rest } = init;
+    const res = await fetch(`${BASE_URL}${path}`, {
+        ...rest,
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            ...(json !== undefined ? { "Content-Type": "application/json" } : {}),
+            ...(rest.headers || {}),
+        },
+        body: json !== undefined ? JSON.stringify(json) : rest.body,
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : null;
+    }
+    catch {
+        parsed = text;
+    }
+    if (!res.ok) {
+        const message = (parsed && typeof parsed === "object" && "error" in parsed
+            ? JSON.stringify(parsed.error)
+            : typeof parsed === "string"
+                ? parsed
+                : JSON.stringify(parsed)) || res.statusText;
+        throw new Error(`PDFgen API ${res.status}: ${message}`);
+    }
+    return parsed;
+}
+/** Standard MCP text result. */
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+/** Standard MCP error result. */
+const fail = (s) => ({ content: [{ type: "text", text: s }], isError: true });
+const server = new McpServer({ name: "pdfgen", version: "0.1.0" });
+server.registerTool("generate_pdf", {
+    title: "Generate a PDF",
+    description: "Generate a PDF from HTML, Markdown, or a saved PDFgen template, and return a hosted link to it. " +
+        "Provide exactly one of `html`, `markdown`, or `template_id`. Use `data` (a JSON object) to fill " +
+        "Handlebars tokens in the HTML or template. Returns an expiring URL to the rendered PDF.",
+    inputSchema: {
+        html: z.string().optional().describe("Raw HTML (optionally with {{handlebars}} tokens)."),
+        markdown: z.string().optional().describe("Markdown to render to a styled PDF."),
+        template_id: z.string().optional().describe("ID of a saved PDFgen template to render."),
+        data: z
+            .record(z.any())
+            .optional()
+            .describe("JSON data object merged into Handlebars tokens."),
+        engine: z
+            .enum(["handlebars", "legacy"])
+            .optional()
+            .describe('For raw html: "handlebars" (default) or "legacy" to skip templating.'),
+        format: z.string().optional().describe('Page format, e.g. "A4" or "Letter".'),
+        file_name: z.string().optional().describe("Optional file name for the generated PDF."),
+    },
+}, async (args) => {
+    const sources = [args.html, args.markdown, args.template_id].filter(Boolean);
+    if (sources.length !== 1) {
+        return fail("Provide exactly one of `html`, `markdown`, or `template_id`.");
+    }
+    try {
+        const result = (await api("/api/v1/generate", {
+            method: "POST",
+            json: {
+                html: args.html,
+                markdown: args.markdown,
+                template_id: args.template_id,
+                data: args.data,
+                engine: args.engine,
+                format: args.format,
+                file_name: args.file_name,
+                // Return a hosted link rather than a binary, which an MCP client can open.
+                export_type: "url",
+            },
+        }));
+        if (!result?.url)
+            return fail(`Unexpected response: ${JSON.stringify(result)}`);
+        return text(`PDF generated: ${result.url}`);
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+});
+server.registerTool("list_templates", {
+    title: "List templates",
+    description: "List the saved PDFgen templates available to your account (id, name, engine).",
+    inputSchema: {},
+}, async () => {
+    try {
+        const result = await api("/api/v1/templates", { method: "GET" });
+        return text(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+});
+server.registerTool("create_template", {
+    title: "Create a template",
+    description: "Create a reusable PDFgen template from HTML (with optional Handlebars tokens). " +
+        "Returns the new template's id, which you can then pass to generate_pdf as `template_id`.",
+    inputSchema: {
+        name: z.string().describe("A name for the template."),
+        content: z.string().describe("The template HTML (optionally with {{handlebars}} tokens)."),
+        engine: z
+            .enum(["handlebars", "legacy"])
+            .optional()
+            .describe('Templating engine: "handlebars" (default) or "legacy".'),
+    },
+}, async (args) => {
+    try {
+        const result = await api("/api/v1/templates", {
+            method: "POST",
+            json: { name: args.name, content: args.content, engine: args.engine },
+        });
+        return text(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`PDFgen MCP server running (base: ${BASE_URL}).`);
+}
+main().catch((err) => {
+    console.error("PDFgen MCP fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@pdfgen/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for PDFgen — let AI agents generate PDFs from HTML, Markdown, or saved templates.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "PDFgen",
+  "homepage": "https://pdfgen.com/mcp",
+  "bin": {
+    "pdfgen-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pdf",
+    "pdfgen",
+    "html-to-pdf",
+    "ai"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}