@exactpdf/mcp 0.2.10 → 0.2.12

package/README.md

@@ -8,9 +8,11 @@ Use it when an agent needs to inspect, merge, split, rotate, compress, extract,
 
 **Design principle:** every tool should work on first run, explain credit cost before risky work, return a local output path for files, and expose precise HTTP/API errors when something fails.
 
+Developer quickstart: [https://exactpdf.com/developers](https://exactpdf.com/developers)
+
 ## Setup
 
-1. Create an API key at [exactpdf.com](https://exactpdf.com) (Max → API keys).
+1. Create an API key at [max.exactpdf.com/account](https://max.exactpdf.com/account). New accounts get **20 free test credits**. Buy one-time credit packs only after the workflow works; no subscription is required for API/MCP.
 2. Export:
 
 ```bash
@@ -60,16 +62,26 @@ Safe first run:
 
 Document outputs are saved to `EXACTPDF_API_OUTPUT_DIR` or your OS temp directory. Paid document tools consume credits only on successful output. Async speech jobs are metered by generated minutes.
 
+Credit model:
+
+- Free probes: checklist, account, PDF info, voice preview, speech cost estimate, and job polling.
+- New accounts: 20 free test credits for API/MCP workflows.
+- Standard document tools: 1 credit only after a successful output.
+- Long audio jobs: metered by generated minutes.
+- One-time packs: available in Max Account when you need more; no subscription required for API/MCP.
+
 | Tool | Endpoint | Credits |
 |------|----------|--------:|
 | `exactpdf_first_run_checklist` | local guidance | 0 |
 | `exactpdf_account` | GET /api/v1/account | 0 |
 | `exactpdf_pdf_info` | POST /api/v1/pdf-info | 0 |
 | `exactpdf_merge_pdfs` | POST /api/v1/merge | 1 |
+| `exactpdf_merge_and_compress_pdfs` | POST /api/v1/merge-compress | 1 |
 | `exactpdf_split_pdf` | POST /api/v1/split | 1 |
 | `exactpdf_rotate_pdf` | POST /api/v1/rotate | 1 |
 | `exactpdf_compress_pdf` | POST /api/v1/compress | 1 |
 | `exactpdf_images_to_pdf` | POST /api/v1/images-to-pdf | 1 |
+| `exactpdf_images_to_pdf_and_compress` | POST /api/v1/images-to-pdf-compress | 1 |
 | `exactpdf_extract_text` | POST /api/v1/extract-text | 1 |
 | `exactpdf_pdf_structured_markdown` | POST /api/v1/pdf-structured-markdown | 1 |
 | `exactpdf_estimate_speech_cost` | local estimate | 0 |
@@ -149,6 +161,7 @@ The package must exist on the public npm registry before the MCP Registry can ve
 
 ## Docs
 
+- [https://exactpdf.com/developers](https://exactpdf.com/developers)
 - [https://exactpdf.com/docs/api](https://exactpdf.com/docs/api)
 
 ## License

package/dist/run.d.ts

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 /**
  * ExactPDF MCP — stdio server for Cursor / Claude Desktop / Codex.
- * Requires EXACTPDF_API_KEY (sk_live_…) from exactpdf.com (Max dashboard → API keys).
+ * Requires EXACTPDF_API_KEY (sk_live_…) from max.exactpdf.com/account.
+ * New accounts get free test credits; one-time credit packs are available
+ * after the first workflow works.
  *
+ * @see https://exactpdf.com/developers
  * @see https://exactpdf.com/docs/api
  */
 export {};

package/dist/run.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 /**
  * ExactPDF MCP — stdio server for Cursor / Claude Desktop / Codex.
- * Requires EXACTPDF_API_KEY (sk_live_…) from exactpdf.com (Max dashboard → API keys).
+ * Requires EXACTPDF_API_KEY (sk_live_…) from max.exactpdf.com/account.
+ * New accounts get free test credits; one-time credit packs are available
+ * after the first workflow works.
  *
+ * @see https://exactpdf.com/developers
  * @see https://exactpdf.com/docs/api
  */
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
@@ -20,12 +23,12 @@ function outputDir() {
 function requireKey() {
     const k = process.env.EXACTPDF_API_KEY?.trim();
     if (!k) {
-        throw new Error('EXACTPDF_API_KEY is not set. Create a key at exactpdf.com (Max → API keys), then export EXACTPDF_API_KEY=sk_live_…');
+        throw new Error('EXACTPDF_API_KEY is not set. Create a key with free test credits at https://max.exactpdf.com/account, then export EXACTPDF_API_KEY=sk_live_…. Quickstart: https://exactpdf.com/developers');
     }
     return k;
 }
-const server = new McpServer({ name: 'exactpdf', version: '0.2.10' }, {
-    instructions: 'ExactPDF turns local PDFs into production outputs for agents: inspect metadata, merge/split/rotate/compress, extract text/structured Markdown, create voice previews, and queue async PDF speech/audiobook/translation/presentation narration jobs. Start with exactpdf_first_run_checklist, then exactpdf_account and exactpdf_pdf_info before paid work. Free tools: first-run checklist, account, pdf-info, voice-preview, speech cost estimate. Standard document tools cost 1 credit on success. Async speech jobs are metered by generated minutes. Use absolute local file paths; binary outputs are saved to EXACTPDF_API_OUTPUT_DIR or the OS temp directory. For async jobs, submit first, then poll exactpdf_get_speech_job, then download with exactpdf_download_audio when succeeded.',
+const server = new McpServer({ name: 'exactpdf', version: '0.2.12' }, {
+    instructions: 'ExactPDF turns local PDFs into production outputs for agents: inspect metadata, merge/split/rotate/compress, create portal-ready merge/images workflows, extract text/structured Markdown, create voice previews, and queue async PDF speech/audiobook/translation/presentation narration jobs. Start with exactpdf_first_run_checklist, then exactpdf_account and exactpdf_pdf_info before paid work. New users can create a key with free test credits at https://max.exactpdf.com/account; developer quickstart: https://exactpdf.com/developers. Free tools: first-run checklist, account, pdf-info, voice-preview, speech cost estimate. Standard document tools cost 1 credit on success, including launch portal-ready workflows. Async speech jobs are metered by generated minutes. Use absolute local file paths; binary outputs are saved to EXACTPDF_API_OUTPUT_DIR or the OS temp directory. For async jobs, submit first, then poll exactpdf_get_speech_job, then download with exactpdf_download_audio when succeeded.',
 });
 async function saveBinaryFromResponse(res, prefix, fallbackExt) {
     const buf = Buffer.from(await res.arrayBuffer());
@@ -47,6 +50,16 @@ function extensionFromContentType(contentType, fallback) {
         return 'pdf';
     return fallback;
 }
+function targetStatus(res) {
+    const target = res.headers.get('x-target-bytes');
+    if (!target)
+        return 'No target_bytes requested.';
+    const reached = res.headers.get('x-target-reached') ?? 'unknown';
+    const original = res.headers.get('x-original-bytes') ?? '?';
+    const output = res.headers.get('x-output-bytes') ?? '?';
+    const mode = res.headers.get('x-compression-mode') ?? 'best_effort';
+    return `Target bytes: ${target}\nTarget reached: ${reached}\nOriginal bytes: ${original}\nOutput bytes: ${output}\nCompression mode: ${mode}`;
+}
 server.registerTool('exactpdf_first_run_checklist', {
     description: 'Return the safest first-run sequence for ExactPDF MCP clients, including API key setup, free probe tools, credit rules, output directory behavior, and docs links. Free; no API key required.',
     inputSchema: z.object({}),
@@ -58,7 +71,8 @@ server.registerTool('exactpdf_first_run_checklist', {
                 ok: true,
                 setup: {
                     required_env: 'EXACTPDF_API_KEY=sk_live_...',
-                    create_key_url: `${BASE}/max/account`,
+                    create_key_url: 'https://max.exactpdf.com/account',
+                    developer_quickstart: `${BASE}/developers`,
                     optional_output_dir: 'EXACTPDF_API_OUTPUT_DIR=/absolute/output/folder',
                     docs: `${BASE}/docs/api`,
                     openapi: `${BASE}/openapi.json`,
@@ -71,7 +85,10 @@ server.registerTool('exactpdf_first_run_checklist', {
                 ],
                 credit_model: {
                     free: ['exactpdf_first_run_checklist', 'exactpdf_account', 'exactpdf_pdf_info', 'exactpdf_voice_preview', 'exactpdf_estimate_speech_cost', 'job polling'],
+                    starter_trial: 'New accounts get 20 free test credits for API/MCP workflows.',
                     standard_document_tools: '1 credit only after successful output',
+                    credit_packs: 'Buy one-time credit packs when the workflow works; subscription is not required for API/MCP.',
+                    launch_portal_ready_workflows: '1 credit on successful output: exactpdf_merge_and_compress_pdfs, exactpdf_images_to_pdf_and_compress',
                     speech_audiobook_presentation: '1 credit per generated minute',
                     translate_and_speak: '3 credits per generated minute',
                 },
@@ -101,6 +118,44 @@ server.registerTool('exactpdf_account', {
         content: [{ type: 'text', text: `HTTP ${res.status}\n${text}` }],
     };
 });
+server.registerTool('exactpdf_merge_and_compress_pdfs', {
+    description: 'Portal-ready workflow: merge 2-20 local PDFs in order, then best-effort repack/compress the final PDF for an upload limit. Costs 1 launch credit on success. Returns measured output size and whether target_bytes was reached; exact target compression for image-heavy PDFs may require Max/browser workflows.',
+    inputSchema: z.object({
+        paths: z.array(z.string()).min(2).describe('Absolute paths to PDF files on this machine, in merge order.'),
+        target_bytes: z.number().int().positive().optional().describe('Optional upload limit, e.g. 1048576 for 1MB or 2097152 for 2MB.'),
+    }),
+}, async ({ paths, target_bytes }) => {
+    const key = requireKey();
+    const form = new FormData();
+    for (const p of paths) {
+        const buf = await readFile(p);
+        form.append('file', new Blob([buf], { type: 'application/pdf' }), basename(p));
+    }
+    if (typeof target_bytes === 'number')
+        form.append('target_bytes', String(target_bytes));
+    const res = await fetch(`${BASE}/api/v1/merge-compress`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}` },
+        body: form,
+    });
+    const credits = res.headers.get('x-credits-remaining') ?? '?';
+    if (!res.ok) {
+        const errBody = await res.text();
+        return {
+            content: [{ type: 'text', text: `merge-compress failed HTTP ${res.status}. Credits: ${credits}\n${errBody.slice(0, 8000)}` }],
+            isError: true,
+        };
+    }
+    const outPath = await saveBinaryFromResponse(res, 'exactpdf-merged-compressed', 'pdf');
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Merged and best-effort compressed ${paths.length} PDFs → ${outPath}\nCredits remaining: ${credits}\n${targetStatus(res)}`,
+            },
+        ],
+    };
+});
 server.registerTool('exactpdf_merge_pdfs', {
     description: 'Merge 2-20 local PDF files into one PDF in the exact order provided. Costs 1 credit only on successful output. Saves the merged PDF locally and returns its path.',
     inputSchema: z.object({
@@ -289,6 +344,50 @@ server.registerTool('exactpdf_compress_pdf', {
         ],
     };
 });
+server.registerTool('exactpdf_images_to_pdf_and_compress', {
+    description: 'Portal-ready workflow: convert local PNG/JPEG images into one ordered PDF, then best-effort repack/compress for an upload limit. Costs 1 launch credit on success. Returns measured output size and whether target_bytes was reached.',
+    inputSchema: z.object({
+        paths: z.array(z.string()).min(1).describe('Absolute paths to PNG or JPEG files, in PDF order.'),
+        target_bytes: z.number().int().positive().optional().describe('Optional upload limit, e.g. 524288 for 500KB or 1048576 for 1MB.'),
+    }),
+}, async ({ paths, target_bytes }) => {
+    const key = requireKey();
+    const form = new FormData();
+    for (const p of paths) {
+        const buf = await readFile(p);
+        const lower = p.toLowerCase();
+        const type = lower.endsWith('.png')
+            ? 'image/png'
+            : lower.endsWith('.jpg') || lower.endsWith('.jpeg')
+                ? 'image/jpeg'
+                : 'application/octet-stream';
+        form.append('file', new Blob([buf], { type }), basename(p));
+    }
+    if (typeof target_bytes === 'number')
+        form.append('target_bytes', String(target_bytes));
+    const res = await fetch(`${BASE}/api/v1/images-to-pdf-compress`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}` },
+        body: form,
+    });
+    const credits = res.headers.get('x-credits-remaining') ?? '?';
+    if (!res.ok) {
+        const errBody = await res.text();
+        return {
+            content: [{ type: 'text', text: `images-to-pdf-compress failed HTTP ${res.status}. Credits: ${credits}\n${errBody.slice(0, 8000)}` }],
+            isError: true,
+        };
+    }
+    const outPath = await saveBinaryFromResponse(res, 'exactpdf-images-compressed', 'pdf');
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Built and best-effort compressed PDF from ${paths.length} images → ${outPath}\nCredits remaining: ${credits}\n${targetStatus(res)}`,
+            },
+        ],
+    };
+});
 server.registerTool('exactpdf_images_to_pdf', {
     description: 'Convert local PNG/JPEG images into one ordered PDF. Costs 1 credit on success. Saves the resulting PDF locally and returns its path.',
     inputSchema: z.object({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exactpdf/mcp",
-  "version": "0.2.10",
-  "description": "MCP server for ExactPDF — PDF tools, voice previews, async PDF speech/audiobook jobs, polling, and API credits.",
+  "version": "0.2.12",
+  "description": "MCP server for ExactPDF — agent PDF workflows, structured Markdown/RAG, merge/compress, voice previews, async audio jobs, and API credits.",
   "mcpName": "com.exactpdf/mcp",
   "type": "module",
   "main": "./dist/run.js",
@@ -19,7 +19,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "homepage": "https://exactpdf.com/docs/api",
+  "homepage": "https://exactpdf.com/developers",
   "bugs": {
     "url": "https://exactpdf.com/docs/api",
     "email": "support@exactpdf.com"

package/server.json

@@ -3,13 +3,13 @@
   "name": "com.exactpdf/mcp",
   "title": "ExactPDF",
   "description": "Agent-facing PDF API: merge, split, rotate, compress, images, metadata, text, Markdown, voice previews, async speech/audiobook, multilingual speech, and presentation narration jobs.",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "websiteUrl": "https://exactpdf.com/docs/api",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@exactpdf/mcp",
-      "version": "0.2.10",
+      "version": "0.2.12",
       "transport": {
         "type": "stdio"
       }