pdfops-mcp 0.3.0 → 0.3.2

package/README.md

@@ -59,4 +59,8 @@ Locally, absolute paths keep working exactly as before and remain the recommende
 
 API docs: [pdfops.dev/docs](https://pdfops.dev/docs) · OpenAPI: [pdfops.dev/openapi.json](https://pdfops.dev/openapi.json) · Typed client: [`pdfops-sdk`](https://www.npmjs.com/package/pdfops-sdk) · Questions: hello@pdfops.dev
 
+## Privacy Policy
+
+This server runs on your machine and sends only what a tool call needs to the PDFops API (`https://pdfops.dev`): the PDF bytes you point it at, the field values you supply, and your API key if you set one. PDFops processes the request in memory and returns the result; it does not store your documents. Anonymous usage is metered per IP and per client tag (`mcp`) for quota and attribution only. Nothing is shared with third parties. The full policy, including retention and contact details, is at <https://pdfops.dev/privacy>. Questions: hello@pdfops.dev.
+
 MIT © PDFops

package/dist/index.js

@@ -17,6 +17,8 @@
 import { writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+// Tool annotations (title + readOnlyHint/destructiveHint) are mandatory for the
+// Claude Connectors Directory and help every client show what a tool does.
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { PdfOps, PdfOpsError } from 'pdfops-sdk';
@@ -41,30 +43,72 @@ 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.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(SOURCE_DOC) }, async ({ pdf_path }) => {
+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 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);
     }
 });
-server.tool('pdf_fill', '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).', {
-    pdf_path: z.string().describe(`Template ${SOURCE_DOC}`),
-    fields: z
-        .record(z.string())
-        .describe('Field name → string value (from pdf_inspect\'s fillTemplate)'),
-    output_path: z.string().optional().describe(OUTPUT_DOC),
-    flatten: z
-        .boolean()
-        .optional()
-        .describe('Bake values into page content and drop the AcroForm so fields are no longer editable'),
+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. 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
+            .record(z.string())
+            .describe('Field name → string value (from pdf_inspect\'s fillTemplate)'),
+        output_path: z.string().optional().describe(OUTPUT_DOC),
+        flatten: z
+            .boolean()
+            .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 {
         const bytes = await client.fillForm(await resolveSource(pdf_path), fields, { flatten });
@@ -74,9 +118,15 @@ server.tool('pdf_fill', 'Fill AcroForm form fields in a PDF and save or return t
         return fail(e);
     }
 });
-server.tool('pdf_merge', 'Merge two or more PDFs into one, in the order given, and save or return the result.', {
-    pdf_paths: z.array(z.string()).min(2).describe(`In order, each a ${SOURCE_DOC}`),
-    output_path: z.string().optional().describe(OUTPUT_DOC),
+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. 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 {
         const inputs = await Promise.all(pdf_paths.map((p) => resolveSource(p)));
@@ -87,37 +137,43 @@ server.tool('pdf_merge', 'Merge two or more PDFs into one, in the order given, a
         return fail(e);
     }
 });
-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().optional().describe(OUTPUT_DOC),
+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. 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({
+            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().optional().describe(OUTPUT_DOC),
+    },
+    outputSchema: PDF_OUTPUT,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 }, async ({ invoice, output_path }) => {
     try {
         const bytes = await client.invoice(invoice);
@@ -128,10 +184,23 @@ server.tool('pdf_invoice', 'Generate a complete, professionally laid-out invoice
         return fail(e);
     }
 });
-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.registerTool('pdfops_usage', {
+    title: 'Check PDFops quota',
+    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.0",
+  "version": "0.3.2",
   "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": [