pdfops-mcp 0.3.1 → 0.3.2

package/dist/index.js

@@ -43,20 +43,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 +95,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 +107,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 +120,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 +139,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 +172,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 +186,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.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": [