pdfops-mcp 0.3.1 → 0.3.3

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
@@ -47,6 +66,15 @@ A hosted MCP runtime executes this server on a machine where your agent's file p
 
 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
@@ -43,20 +56,51 @@ const errText = (e) => e instanceof PdfOpsError
         ? e.message
         : String(e);
 const fail = (e) => ({ content: [{ type: 'text', text: errText(e) }], isError: true });
+// Declared as outputSchema on every PDF-emitting tool so an agent knows what it
+// gets back without calling first. Both delivery modes are represented: a path
+// when output_path was given, a pdfops:// resource uri when it was not.
+const PDF_OUTPUT = {
+    bytes: z.number().int().describe('Size of the produced PDF in bytes'),
+    output_path: z.string().optional().describe('Absolute path written, when output_path was supplied'),
+    resource_uri: z.string().optional().describe('pdfops:// uri of the inline application/pdf resource, when output_path was omitted'),
+};
 const emit = async (bytes, name, summary, output_path) => {
     if (output_path)
         await writeFile(output_path, bytes);
-    return pdfResult(bytes, name, summary, output_path);
+    const base = pdfResult(bytes, name, summary, output_path);
+    return {
+        ...base,
+        structuredContent: output_path
+            ? { bytes: bytes.byteLength, output_path }
+            : { bytes: bytes.byteLength, resource_uri: `pdfops://${name}` },
+    };
 };
 server.registerTool('pdf_inspect', {
     title: 'Inspect PDF form fields',
-    description: '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.',
+    description: '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 fillable form returns count 0. Read-only: the PDF is fetched or read but never modified. Call this FIRST when filling an unfamiliar PDF, since pdf_fill rejects unknown field names and over-length values.',
     inputSchema: { pdf_path: z.string().describe(SOURCE_DOC) },
+    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'),
+        fields: z
+            .array(z.object({
+            name: z.string(),
+            type: z.string().describe('text, checkbox, 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'),
+            checked: z.boolean().optional(),
+            maxLength: z.number().int().optional().describe('Longer values are rejected by pdf_fill'),
+            raw: z.unknown().optional(),
+        }))
+            .describe('One entry per form field, in document order'),
+        fillTemplate: z.record(z.string()).describe('Field name to empty-or-current value, ready to edit and pass to pdf_fill'),
+    },
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 }, async ({ pdf_path }) => {
     try {
         const result = await client.inspect(await resolveSource(pdf_path));
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: { ...result } };
     }
     catch (e) {
         return fail(e);
@@ -64,7 +108,7 @@ server.registerTool('pdf_inspect', {
 });
 server.registerTool('pdf_fill', {
     title: 'Fill PDF form',
-    description: 'Fill AcroForm form fields in a PDF and save or return 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).',
+    description: 'Fill AcroForm form fields in a PDF and save or return 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. The source PDF is never modified. Returns the filled PDF written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. Encrypted PDFs are rejected with decrypt advice (common for government blanks with an empty user password), and a rejected fill writes no file at all.',
     inputSchema: {
         pdf_path: z.string().describe(`Template ${SOURCE_DOC}`),
         fields: z
@@ -76,6 +120,7 @@ server.registerTool('pdf_fill', {
             .optional()
             .describe('Bake values into page content and drop the AcroForm so fields are no longer editable'),
     },
+    outputSchema: PDF_OUTPUT,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 }, async ({ pdf_path, fields, output_path, flatten }) => {
     try {
@@ -88,11 +133,12 @@ server.registerTool('pdf_fill', {
 });
 server.registerTool('pdf_merge', {
     title: 'Merge PDFs',
-    description: 'Merge two or more PDFs into one, in the order given, and save or return the result.',
+    description: 'Merge two or more PDFs into one, in the order given, and save or return the result. Source files are read only and never modified; an existing file at output_path is overwritten. Returns the merged PDF written to output_path, or inline as an application/pdf resource when output_path is omitted. This tool only concatenates whole documents: it does not reorder, rotate or delete pages within them, and it does not fill forms — use pdf_fill for a fillable form and pdf_invoice to build a document from data. An unreadable or rejected input fails with an error and writes no file, so a partial merge is never left behind.',
     inputSchema: {
         pdf_paths: z.array(z.string()).min(2).describe(`In order, each a ${SOURCE_DOC}`),
         output_path: z.string().optional().describe(OUTPUT_DOC),
     },
+    outputSchema: PDF_OUTPUT,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 }, async ({ pdf_paths, output_path }) => {
     try {
@@ -106,7 +152,7 @@ server.registerTool('pdf_merge', {
 });
 server.registerTool('pdf_invoice', {
     title: 'Generate invoice PDF',
-    description: '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.',
+    description: '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. Returns the invoice written to output_path, or inline as an application/pdf resource when output_path is omitted; an existing file at output_path is overwritten. Use this when you have invoice DATA and no document; if you already have an invoice PDF or a fillable template to populate, use pdf_fill instead.',
     inputSchema: {
         invoice: z
             .object({
@@ -139,6 +185,7 @@ server.registerTool('pdf_invoice', {
             .describe('Invoice data'),
         output_path: z.string().optional().describe(OUTPUT_DOC),
     },
+    outputSchema: PDF_OUTPUT,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 }, async ({ invoice, output_path }) => {
     try {
@@ -152,13 +199,21 @@ server.registerTool('pdf_invoice', {
 });
 server.registerTool('pdfops_usage', {
     title: 'Check PDFops quota',
-    description: 'Check the current PDFops API quota for the configured key: tier, limit, used, remaining, reset date. Requires PDFOPS_API_KEY.',
+    description: 'Check the current PDFops API quota for the configured key: tier, limit, used, remaining, the billing period, and the reset timestamp. Read-only and safe to call before a batch to confirm there is headroom. Requires PDFOPS_API_KEY.',
     inputSchema: {},
+    outputSchema: {
+        tier: z.string().describe('Plan name, e.g. free'),
+        limit: z.number().int().describe('Calls allowed in the current period'),
+        used: z.number().int(),
+        remaining: z.number().int(),
+        period: z.string().describe('Billing period the counts belong to, YYYY-MM'),
+        resets_at: z.string().describe('ISO 8601 timestamp when used resets to 0'),
+    },
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 }, async () => {
     try {
         const usage = await client.usage();
-        return { content: [{ type: 'text', text: JSON.stringify(usage, null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify(usage, null, 2) }], structuredContent: { ...usage } };
     }
     catch (e) {
         return fail(e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdfops-mcp",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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": [