pdfops-mcp 0.1.1 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PDFops (pdfops.dev)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -33,7 +33,7 @@ claude mcp add pdfops -- npx -y pdfops-mcp
 | Tool | What it does |
 |---|---|
 | `pdf_inspect` | List a PDF's form fields (names, types, options, values) + a paste-ready fill template. Call first on unfamiliar PDFs. |
-| `pdf_fill` | Fill AcroForm fields → write the filled PDF. |
+| `pdf_fill` | Fill AcroForm fields → write the filled PDF. Optional `flatten` bakes values in and drops the form. |
 | `pdf_merge` | Merge ≥2 PDFs in order → write the result. |
 | `pdf_invoice` | Structured data → complete invoice PDF. Deterministic: same input, byte-identical output. |
 | `pdfops_usage` | Quota check for the configured key. |

package/dist/index.js

@@ -1,131 +1,142 @@
 #!/usr/bin/env node
-import { readFile, writeFile } from "node:fs/promises";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { PdfOps, PdfOpsError } from "pdfops-sdk";
+// pdfops-mcp — MCP server exposing the PDFops API as agent tools.
+//
+// Design: tools take/return FILE PATHS, not base64 blobs. This server
+// runs locally (npx pdfops-mcp) beside the agent, so the filesystem is
+// the natural interface — an agent says "fill /tmp/form.pdf and save
+// to /tmp/out.pdf" and the PDF bytes never transit the model context.
+//
+// Env:
+//   PDFOPS_API_KEY  optional — free key from https://pdfops.dev/pricing
+//                   (250 req/mo; keyless works at 100 req/IP/mo)
+//   PDFOPS_BASE_URL optional — API origin override (testing)
+import { readFile, writeFile } from 'node:fs/promises';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { PdfOps, PdfOpsError } from 'pdfops-sdk';
 const client = new PdfOps({
-  apiKey: process.env.PDFOPS_API_KEY,
-  baseUrl: process.env.PDFOPS_BASE_URL,
-  clientTag: "mcp"
+    apiKey: process.env.PDFOPS_API_KEY,
+    baseUrl: process.env.PDFOPS_BASE_URL,
+    clientTag: 'mcp',
 });
 const server = new McpServer({
-  name: "pdfops",
-  version: "0.1.1"
+    name: 'pdfops',
+    version: '0.2.1', // keep in sync with package.json
 });
