pdfops-mcp 0.2.0 → 0.3.0

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

@@ -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"

package/dist/index.js

@@ -1,133 +1,141 @@
 #!/usr/bin/env node
-#!/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 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 { writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+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';
+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.1.1"
+    apiKey: process.env.PDFOPS_API_KEY,
+    baseUrl: process.env.PDFOPS_BASE_URL,
+    clientTag: 'mcp',
 });
-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, per-field maxLength where declared \u2014 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 }) => {
+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'
+            : '')
+    : 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.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 }) => {
     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 resolveSource(pdf_path));
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (e) {
+        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 \u2192 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 }) => {
+});
+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'),
+}, 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)` }
-        ]
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: errText(e) }], isError: true };
+        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 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")
-  },
-  async ({ pdf_paths, output_path }) => {
+});
+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),
+}, 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) => resolveSource(p)));
+        const bytes = await client.merge(inputs);
+        return await emit(bytes, 'merged.pdf', `Merged ${pdf_paths.length} PDFs`, output_path);
     }
-  }
-);
-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 }) => {
+    catch (e) {
+        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),
+}, 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);
+        const name = invoice.invoice_number ? `invoice-${invoice.invoice_number}.pdf` : 'invoice.pdf';
+        return await emit(bytes, name, 'Invoice', output_path);
+    }
+    catch (e) {
+        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.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 fail(e);
     }
-  }
-);
+});
 const transport = new StdioServerTransport();
 await server.connect(transport);

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.0",
+  "version": "0.3.0",
   "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",
@@ -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,7 +32,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -38,5 +42,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pdfops/pdfops-mcp.git"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.0"
   }
-}
+}