pdfops-mcp 0.2.1 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 MCP server that gives AI agents deterministic PDF tools, backed by the [PDFops API](https://pdfops.dev): **inspect** AcroForm fields, **fill** forms, **merge** PDFs, and **generate invoices** — no Chromium, no native deps, nothing to host.
 
-Tools operate on local file paths, so PDF bytes never transit the model context: your agent says *"fill /tmp/form.pdf and save to /tmp/out.pdf"* and gets a one-line confirmation back.
+Beside a local agent, tools operate on file paths, so PDF bytes never transit the model context: your agent says *"fill /tmp/form.pdf and save to /tmp/out.pdf"* and gets a one-line confirmation back. Every PDF input also accepts an `https://` URL or a `data:application/pdf;base64,…` URI, and every output can be returned inline instead of written — which is what makes the server work on hosted runtimes (see below).
 
 ## Install
 
@@ -38,6 +38,15 @@ claude mcp add pdfops -- npx -y pdfops-mcp
 | `pdf_invoice` | Structured data → complete invoice PDF. Deterministic: same input, byte-identical output. |
 | `pdfops_usage` | Quota check for the configured key. |
 
+## Running remotely (Smithery, Glama hosted, cloud IDE gateways)
+
+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.
+- **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 agent flow
 
 > "Fill the W-9 template at ~/docs/w9.pdf for Ada Lovelace and merge it with ~/docs/cover.pdf"
@@ -50,4 +59,8 @@ claude mcp add pdfops -- npx -y pdfops-mcp
 
 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

@@ -1,141 +1,167 @@
 #!/usr/bin/env node
 // 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.
+// Design: tools take PDF *sources* and return files or inline PDFs.
+// Beside a local agent (npx pdfops-mcp) the filesystem is the natural
+// interface — "fill /tmp/form.pdf and save to /tmp/out.pdf" — and the PDF
+// bytes never transit the model context. On a hosted runtime (Smithery,
+// Glama hosted, cloud IDE gateways) the agent's paths do not exist on this
+// machine, so every source also accepts an https:// URL or a
+// data:application/pdf;base64 URI, and omitting output_path returns the
+// result inline as an application/pdf resource. See src/source.ts.
 //
 // 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 { 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';
+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 client = new PdfOps({
     apiKey: process.env.PDFOPS_API_KEY,
     baseUrl: process.env.PDFOPS_BASE_URL,
     clientTag: 'mcp',
 });
-const server = new McpServer({
-    name: 'pdfops',
-    version: '0.2.1', // keep in sync with package.json
-});
+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
     ? `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 }) => {
+    : e instanceof Error
+        ? e.message
+        : String(e);
+const fail = (e) => ({ content: [{ type: 'text', text: errText(e) }], isError: true });
+const emit = async (bytes, name, summary, output_path) => {
+    if (output_path)
+        await writeFile(output_path, bytes);
+    return pdfResult(bytes, name, summary, output_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 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.',
+    inputSchema: { pdf_path: z.string().describe(SOURCE_DOC) },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, async ({ pdf_path }) => {
     try {
-        const result = await client.inspect(await readFile(pdf_path));
+        const result = await client.inspect(await resolveSource(pdf_path));
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     }
     catch (e) {
-        return { content: [{ type: 'text', text: errText(e) }], isError: true };
+        return fail(e);
     }
 });
-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'),
+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).',
+    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'),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 }, async ({ pdf_path, fields, output_path, flatten }) => {
     try {
-        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)` },
-            ],
-        };
+        const bytes = await client.fillForm(await resolveSource(pdf_path), fields, { flatten });
+        return await emit(bytes, 'filled.pdf', `Filled ${describeSource(pdf_path)}`, output_path);
     }
     catch (e) {
-        return { content: [{ type: 'text', text: errText(e) }], isError: true };
+        return fail(e);
     }
 });
-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'),
+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.',
+    inputSchema: {
+        pdf_paths: z.array(z.string()).min(2).describe(`In order, each a ${SOURCE_DOC}`),
+        output_path: z.string().optional().describe(OUTPUT_DOC),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 }, async ({ pdf_paths, output_path }) => {
     try {
-        const inputs = await Promise.all(pdf_paths.map((p) => readFile(p)));
+        const inputs = await Promise.all(pdf_paths.map((p) => resolveSource(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)` },
-            ],
-        };
+        return await emit(bytes, 'merged.pdf', `Merged ${pdf_paths.length} PDFs`, output_path);
     }
     catch (e) {
-        return { content: [{ type: 'text', text: errText(e) }], isError: true };
+        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().describe('Absolute path to write the invoice PDF'),
+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.',
+    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),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
 }, 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)` },
-            ],
-        };
+        const name = invoice.invoice_number ? `invoice-${invoice.invoice_number}.pdf` : 'invoice.pdf';
+        return await emit(bytes, name, 'Invoice', output_path);
     }
     catch (e) {
-        return { content: [{ type: 'text', text: errText(e) }], isError: true };
+        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, reset date. Requires PDFOPS_API_KEY.',
+    inputSchema: {},
+    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) }] };
     }
     catch (e) {
-        return { content: [{ type: 'text', text: errText(e) }], isError: true };
+        return fail(e);
     }
 });
 const transport = new StdioServerTransport();