-const errText = (e) => e instanceof PdfOpsError ? `PDFops API error ${e.status} (${e.code}): ${e.message}` + (e.code === "rate_limited" ? " \u2014 get a free API key (250/mo) at https://pdfops.dev/pricing and set PDFOPS_API_KEY" : "") : String(e);
-server.tool(
-  "pdf_inspect",
-  "List a PDF's AcroForm form fields \u2014 names, types, options, current values \u2014 plus a paste-ready fillTemplate object for pdf_fill. A PDF with no form returns count 0. Call this FIRST when filling an unfamiliar PDF: you cannot fill fields whose names you do not know.",
-  { pdf_path: z.string().describe("Absolute path to the PDF to inspect") },
-  async ({ pdf_path }) => {
+const errText = (e) => e instanceof PdfOpsError
+    ? `PDFops API error ${e.status} (${e.code}): ${e.message}` +
+        (e.code === 'rate_limited'
+            ? ' — get a free API key (250/mo) at https://pdfops.dev/pricing and set PDFOPS_API_KEY'
+            : '')
+    : String(e);
+server.tool('pdf_inspect', 'List a PDF\'s AcroForm form fields — names, types, options, current values, per-field maxLength where declared — plus a paste-ready fillTemplate object for pdf_fill and a hasXFA flag (hybrid AcroForm/XFA inputs lose their XFA layer when filled). A PDF with no form returns count 0. Call this FIRST when filling an unfamiliar PDF: you cannot fill fields whose names you do not know, and values longer than a field\'s maxLength are rejected.', { pdf_path: z.string().describe('Absolute path to the PDF to inspect') }, async ({ pdf_path }) => {
     try {
-      const result = await client.inspect(await readFile(pdf_path));
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-    } catch (e) {
-      return { content: [{ type: "text", text: errText(e) }], isError: true };
+        const result = await client.inspect(await readFile(pdf_path));
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     }
-  }
-);
-server.tool(
-  "pdf_fill",
-  `Fill AcroForm form fields in a PDF and save the result. Field names must exist in the PDF (use pdf_inspect first). All values are strings; checkboxes take "true"/"false"; dropdown/radio/optionlist values must be one of the field's options.`,
-  {
-    pdf_path: z.string().describe("Absolute path to the template PDF"),
-    fields: z.record(z.string()).describe("Field name \u2192 string value (from pdf_inspect's fillTemplate)"),
-    output_path: z.string().describe("Absolute path to write the filled PDF")
-  },
-  async ({ pdf_path, fields, output_path }) => {
+    catch (e) {
+        return { content: [{ type: 'text', text: errText(e) }], isError: true };
+    }
+});
+server.tool('pdf_fill', 'Fill AcroForm form fields in a PDF and save the result. Field names must exist in the PDF (use pdf_inspect first). All values are strings; checkboxes take "true"/"false"; dropdown/radio/optionlist values must be one of the field\'s options; text values must respect the field\'s maxLength from pdf_inspect. Encrypted PDFs are rejected with decrypt advice (common for government blanks with an empty user password).', {
+    pdf_path: z.string().describe('Absolute path to the template PDF'),
+    fields: z
+        .record(z.string())
+        .describe('Field name → string value (from pdf_inspect\'s fillTemplate)'),
+    output_path: z.string().describe('Absolute path to write the filled PDF'),
+    flatten: z
+        .boolean()
+        .optional()
+        .describe('Bake values into page content and drop the AcroForm so fields are no longer editable'),
+}, async ({ pdf_path, fields, output_path, flatten }) => {
     try {
-      const bytes = await client.fillForm(await readFile(pdf_path), fields);
-      await writeFile(output_path, bytes);
-      return {
-        content: [
-          { type: "text", text: `Filled PDF written to ${output_path} (${bytes.byteLength} bytes)` }
-        ]
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: errText(e) }], isError: true };
+        const bytes = await client.fillForm(await readFile(pdf_path), fields, { flatten });
+        await writeFile(output_path, bytes);
+        return {
+            content: [
+                { type: 'text', text: `Filled PDF written to ${output_path} (${bytes.byteLength} bytes)` },
+            ],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: errText(e) }], isError: true };
     }
-  }
-);
-server.tool(
-  "pdf_merge",
-  "Merge two or more PDFs into one, in the order given, and save the result.",
-  {
-    pdf_paths: z.array(z.string()).min(2).describe("Absolute paths of the PDFs to merge, in order"),
-    output_path: z.string().describe("Absolute path to write the merged PDF")
-  },
-  async ({ pdf_paths, output_path }) => {
+});
+server.tool('pdf_merge', 'Merge two or more PDFs into one, in the order given, and save the result.', {
+    pdf_paths: z
+        .array(z.string())
+        .min(2)
+        .describe('Absolute paths of the PDFs to merge, in order'),
+    output_path: z.string().describe('Absolute path to write the merged PDF'),
+}, async ({ pdf_paths, output_path }) => {
     try {
-      const inputs = await Promise.all(pdf_paths.map((p) => readFile(p)));
-      const bytes = await client.merge(inputs);
-      await writeFile(output_path, bytes);
-      return {
-        content: [
-          { type: "text", text: `Merged ${pdf_paths.length} PDFs into ${output_path} (${bytes.byteLength} bytes)` }
-        ]
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: errText(e) }], isError: true };
+        const inputs = await Promise.all(pdf_paths.map((p) => readFile(p)));
+        const bytes = await client.merge(inputs);
+        await writeFile(output_path, bytes);
+        return {
+            content: [
+                { type: 'text', text: `Merged ${pdf_paths.length} PDFs into ${output_path} (${bytes.byteLength} bytes)` },
+            ],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: errText(e) }], isError: true };
     }
