pdfpipe-mcp-server 0.1.0 → 0.3.0

package/dist/index.js

@@ -2,10 +2,10 @@
 /**
  * MCP server for PDFPipe (https://pdfpipe.xyz).
  *
- * Exposes a single high-value tool, `pdfpipe_generate_pdf`, that turns HTML or
- * a public URL into a PDF document via the PDFPipe REST API and writes it to a
- * path the agent chooses. Built so an AI agent can produce an invoice, report,
- * or certificate in one tool call.
+ * Tools:
+ *   pdfpipe_generate_pdf   — render HTML or URL to a PDF file
+ *   pdfpipe_list_documents — list archived PDFs (requires store: true on generate)
+ *   pdfpipe_get_document   — retrieve an archived PDF by document ID
  *
  * Auth: set PDFPIPE_API_KEY. Override the host with PDFPIPE_BASE_URL.
  */
@@ -47,6 +47,37 @@ const GeneratePdfInput = z
         .string()
         .default("1cm")
         .describe("Uniform page margin as a CSS length, e.g. '1cm', '0', '0.5in'. Default '1cm'."),
+    store: z
+        .boolean()
+        .default(false)
+        .describe("If true, persist the PDF for later retrieval via pdfpipe_get_document. " +
+        "Returns document_id, document_url, and document_expires. " +
+        "Retention by plan: hobby 1 day, starter 30 days, growth 1 year, scale 2 years."),
+    filename: z
+        .string()
+        .max(200)
+        .optional()
+        .describe("Filename to associate with the stored document. Only used when store is true."),
+    header_html: z
+        .string()
+        .optional()
+        .describe("HTML rendered as a running page header. Class names .pageNumber, .totalPages, .date, .title, .url are substituted by the renderer on each page."),
+    footer_html: z
+        .string()
+        .optional()
+        .describe("HTML rendered as a running page footer. Same class substitution as header_html."),
+    tabular_nums: z
+        .boolean()
+        .default(false)
+        .describe("Force consistent digit widths via font-variant-numeric: tabular-nums. Fixes column misalignment in tables and invoices. Default false."),
+    deduplicate_images: z
+        .boolean()
+        .default(false)
+        .describe("Merge identical image XObjects in the output PDF. Reduces file size when the same image (e.g. a logo) appears on many pages. Default false."),
+    pdf_a: z
+        .boolean()
+        .default(false)
+        .describe("Add PDF/A-1b XMP metadata to the document (best-effort conformance). Default false."),
 })
     .strict();
 const GeneratePdfOutput = z.object({
@@ -55,6 +86,9 @@ const GeneratePdfOutput = z.object({
     plan: z.string().optional(),
     usage: z.number().optional(),
     limit: z.number().optional(),
+    document_id: z.string().optional().describe("Archive ID (present when store: true)"),
+    document_url: z.string().optional().describe("Retrieval URL (present when store: true)"),
+    document_expires: z.string().optional().describe("ISO 8601 expiry timestamp (present when store: true)"),
 });
 function apiKey() {
     const key = process.env.PDFPIPE_API_KEY;
@@ -110,13 +144,15 @@ function describeError(error) {
 }
 const server = new McpServer({
     name: "pdfpipe-mcp-server",
-    version: "0.1.0",
+    version: "0.3.0",
 });
 server.registerTool("pdfpipe_generate_pdf", {
     title: "Generate a PDF with PDFPipe",
     description: `Generate a PDF document from HTML or a public URL using the PDFPipe API, and save it to disk.
 
-Use this to produce invoices, receipts, reports, certificates, statements, or any document, from HTML you compose or a web page you point at. The rendering runs server-side in a sandboxed Chromium, so the calling agent does not need a browser.
+Use this to produce invoices, receipts, reports, certificates, statements, or any document, from HTML you compose or a web page you point at. The rendering runs server-side in a sandboxed browser, so the calling agent does not need a browser.
+
+Pass store: true to persist the PDF and receive a document_id for later retrieval via pdfpipe_get_document.
 
 Args:
   - html (string, optional): Raw HTML to render. Provide html OR url, not both.
@@ -125,21 +161,15 @@ Args:
   - format ('A4'|'A3'|'A5'|'Letter'|'Legal'|'Tabloid', optional): Page size, default 'A4'.
   - landscape (boolean, optional): Landscape orientation, default false.
   - margin (string, optional): CSS length page margin, e.g. '1cm', '0', default '1cm'.
+  - header_html (string, optional): HTML for a running page header. .pageNumber, .totalPages, .date classes substituted per page.
+  - footer_html (string, optional): HTML for a running page footer. Same substitution as header_html.
+  - tabular_nums (boolean, optional): Force consistent digit widths for tables/invoices. Default false.
+  - deduplicate_images (boolean, optional): Merge duplicate image XObjects to shrink file size. Default false.
+  - pdf_a (boolean, optional): Add PDF/A-1b metadata (best-effort). Default false.
+  - store (boolean, optional): Persist the PDF for later retrieval, default false.
+  - filename (string, optional): Filename for the stored document (used with store: true).
 
-Returns JSON:
-  {
-    "output_path": string,   // absolute path the PDF was written to
-    "size_bytes": number,    // size of the generated PDF
-    "plan": string,          // the API key's plan (e.g. "hobby")
-    "usage": number,         // documents used this month after this call
-    "limit": number          // monthly document limit for the plan
-  }
-
-Examples:
-  - "Make an invoice PDF": html="<h1>Invoice #4012</h1>...", output_path="./invoice-4012.pdf"
-  - "Save this web page as PDF": url="https://example.com/report", output_path="./report.pdf"
-
-Errors return a message starting with "Error:" explaining the cause (bad key, limit reached, render failure, unreachable API).`,
+Returns JSON with output_path, size_bytes, plan, usage, limit, and optionally document_id/document_url/document_expires when store is true.`,
     inputSchema: GeneratePdfInput.shape,
     outputSchema: GeneratePdfOutput.shape,
     annotations: {
@@ -163,14 +193,22 @@ Errors return a message starting with "Error:" explaining the cause (bad key, li
         };
     }
     try {
-        const response = await axios.post(`${BASE_URL}/v1/pdf`, {
+        const body = {
             ...(params.html ? { html: params.html } : { url: params.url }),
             options: {
                 format: params.format,
                 landscape: params.landscape,
                 margin: params.margin,
+                ...(params.header_html ? { header_html: params.header_html } : {}),
+                ...(params.footer_html ? { footer_html: params.footer_html } : {}),
+                ...(params.tabular_nums ? { tabular_nums: true } : {}),
+                ...(params.deduplicate_images ? { deduplicate_images: true } : {}),
+                ...(params.pdf_a ? { pdf_a: true } : {}),
             },
-        }, {
+            ...(params.store ? { store: true } : {}),
+            ...(params.filename ? { filename: params.filename } : {}),
+        };
+        const response = await axios.post(`${BASE_URL}/v1/pdf`, body, {
             responseType: "arraybuffer",
             timeout: REQUEST_TIMEOUT_MS,
             headers: {
@@ -190,12 +228,16 @@ Errors return a message starting with "Error:" explaining the cause (bad key, li
             const n = Number(v);
             return Number.isFinite(n) ? n : undefined;
         };
+        const str = (v) => (typeof v === "string" && v ? v : undefined);
         const output = {
             output_path: absPath,
             size_bytes: buffer.length,
-            plan: h["x-pdfpipe-plan"] ?? undefined,
+            plan: str(h["x-pdfpipe-plan"]),
             usage: num(h["x-pdfpipe-usage"]),
             limit: num(h["x-pdfpipe-limit"]),
+            document_id: str(h["x-pdfpipe-document-id"]),
+            document_url: str(h["x-pdfpipe-document-url"]),
+            document_expires: str(h["x-pdfpipe-document-expires"]),
         };
         return {
             content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
@@ -209,6 +251,62 @@ Errors return a message starting with "Error:" explaining the cause (bad key, li
         };
     }
 });
+server.registerTool("pdfpipe_list_documents", {
+    title: "List archived PDFs",
+    description: "List PDFs previously stored with store: true. Returns up to 100 documents per page, newest first. Use the next_before cursor for pagination.",
+    inputSchema: z.object({
+        limit: z.number().int().min(1).max(100).default(100).describe("Max documents to return (1-100)."),
+        before: z.string().optional().describe("ISO 8601 cursor: return documents created before this timestamp. Use next_before from a previous response."),
+    }).shape,
+    annotations: { readOnlyHint: true },
+}, async (params) => {
+    try {
+        const qs = new URLSearchParams({ limit: String(params.limit) });
+        if (params.before) qs.set("before", params.before);
+        const res = await axios.get(`${BASE_URL}/v1/documents?${qs}`, {
+            timeout: REQUEST_TIMEOUT_MS,
+            headers: { Authorization: `Bearer ${apiKey()}` },
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+            structuredContent: res.data,
+        };
+    }
+    catch (error) {
+        return { isError: true, content: [{ type: "text", text: describeError(error) }] };
+    }
+});
+server.registerTool("pdfpipe_get_document", {
+    title: "Retrieve an archived PDF",
+    description: "Download a previously archived PDF by its document_id and save it to disk.",
+    inputSchema: z.object({
+        document_id: z.string().min(1).describe("The document_id returned by pdfpipe_generate_pdf when store was true."),
+        output_path: z.string().min(1).describe("Filesystem path to write the PDF to. Parent dirs are created."),
+    }).shape,
+    annotations: { readOnlyHint: false },
+}, async (params) => {
+    try {
+        const res = await axios.get(`${BASE_URL}/v1/documents/${encodeURIComponent(params.document_id)}`, {
+            responseType: "arraybuffer",
+            timeout: REQUEST_TIMEOUT_MS,
+            headers: { Authorization: `Bearer ${apiKey()}`, Accept: "application/pdf" },
+        });
+        const buffer = Buffer.from(res.data);
+        const absPath = isAbsolute(params.output_path)
+            ? params.output_path
+            : resolve(process.cwd(), params.output_path);
+        mkdirSync(dirname(absPath), { recursive: true });
+        writeFileSync(absPath, buffer);
+        const output = { output_path: absPath, size_bytes: buffer.length };
+        return {
+            content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+            structuredContent: output,
+        };
+    }
+    catch (error) {
+        return { isError: true, content: [{ type: "text", text: describeError(error) }] };
+    }
+});
 async function main() {
     // Fail fast with a clear message if the key is missing.
     if (!process.env.PDFPIPE_API_KEY) {
@@ -223,4 +321,3 @@ main().catch((error) => {
     console.error("Fatal:", error);
     process.exit(1);
 });
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,32 +1,38 @@
-{
-  "name": "pdfpipe-mcp-server",
-  "version": "0.1.0",
-  "description": "MCP server for PDFPipe. Generate PDF documents (invoices, reports, certificates) from HTML or a URL in one tool call.",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "pdfpipe-mcp-server": "dist/index.js"
-  },
-  "files": ["dist"],
-  "author": "Johin Johny <johinjohny144@gmail.com>",
-  "license": "MIT",
-  "keywords": ["mcp", "pdf", "pdf-generation", "html-to-pdf", "pdfpipe", "ai-agents"],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx watch src/index.ts"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.6.1",
-    "axios": "^1.7.9",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
-  }
-}
+{
+  "name": "pdfpipe-mcp-server",
+  "version": "0.3.0",
+  "description": "MCP server for PDFPipe. Generate PDF documents (invoices, reports, certificates) from HTML or a URL in one tool call.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "pdfpipe-mcp-server": "dist/index.js"
+  },
+  "files": ["dist"],
+  "author": "Johin Johny <johinjohny144@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://pdfpipe.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Johin2/pdfpipe-libraries.git",
+    "directory": "mcp"
+  },
+  "keywords": ["mcp", "pdf", "pdf-generation", "html-to-pdf", "pdfpipe", "ai-agents"],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "axios": "^1.7.9",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}