package/dist/source.js

@@ -0,0 +1,108 @@
+// PDF input/output plumbing shared by every tool.
+//
+// The server was designed around local file paths (bytes never transit the
+// model context). That is still the right default beside a local agent — but
+// every hosted MCP runtime (Smithery, Glama hosted, cloud IDE gateways) runs
+// this process on a machine where the agent's paths do not exist, so inspect/
+// fill/merge were broken by construction there (TASK-102). A "source" string is
+// now one of three things, told apart by prefix, with no schema change:
+//
+//   /abs/path/file.pdf                        read from disk (local default)
+//   https://host/file.pdf                     fetched (hosted default)
+//   data:application/pdf;base64,JVBERi0x...   decoded inline
+//
+// 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;
+export const classifySource = (s) => {
+    if (/^data:/i.test(s))
+        return 'data';
+    if (/^https?:\/\//i.test(s))
+        return 'url';
+    return 'path';
+};
+/** Short, safe label for tool output — never echoes inline payloads. */
+export const describeSource = (s) => {
+    switch (classifySource(s)) {
+        case 'data':
+            return 'inline data URI';
+        case 'url':
+            try {
+                return new URL(s).host + new URL(s).pathname;
+            }
+            catch {
+                return 'url';
+            }
+        default:
+            return s;
+    }
+};
+const decodeDataUri = (s) => {
+    const m = /^data:([^;,]*)((?:;[^;,]*)*),(.*)$/is.exec(s);
+    if (!m)
+        throw new Error('Malformed data: URI');
+    const params = m[2].toLowerCase();
+    if (!params.includes(';base64')) {
+        throw new Error('data: URI must be base64-encoded (data:application/pdf;base64,...)');
+    }
+    const bytes = Buffer.from(m[3].replace(/\s+/g, ''), 'base64');
+    if (bytes.byteLength === 0)
+        throw new Error('data: URI decoded to zero bytes');
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+};
+const fetchUrl = async (url, fetchImpl) => {
+    const res = await fetchImpl(url, {
+        redirect: 'follow',
+        signal: AbortSignal.timeout(30_000),
+        headers: { accept: 'application/pdf,*/*' },
+    });
+    if (!res.ok)
+        throw new Error(`Fetching ${describeSource(url)} failed: HTTP ${res.status}`);
+    const declared = Number(res.headers.get('content-length') ?? 0);
+    if (declared > MAX_INPUT_BYTES) {
+        throw new Error(`${describeSource(url)} is ${declared} bytes; limit is ${MAX_INPUT_BYTES}`);
+    }
+    const buf = new Uint8Array(await res.arrayBuffer());
+    if (buf.byteLength > MAX_INPUT_BYTES) {
+        throw new Error(`${describeSource(url)} is ${buf.byteLength} bytes; limit is ${MAX_INPUT_BYTES}`);
+    }
+    if (buf.byteLength === 0)
+        throw new Error(`${describeSource(url)} returned an empty body`);
+    return buf;
+};
+/** Resolve a source string (path | https URL | data: URI) to PDF bytes. */
+export const resolveSource = async (source, fetchImpl = fetch) => {
+    switch (classifySource(source)) {
+        case 'data':
+            return decodeDataUri(source);
+        case 'url':
+            return fetchUrl(source, fetchImpl);
+        default: {
+            const buf = await readFile(source);
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        }
+    }
+};
+/**
+ * Tool result for a produced PDF. With `wroteTo` (the caller already wrote the
+ * file) it is a one-line confirmation; without it the bytes travel back inline
+ * as an embedded application/pdf resource, which is what a hosted server must
+ * do since it has no filesystem the agent can reach.
+ */
+export const pdfResult = (bytes, name, summary, wroteTo) => {
+    if (wroteTo) {
+        return { content: [{ type: 'text', text: `${summary} written to ${wroteTo} (${bytes.byteLength} bytes)` }] };
+    }
+    const uri = `pdfops://${name}`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${summary} (${bytes.byteLength} bytes) returned inline as ${uri} — no output_path was given. Save the attached application/pdf resource; pass output_path to write to disk instead.`,
+            },
+            { type: 'resource', resource: { uri, mimeType: 'application/pdf', blob: Buffer.from(bytes).toString('base64') } },
+        ],
+    };
+};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pdfops-mcp",
-  "version": "0.2.1",
+  "version": "0.3.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.",
+  "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": [
     "mcp",
     "model-context-protocol",