-  }
-);
-server.tool(
-  "pdf_invoice",
-  'Generate a complete, professionally laid-out invoice PDF from structured data \u2014 no template needed. Deterministic: the same input produces byte-identical output (safe to re-run). Note: without a paid PDFops key the output carries a small "Generated with pdfops.dev" footer line.',
-  {
-    invoice: z.object({
-      from: z.union([
-        z.string(),
-        z.object({ name: z.string(), lines: z.array(z.string()).optional() })
-      ]),
-      to: z.union([
-        z.string(),
-        z.object({ name: z.string(), lines: z.array(z.string()).optional() })
-      ]),
-      items: z.array(
-        z.object({
-          description: z.string(),
-          quantity: z.number().positive().optional(),
-          unit_price: z.number().nonnegative()
-        })
-      ).min(1).max(100),
-      invoice_number: z.string().optional(),
-      date: z.string().optional().describe("Shown on the invoice; also pins metadata for determinism"),
-      due: z.string().optional(),
-      currency: z.string().regex(/^[A-Z]{3}$/).optional(),
-      tax_rate: z.number().min(0).max(100).optional(),
-      notes: z.string().max(1e3).optional()
-    }).describe("Invoice data"),
-    output_path: z.string().describe("Absolute path to write the invoice PDF")
-  },
-  async ({ invoice, output_path }) => {
+});
+server.tool('pdf_invoice', 'Generate a complete, professionally laid-out invoice PDF from structured data — no template needed. Deterministic: the same input produces byte-identical output (safe to re-run). Note: without a paid PDFops key the output carries a small "Generated with pdfops.dev" footer line.', {
+    invoice: z
+        .object({
+        from: z.union([
+            z.string(),
+            z.object({ name: z.string(), lines: z.array(z.string()).optional() }),
+        ]),
+        to: z.union([
+            z.string(),
+            z.object({ name: z.string(), lines: z.array(z.string()).optional() }),
+        ]),
+        items: z
+            .array(z.object({
+            description: z.string(),
+            quantity: z.number().positive().optional(),
+            unit_price: z.number().nonnegative(),
+        }))
+            .min(1)
+            .max(100),
+        invoice_number: z.string().optional(),
+        date: z
+            .string()
+            .optional()
+            .describe('Shown on the invoice; also pins metadata for determinism'),
+        due: z.string().optional(),
+        currency: z.string().regex(/^[A-Z]{3}$/).optional(),
+        tax_rate: z.number().min(0).max(100).optional(),
+        notes: z.string().max(1000).optional(),
+    })
+        .describe('Invoice data'),
+    output_path: z.string().describe('Absolute path to write the invoice PDF'),
+}, async ({ invoice, output_path }) => {
     try {
-      const bytes = await client.invoice(invoice);
-      await writeFile(output_path, bytes);
-      return {
-        content: [
-          { type: "text", text: `Invoice written to ${output_path} (${bytes.byteLength} bytes)` }
-        ]
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: errText(e) }], isError: true };
+        const bytes = await client.invoice(invoice);
+        await writeFile(output_path, bytes);
+        return {
+            content: [
+                { type: 'text', text: `Invoice written to ${output_path} (${bytes.byteLength} bytes)` },
+            ],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: errText(e) }], isError: true };
     }
-  }
-);
-server.tool(
-  "pdfops_usage",
-  "Check the current PDFops API quota for the configured key: tier, limit, used, remaining, reset date. Requires PDFOPS_API_KEY.",
-  {},
-  async () => {
+});
+server.tool('pdfops_usage', 'Check the current PDFops API quota for the configured key: tier, limit, used, remaining, reset date. Requires PDFOPS_API_KEY.', {}, async () => {
     try {
-      const usage = await client.usage();
-      return { content: [{ type: "text", text: JSON.stringify(usage, null, 2) }] };
-    } catch (e) {
-      return { content: [{ type: "text", text: errText(e) }], isError: true };
+        const usage = await client.usage();
+        return { content: [{ type: 'text', text: JSON.stringify(usage, null, 2) }] };
     }
-  }
-);
+    catch (e) {
+        return { content: [{ type: 'text', text: errText(e) }], isError: true };
+    }
+});
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdfops-mcp",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "mcpName": "dev.pdfops/pdfops-mcp",
   "description": "MCP server for the PDFops API \u2014 give AI agents deterministic PDF tools: inspect AcroForm fields, fill forms, merge PDFs, and generate invoices. Works with Claude Code, Claude Desktop, Cursor, and any MCP client.",
   "keywords": [
@@ -20,6 +20,10 @@
   "author": "PDFops <hello@pdfops.dev> (https://pdfops.dev)",
   "license": "MIT",
   "type": "module",
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "prepare": "npm run build"
+  },
   "bin": {
     "pdfops-mcp": "./dist/index.js"
   },
@@ -28,15 +32,19 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "pdfops-sdk": "^0.3.0",
+    "pdfops-sdk": "^0.4.0",
     "zod": "^3.23.0"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pdfops/pdfops-mcp.git"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.0"
   }
-}
+}