pdfops-mcp 0.3.2 → 0.3.4

package/README.md

@@ -10,6 +10,8 @@ Beside a local agent, tools operate on file paths, so PDF bytes never transit th
 
 ```bash
 claude mcp add pdfops -- npx -y pdfops-mcp
+# with a key:
+claude mcp add pdfops -e PDFOPS_API_KEY=pdfops_live_… -- npx -y pdfops-mcp
 ```
 
 **Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`.cursor/mcp.json`)
@@ -26,6 +28,23 @@ claude mcp add pdfops -- npx -y pdfops-mcp
 }
 ```
 
+**VS Code** (`.vscode/mcp.json`, note the `servers` key and `type`)
+
+```json
+{
+  "servers": {
+    "pdfops": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "pdfops-mcp"],
+      "env": { "PDFOPS_API_KEY": "pdfops_live_…" }
+    }
+  }
+}
+```
+
+Any other stdio client (Windsurf, Cline, Zed, your own agent): command `npx`, args `-y pdfops-mcp`. Per-client walkthrough and a real tool-call transcript: [pdfops.dev/mcp](https://pdfops.dev/mcp).
+
 `PDFOPS_API_KEY` is optional — without it you get the keyless trial (100 requests/IP/month). A free key (250/month, no card) takes one field at [pdfops.dev/pricing](https://pdfops.dev/pricing).
 
 ## Tools
@@ -42,11 +61,20 @@ claude mcp add pdfops -- npx -y pdfops-mcp
 
 A hosted MCP runtime executes this server on a machine where your agent's file paths do not exist. Nothing changes in the config — pass sources the server can reach and skip `output_path`:
 
-- **Inputs** (`pdf_path`, `pdf_paths`): an `https://` URL the server can fetch (≤50 MB), or a `data:application/pdf;base64,…` URI for small files.
+- **Inputs** (`pdf_path`, `pdf_paths`): an `https://` URL the server can fetch (≤4 MB per PDF, ≤4.5 MB per request — the API's limits), or a `data:application/pdf;base64,…` URI for small files.
 - **Outputs**: omit `output_path` and `pdf_fill` / `pdf_merge` / `pdf_invoice` return the PDF inline as an embedded `application/pdf` resource (`pdfops://filled.pdf`, …) that the client saves. With `output_path` set, the file is written where the *server* runs.
 
 Locally, absolute paths keep working exactly as before and remain the recommended form — bytes stay off the model context.
 
+## Example prompts
+
+- *"What fields does ~/forms/fw9.pdf have?"* → `pdf_inspect`
+- *"Fill ~/forms/fw9.pdf for Ada Lovelace, 12 Analytical Way, London; save it flattened as ~/out/w9-ada.pdf"* → `pdf_inspect`, then `pdf_fill` with `flatten: true`
+- *"Fill the onboarding form once per row of contractors.csv into ~/out/"* → one `pdf_inspect`, then `pdf_fill` per row
+- *"Merge ~/out/w9-ada.pdf, ~/docs/nda.pdf and ~/docs/cover.pdf into one packet, cover first"* → `pdf_merge`
+- *"Invoice Globex for 3 days of consulting at $650, 8.5% tax, due in 30 days"* → `pdf_invoice`
+- *"How many PDFops requests do I have left this month?"* → `pdfops_usage`
+
 ## Example agent flow
 
 > "Fill the W-9 template at ~/docs/w9.pdf for Ada Lovelace and merge it with ~/docs/cover.pdf"

package/dist/index.js

@@ -26,12 +26,25 @@ import { describeSource, pdfResult, resolveSource } from './source.js';
 // Version comes from package.json so the string MCP clients display can no
 // longer drift from the published one (0.2.0 shipped reporting 0.1.1).
 const { version } = createRequire(import.meta.url)('../package.json');
+const server = new McpServer({ name: 'pdfops', version });
+// Source attribution: every API call carries this server's version and the
+// MCP host app ("claude-ai/0.1.0", "cursor-vscode/1.0.0", …) taken from the
+// initialize handshake's clientInfo. Added via a fetch wrapper rather than
+// SDK options because clientInfo only exists after connect, and so this works
+// against the already-published pdfops-sdk 0.4.0.
 const client = new PdfOps({
     apiKey: process.env.PDFOPS_API_KEY,
     baseUrl: process.env.PDFOPS_BASE_URL,
     clientTag: 'mcp',
+    fetch: (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set('X-Pdfops-Client-Version', version);
+        const host = server.server.getClientVersion();
+        if (host)
+            headers.set('X-Pdfops-Client-Host', `${host.name}/${host.version}`);
+        return fetch(input, { ...init, headers });
+    },
 });
-const server = new McpServer({ name: 'pdfops', version });
 const SOURCE_DOC = 'PDF source: an absolute file path, an https:// URL, or a data:application/pdf;base64,… URI. Use a URL or data URI when this server runs remotely (Smithery, hosted gateways) where local paths do not exist.';
 const OUTPUT_DOC = 'Absolute path to write the result. Omit when running remotely: the PDF is then returned inline as an application/pdf resource for the client to save.';
 const errText = (e) => e instanceof PdfOpsError
@@ -69,10 +82,11 @@ server.registerTool('pdf_inspect', {
     outputSchema: {
         count: z.number().int().describe('Number of form fields found; 0 when the PDF has no fillable form'),
         hasXFA: z.boolean().describe('True for hybrid AcroForm/XFA documents, whose XFA layer is dropped when filled'),
+        truncated: z.boolean().describe('True when the form exceeded an API enumeration cap; fields is then a prefix, not the full list'),
         fields: z
             .array(z.object({
             name: z.string(),
-            type: z.string().describe('text, checkbox, radio, optionlist, or unsupported'),
+            type: z.string().describe('text, checkbox, dropdown, radio, optionlist, or unsupported'),
             readOnly: z.boolean(),
             value: z.string().optional(),
             options: z.array(z.string()).optional().describe('Permitted values for radio/dropdown/optionlist fields'),
@@ -162,8 +176,9 @@ server.registerTool('pdf_invoice', {
             invoice_number: z.string().optional(),
             date: z
                 .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
                 .optional()
-                .describe('Shown on the invoice; also pins metadata for determinism'),
+                .describe('Calendar date in YYYY-MM-DD form (other formats are rejected with invalid_date). 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(),

package/dist/source.js

@@ -14,8 +14,8 @@
 // Outputs mirror it: with `output_path` the PDF is written to disk; without it
 // the PDF comes back as an embedded application/pdf resource the client saves.
 import { readFile } from 'node:fs/promises';
-/** Upper bound on a fetched or inline PDF. The API rejects larger bodies anyway. */
-export const MAX_INPUT_BYTES = 50 * 1024 * 1024;
+/** Upper bound on a fetched PDF: the API's per-PDF cap, so oversize fails here with a clear message. */
+export const MAX_INPUT_BYTES = 4 * 1024 * 1024;
 export const classifySource = (s) => {
     if (/^data:/i.test(s))
         return 'data';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdfops-mcp",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "mcpName": "dev.pdfops/pdfops-mcp",
   "description": "MCP server for the PDFops API — 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": [