podpdf-mcp 1.0.0

package/README.md

@@ -0,0 +1,47 @@
+# podpdf-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for [PodPDF](https://podpdf.com). It lets Claude, Cursor, VS Code and any other MCP client turn HTML, Markdown, URLs and saved templates into PDFs.
+
+## Setup
+
+1. Get an API key at [app.podpdf.com](https://app.podpdf.com) → Settings → API Keys. PodPDF charges $0.01 per PDF, and an account needs a plan or a credit pack before calls succeed.
+2. Add the server to your client. Most clients take this config:
+
+```json
+{
+  "mcpServers": {
+    "podpdf": {
+      "command": "npx",
+      "args": ["-y", "podpdf-mcp"],
+      "env": { "PODPDF_API_KEY": "pk_..." }
+    }
+  }
+}
+```
+
+With Claude Code:
+
+```bash
+claude mcp add podpdf --env PODPDF_API_KEY=pk_... -- npx -y podpdf-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `generate_pdf` | HTML, Markdown or a public HTTPS URL to PDF, up to 25 pages. Options: `format`, `landscape`, `margin`, `printBackground`, `scale`, `pageRanges`. |
+| `render_template` | Fill a saved template (`template_id`) with `data` and render it. |
+| `start_long_job` | Queue HTML or Markdown up to 100 pages. `wait: true` polls until it's done. |
+| `get_job` | Status and details of a job. |
+| `get_download_link` | A fresh 1-hour download link for a job's stored output. |
+
+`generate_pdf`, `render_template` and `get_download_link` take an optional `save_path` to write the PDF to disk. Otherwise they return a download link that is valid for one hour.
+
+## Environment
+
+| Variable | Required | Default |
+| --- | --- | --- |
+| `PODPDF_API_KEY` | yes | — |
+| `PODPDF_API_URL` | no | `https://api.podpdf.com` |
+
+API docs: [apidocs.podpdf.com](https://apidocs.podpdf.com). Support: podpdfapp@gmail.com.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "podpdf-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for PodPDF: turn HTML, Markdown, URLs and templates into PDFs from any MCP client.",
+  "mcpName": "io.github.mohzameer/podpdf",
+  "type": "module",
+  "bin": {
+    "podpdf-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test"
+  },
+  "keywords": ["mcp", "model-context-protocol", "pdf", "html-to-pdf", "markdown-to-pdf", "podpdf"],
+  "homepage": "https://podpdf.com",
+  "author": "PodPDF <podpdfapp@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,98 @@
+// Thin client for the slice of the PodPDF API the MCP tools use. See ../../SPEC.md.
+
+export const DEFAULT_BASE_URL = 'https://api.podpdf.com';
+
+export class PodPdfError extends Error {
+  constructor(status, code, message, details) {
+    super(`PodPDF ${status}${code ? ` ${code}` : ''}: ${message}`);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function createClient({ apiKey, baseUrl = DEFAULT_BASE_URL, fetchImpl = globalThis.fetch } = {}) {
+  const root = baseUrl.replace(/\/+$/, '');
+
+  async function request(method, path, body) {
+    if (!apiKey) {
+      throw new PodPdfError(401, 'MISSING_API_KEY', 'Set PODPDF_API_KEY to your key from https://app.podpdf.com (Settings → API Keys).');
+    }
+    const res = await fetchImpl(`${root}${path}`, {
+      method,
+      headers: {
+        'X-API-Key': apiKey,
+        Accept: 'application/json',
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+        'User-Agent': 'podpdf-mcp',
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let json = null;
+    try {
+      json = text ? JSON.parse(text) : null;
+    } catch {
+      // Non-JSON body; reported below if the status is an error.
+    }
+    if (!res.ok) {
+      const err = json?.error ?? {};
+      throw new PodPdfError(res.status, err.code, err.message || text || res.statusText, err.details);
+    }
+    return json;
+  }
+
+  async function download(url) {
+    const res = await fetchImpl(url);
+    if (!res.ok) throw new PodPdfError(res.status, 'DOWNLOAD_FAILED', `Could not download ${url}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+
+  return {
+    me: () => request('GET', '/me'),
+    quickjob: (body) => request('POST', '/quickjob', { ...body, store: true }),
+    renderTemplate: (templateId, body) =>
+      request('POST', `/templates/${encodeURIComponent(templateId)}/render`, { ...body, store: true }),
+    longjob: (body) => request('POST', '/longjob', body),
+    getJob: (jobId) => request('GET', `/jobs/${encodeURIComponent(jobId)}`),
+    getDownloadLink: (jobId) => request('GET', `/jobs/${encodeURIComponent(jobId)}/download`),
+    download,
+  };
+}
+
+/**
+ * Expands dotted keys into nested objects, so `customer.name` becomes
+ * `{ customer: { name: … } }` — the shape the render API expects. A plain key
+ * wins over a dotted one.
+ */
+export function expandDottedKeys(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return data;
+  const out = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (!key.includes('.')) continue;
+    const parts = key.split('.');
+    const last = parts.pop();
+    let target = out;
+    for (const part of parts) {
+      if (!target[part] || typeof target[part] !== 'object' || Array.isArray(target[part])) target[part] = {};
+      target = target[part];
+    }
+    target[last] = value;
+  }
+  for (const [key, value] of Object.entries(data)) {
+    if (!key.includes('.')) out[key] = value;
+  }
+  return out;
+}
+
+// Builds `options` from the flat fields tools accept, leaving out anything unset.
+export function buildOptions({ format, landscape, margin, printBackground, scale, pageRanges } = {}) {
+  const options = {};
+  if (format) options.format = format;
+  if (landscape !== undefined) options.landscape = landscape;
+  if (margin) options.margin = { top: margin, right: margin, bottom: margin, left: margin };
+  if (printBackground !== undefined) options.printBackground = printBackground;
+  if (scale !== undefined) options.scale = scale;
+  if (pageRanges) options.pageRanges = pageRanges;
+  return Object.keys(options).length ? options : undefined;
+}

package/src/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createClient } from './client.js';
+import { createServer } from './server.js';
+
+const client = createClient({
+  apiKey: process.env.PODPDF_API_KEY,
+  baseUrl: process.env.PODPDF_API_URL || undefined,
+});
+
+if (!process.env.PODPDF_API_KEY) {
+  console.error('podpdf-mcp: PODPDF_API_KEY is not set; tool calls will fail until it is.');
+}
+
+await createServer(client).connect(new StdioServerTransport());

package/src/server.js

@@ -0,0 +1,189 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { buildOptions, expandDottedKeys, PodPdfError } from './client.js';
+
+export const VERSION = '1.0.0';
+
+const DOCS = 'https://apidocs.podpdf.com';
+const TERMINAL = new Set(['completed', 'partial_failed', 'failed', 'timeout']);
+
+const optionFields = {
+  format: z.enum(['A4', 'Letter', 'Legal', 'A3', 'A5', 'Tabloid']).optional().describe('Paper size (default A4)'),
+  landscape: z.boolean().optional().describe('Landscape orientation'),
+  margin: z.string().optional().describe('Margin for all four sides, e.g. "20mm" or "0.5in"'),
+  printBackground: z.boolean().optional().describe('Print background colours and images (default true)'),
+  scale: z.number().min(0.1).max(2).optional().describe('Render scale, 0.1 to 2 (default 1)'),
+  pageRanges: z.string().optional().describe('Pages to keep, e.g. "1-3, 5"'),
+};
+
+const savePath = z
+  .string()
+  .optional()
+  .describe('Optional local file path to save the PDF to, e.g. "./invoice.pdf". The download link is returned either way.');
+
+function ok(data, extra) {
+  const text = [extra, JSON.stringify(data, null, 2)].filter(Boolean).join('\n\n');
+  return { content: [{ type: 'text', text }], structuredContent: data };
+}
+
+function fail(err) {
+  const message =
+    err instanceof PodPdfError
+      ? [err.message, hint(err), err.details ? `Details: ${JSON.stringify(err.details)}` : null].filter(Boolean).join('\n')
+      : String(err?.message ?? err);
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+function hint(err) {
+  switch (err.code || err.status) {
+    case 'QUICKJOB_TIMEOUT':
+      return 'The document took over 30 seconds. Use start_long_job instead.';
+    case 'UPGRADE_REQUIRED':
+      return 'The account has no paid plan yet. Buy credits or subscribe at https://app.podpdf.com.';
+    case 'INSUFFICIENT_CREDITS':
+      return 'Out of credits. Top up at https://app.podpdf.com.';
+    case 401:
+      return 'Check PODPDF_API_KEY.';
+    default:
+      return null;
+  }
+}
+
+async function maybeSave(client, result, file) {
+  if (!file || !result?.download_url) return null;
+  const target = path.resolve(file);
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, await client.download(result.download_url));
+  return `Saved PDF to ${target}`;
+}
+
+function contentFor(input) {
+  const { input_type, content } = input;
+  if (input_type === 'url') return { url: content };
+  return { [input_type]: content };
+}
+
+export function createServer(client, { pollIntervalMs = 5000, maxWaitMs = 180000 } = {}) {
+  const server = new McpServer({ name: 'podpdf', version: VERSION });
+
+  server.registerTool(
+    'generate_pdf',
+    {
+      title: 'Generate PDF',
+      description:
+        `Convert HTML, Markdown or a public HTTPS URL to a PDF (up to 25 pages, 30 seconds). Returns a download link valid for 1 hour. Costs one PodPDF credit. Docs: ${DOCS}/api-reference/quickjob`,
+      inputSchema: {
+        input_type: z.enum(['html', 'markdown', 'url']).describe('What `content` is'),
+        content: z.string().min(1).describe('The HTML, the Markdown, or the https:// URL to convert'),
+        ...optionFields,
+        save_path: savePath,
+      },
+      annotations: { readOnlyHint: false, openWorldHint: true },
+    },
+    async ({ input_type, content, save_path, ...opts }) => {
+      try {
+        const result = await client.quickjob({ input_type, ...contentFor({ input_type, content }), options: buildOptions(opts) });
+        return ok(result, await maybeSave(client, result, save_path));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'render_template',
+    {
+      title: 'Render Template',
+      description:
+        `Fill a saved PodPDF template with data and render it to PDF. Template IDs are shown in the dashboard (Templates → Use via API). Docs: ${DOCS}/api-reference/templates`,
+      inputSchema: {
+        template_id: z.string().min(1).describe('Template ID from the PodPDF dashboard'),
+        data: z.record(z.any()).describe("Values for the template's fields; nested objects and arrays of objects for list fields. A dotted key such as \"customer.name\" is also accepted."),
+        filename: z.string().optional().describe('File name for the PDF'),
+        save_path: savePath,
+      },
+      annotations: { readOnlyHint: false, openWorldHint: true },
+    },
+    async ({ template_id, data, filename, save_path }) => {
+      try {
+        const result = await client.renderTemplate(template_id, { data: expandDottedKeys(data), ...(filename ? { filename } : {}) });
+        return ok(result, await maybeSave(client, result, save_path));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'start_long_job',
+    {
+      title: 'Start Long Job',
+      description:
+        `Queue a large HTML or Markdown document (up to 100 pages) for asynchronous rendering. Returns a job_id; set wait to true to poll until it finishes and return the download link. Docs: ${DOCS}/api-reference/longjob`,
+      inputSchema: {
+        input_type: z.enum(['html', 'markdown']).describe('What `content` is'),
+        content: z.string().min(1).describe('The HTML or Markdown to render'),
+        ...optionFields,
+        wait: z.boolean().optional().describe('Wait up to 3 minutes for the job to finish (default false)'),
+      },
+      annotations: { readOnlyHint: false, openWorldHint: true },
+    },
+    async ({ input_type, content, wait, ...opts }) => {
+      try {
+        const queued = await client.longjob({ input_type, [input_type]: content, options: buildOptions(opts) });
+        if (!wait) return ok(queued, 'Job queued. Check it with get_job, then fetch the PDF with get_download_link.');
+        const deadline = Date.now() + maxWaitMs;
+        let job = queued;
+        while (!TERMINAL.has(job.status) && Date.now() < deadline) {
+          await new Promise((r) => setTimeout(r, pollIntervalMs));
+          job = await client.getJob(queued.job_id);
+        }
+        if (job.status !== 'completed') {
+          return ok(job, TERMINAL.has(job.status) ? `Job ended with status ${job.status}.` : 'Still running; check again with get_job.');
+        }
+        return ok({ ...job, ...(await client.getDownloadLink(queued.job_id)) });
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'get_job',
+    {
+      title: 'Get Job',
+      description: `Get the status and details of a PodPDF job (queued, processing, completed, partial_failed, failed, timeout). Docs: ${DOCS}/api-reference/jobs`,
+      inputSchema: { job_id: z.string().min(1).describe('Job ID') },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    async ({ job_id }) => {
+      try {
+        return ok(await client.getJob(job_id));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'get_download_link',
+    {
+      title: 'Get Download Link',
+      description: `Get a fresh 1-hour download link for a finished job's stored output (long, bulk, merge/split, or stored quick and template jobs). Docs: ${DOCS}/api-reference/jobs`,
+      inputSchema: { job_id: z.string().min(1).describe('Job ID'), save_path: savePath },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    async ({ job_id, save_path }) => {
+      try {
+        const result = await client.getDownloadLink(job_id);
+        return ok(result, await maybeSave(client, result, save_path));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  return server;
+}