@exactpdf/mcp 0.2.13 → 0.2.14

package/README.md

@@ -4,7 +4,7 @@
 
 Model Context Protocol (stdio) server for **ExactPDF** — production PDF tools for **Cursor**, **Claude Desktop**, **Codex**, and any MCP client.
 
-Use it when an agent needs to inspect, merge, split, rotate, compress, extract text, export structured Markdown for RAG, or build images-to-PDF workflows without writing fragile PDF plumbing.
+Use it when an agent needs to inspect, merge, split, rotate, compress to upload limits, extract text, export PDF JSON, export structured Markdown for RAG, or build images-to-PDF workflows without writing fragile PDF plumbing.
 
 **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.
 
@@ -82,10 +82,18 @@ Credit model:
 | `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_compress_pdf_to_target` | POST /api/v1/compress + target_bytes | 1 |
+| `exactpdf_compress_pdf_to_100kb` | POST /api/v1/compress + 102400 target_bytes | 1 |
+| `exactpdf_compress_pdf_to_200kb` | POST /api/v1/compress + 204800 target_bytes | 1 |
+| `exactpdf_compress_pdf_to_500kb` | POST /api/v1/compress + 512000 target_bytes | 1 |
+| `exactpdf_compress_pdf_to_1mb` | POST /api/v1/compress + 1048576 target_bytes | 1 |
+| `exactpdf_pdf_to_images` | planned /api/v1/pdf-to-images | backend required |
 | `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_to_json` | POST /api/v1/pdf-to-json | 1 |
 | `exactpdf_pdf_structured_markdown` | POST /api/v1/pdf-structured-markdown | 1 |
+| `exactpdf_ocr_pdf` | planned /api/v1/ocr | backend required |
 | `exactpdf_estimate_speech_cost` | local estimate | 0 |
 | `exactpdf_voice_preview` | POST /api/v1/voice-preview | 0 |
 | `exactpdf_pdf_to_speech` | POST /api/v1/pdf-to-speech | disabled / hardening |
@@ -102,8 +110,10 @@ Credit model:
 | Tool family | What the agent provides | What ExactPDF returns |
 | --- | --- | --- |
 | Account / inspect | API key, local PDF path | JSON balance, page count, metadata |
-| PDF operations | Absolute local PDF paths | Saved PDF/ZIP path plus remaining credits |
-| Text / Markdown | Absolute local PDF path | JSON text/Markdown, page count, structured content |
+| PDF operations | Absolute local PDF paths | Saved PDF/ZIP path plus remaining credits and measured size headers |
+| Target-size compression | Absolute local PDF path, target bytes or preset | Saved PDF plus `X-Target-Reached`, original bytes, output bytes |
+| Text / JSON / Markdown | Absolute local PDF path | JSON text/pages/metadata or Markdown, page count, structured content |
+| Backend-required PDF images/OCR | Desired path/options | Clear backend-required message plus live browser tool URL |
 | Voice preview | Short text, voice style/language | Saved MP3/WAV preview, no credit charge |
 | Audio planning | Short text, character count, rough PDF size | Voice preview or estimated minutes/credits |
 | Legacy job polling/download | `job_id` | progress/errors/result URL or saved audio/ZIP for jobs created before the hardening gate |

package/dist/run.js

@@ -28,8 +28,15 @@ function requireKey() {
     return k;
 }
 const BACKGROUND_AUDIO_HARDENING_MESSAGE = 'Background PDF speech, audiobook, translate-and-speak, and presentation narration jobs are currently disabled for paid workloads while ExactPDF finishes dedicated worker hardening and queue-completion smoke. Use exactpdf_voice_preview for short free voice samples and exactpdf_estimate_speech_cost for planning only. Do not promise MP3/audiobook delivery through MCP until the API returns enabled status again.';
-const server = new McpServer({ name: 'exactpdf', version: '0.2.13' }, {
-    instructions: 'ExactPDF turns local PDFs into production outputs for agents: inspect metadata, merge/split/rotate/compress, create portal-ready merge/images workflows, extract text, export structured Markdown for RAG, and create short voice previews. 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, and speech cost estimate. Standard document tools cost 1 credit on success, including launch portal-ready workflows. Background PDF speech/audiobook/translation/presentation jobs are in production hardening and must be treated as planning-only until worker smoke passes. Use absolute local file paths; binary outputs are saved to EXACTPDF_API_OUTPUT_DIR or the OS temp directory.',
+const BACKEND_REQUIRED_TOOL_MESSAGE = 'This MCP tool is intentionally exposed as backend-required, not live. ExactPDF has the browser workflow today, but the API/MCP endpoint needs a dedicated server renderer/OCR worker before agents can run it as infrastructure. Do not present this as a completed API workflow yet.';
+const TARGET_SIZE_PRESETS = {
+    '100kb': 100 * 1024,
+    '200kb': 200 * 1024,
+    '500kb': 500 * 1024,
+    '1mb': 1024 * 1024,
+};
+const server = new McpServer({ name: 'exactpdf', version: '0.2.14' }, {
+    instructions: 'ExactPDF turns local PDFs into production outputs for agents: inspect metadata, merge/split/rotate/compress, target-size best-effort compression, create portal-ready merge/images workflows, extract text, export PDF JSON, export structured Markdown for RAG, and create short voice previews. 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, and speech cost estimate. Standard document tools cost 1 credit on success, including launch portal-ready workflows. PDF-to-images and OCR are visible as backend-required placeholders until server renderer/OCR worker endpoints ship. Background PDF speech/audiobook/translation/presentation jobs are in production hardening and must be treated as planning-only until worker smoke passes. Use absolute local file paths; binary outputs are saved to EXACTPDF_API_OUTPUT_DIR or the OS temp directory.',
 });
 async function saveBinaryFromResponse(res, prefix, fallbackExt) {
     const buf = Buffer.from(await res.arrayBuffer());
@@ -61,6 +68,40 @@ function targetStatus(res) {
     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}`;
 }
+async function compressPdfToTarget(path, target_bytes) {
+    const key = requireKey();
+    const form = new FormData();
+    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
+    if (typeof target_bytes === 'number')
+        form.append('target_bytes', String(target_bytes));
+    const res = await fetch(`${BASE}/api/v1/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: `Compress failed HTTP ${res.status}. Credits: ${credits}\n${errBody.slice(0, 4000)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const outPath = await saveBinaryFromResponse(res, 'exactpdf-compressed', 'pdf');
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Compressed → ${outPath}\nCredits remaining: ${credits}\n${targetStatus(res)}`,
+            },
+        ],
+    };
+}
 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({}),
@@ -305,46 +346,67 @@ server.registerTool('exactpdf_rotate_pdf', {
     };
 });
 server.registerTool('exactpdf_compress_pdf', {
-    description: 'Compress/repack a local PDF for smaller delivery. Costs 1 credit on success. Best for structure/object cleanup; image-heavy PDFs may need ExactPDF Max target-size compression.',
+    description: 'Compress/repack a local PDF for smaller delivery. Costs 1 credit on success. Optional target_bytes returns measured target headers. Best-effort, not guaranteed exact-size compression.',
     inputSchema: z.object({
         path: z.string().describe('Absolute path to a PDF file'),
+        target_bytes: z.number().int().positive().optional().describe('Optional upload limit such as 102400 for 100KB, 204800 for 200KB, 512000 for 500KB, or 1048576 for 1MB.'),
     }),
-}, async ({ path }) => {
-    const key = requireKey();
-    const form = new FormData();
-    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
-    const res = await fetch(`${BASE}/api/v1/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: `Compress failed HTTP ${res.status}. Credits: ${credits}\n${errBody.slice(0, 4000)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-    const buf = Buffer.from(await res.arrayBuffer());
-    const dir = outputDir();
-    await mkdir(dir, { recursive: true });
-    const outPath = join(dir, `exactpdf-compressed-${Date.now()}.pdf`);
-    await writeFile(outPath, buf);
-    return {
-        content: [
-            {
-                type: 'text',
-                text: `Compressed → ${outPath}\nCredits remaining: ${credits}`,
-            },
-        ],
-    };
-});
+}, async ({ path, target_bytes }) => compressPdfToTarget(path, target_bytes));
+server.registerTool('exactpdf_compress_pdf_to_target', {
+    description: 'Best-effort compress/repack a local PDF toward a target size such as 100KB, 200KB, 500KB, or 1MB. Costs 1 credit on success and reports whether target_bytes was reached.',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute path to a PDF file'),
+        target_bytes: z.number().int().positive().describe('Upload limit in bytes, e.g. 102400 for 100KB or 1048576 for 1MB.'),
+    }),
+}, async ({ path, target_bytes }) => compressPdfToTarget(path, target_bytes));
+for (const [label, targetBytes] of Object.entries(TARGET_SIZE_PRESETS)) {
+    server.registerTool(`exactpdf_compress_pdf_to_${label}`, {
+        description: `Best-effort compress/repack a local PDF toward ${label.toUpperCase()}. Costs 1 credit on success and reports whether the target was reached.`,
+        inputSchema: z.object({
+            path: z.string().describe('Absolute path to a PDF file'),
+        }),
+    }, async ({ path }) => compressPdfToTarget(path, targetBytes));
+}
+server.registerTool('exactpdf_pdf_to_images', {
+    description: 'Backend-required placeholder for PDF-to-images API/MCP. Use the live browser tool at https://exactpdf.com/tools/pdf-to-images until the server renderer endpoint ships.',
+    inputSchema: z.object({
+        path: z.string().optional().describe('Absolute path to a PDF file. Not processed yet because the API endpoint is not live.'),
+        output_format: z.enum(['jpg', 'png']).optional().describe('Planned output format.'),
+        dpi: z.number().int().positive().optional().describe('Planned render DPI.'),
+        page_range: z.string().optional().describe('Planned page range, e.g. "1-3".'),
+    }),
+}, async () => ({
+    content: [{
+            type: 'text',
+            text: JSON.stringify({
+                ok: false,
+                status: 'backend_required',
+                web_tool: `${BASE}/tools/pdf-to-images`,
+                planned_endpoint: `${BASE}/api/v1/pdf-to-images`,
+                note: BACKEND_REQUIRED_TOOL_MESSAGE,
+            }, null, 2),
+        }],
+    isError: true,
+}));
+server.registerTool('exactpdf_ocr_pdf', {
+    description: 'Backend-required placeholder for OCR API/MCP. Use the live browser OCR page at https://exactpdf.com/tools/ocr-pdf until the server OCR worker endpoint ships.',
+    inputSchema: z.object({
+        path: z.string().optional().describe('Absolute path to a PDF file. Not processed yet because the API endpoint is not live.'),
+        language: z.string().optional().describe('Planned OCR language hint such as eng, hin, spa.'),
+    }),
+}, async () => ({
+    content: [{
+            type: 'text',
+            text: JSON.stringify({
+                ok: false,
+                status: 'backend_required',
+                web_tool: `${BASE}/tools/ocr-pdf`,
+                planned_endpoint: `${BASE}/api/v1/ocr`,
+                note: BACKEND_REQUIRED_TOOL_MESSAGE,
+            }, null, 2),
+        }],
+    isError: true,
+}));
 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({
@@ -535,6 +597,40 @@ server.registerTool('exactpdf_pdf_structured_markdown', {
         content: [{ type: 'text', text: `Credits remaining: ${credits}\n${raw.slice(0, 120_000)}` }],
     };
 });
+server.registerTool('exactpdf_pdf_to_json', {
+    description: 'Extract text-layer PDF structure as JSON: metadata, per-page text, full text, page count, and extraction notes. Costs 1 credit on success. Scanned PDFs need OCR first.',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute path to a PDF file'),
+    }),
+}, async ({ path }) => {
+    const key = requireKey();
+    const form = new FormData();
+    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
+    const res = await fetch(`${BASE}/api/v1/pdf-to-json`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${key}`,
+            Accept: 'application/json',
+        },
+        body: form,
+    });
+    const credits = res.headers.get('x-credits-remaining') ?? '?';
+    const raw = await res.text();
+    if (!res.ok) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `pdf-to-json failed HTTP ${res.status}. Credits: ${credits}\n${raw.slice(0, 8000)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: 'text', text: `Credits remaining: ${credits}\n${raw.slice(0, 120_000)}` }],
+    };
+});
 server.registerTool('exactpdf_pdf_to_audiobook', {
     description: 'Planning-only placeholder while background audio workers are hardened. Do not use for paid workloads; use exactpdf_voice_preview and exactpdf_estimate_speech_cost instead.',
     inputSchema: z.object({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exactpdf/mcp",
-  "version": "0.2.13",
-  "description": "MCP server for ExactPDF — agent PDF workflows, structured Markdown/RAG, merge/split/compress, images-to-PDF, voice previews, and API credits.",
+  "version": "0.2.14",
+  "description": "MCP server for ExactPDF — agent PDF workflows, target-size compression, structured Markdown/RAG, PDF JSON, merge/split, images-to-PDF, voice previews, and API credits.",
   "mcpName": "com.exactpdf/mcp",
   "type": "module",
   "main": "./dist/run.js",
@@ -48,7 +48,11 @@
     "pdf-mcp",
     "pdf-compression",
     "pdf-to-markdown",
+    "pdf-to-json",
+    "pdf-to-images",
+    "target-size-compression",
     "rag",
+    "ocr",
     "images-to-pdf",
     "merge-pdf",
     "split-pdf"

package/server.json

@@ -2,14 +2,14 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "com.exactpdf/mcp",
   "title": "ExactPDF",
-  "description": "Agent-facing PDF API: merge, split, rotate, compress, images-to-PDF, metadata, text extraction, structured Markdown/RAG, voice previews, and API credit checks. Background audio jobs are hardening-only until worker smoke passes.",
-  "version": "0.2.13",
+  "description": "Agent-facing PDF API: merge, split, rotate, compress, target-size compression, images-to-PDF, metadata, text extraction, PDF JSON, structured Markdown/RAG, voice previews, and API credit checks. PDF-to-images/OCR require backend workers; background audio jobs are hardening-only until worker smoke passes.",
+  "version": "0.2.14",
   "websiteUrl": "https://exactpdf.com/docs/api",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@exactpdf/mcp",
-      "version": "0.2.13",
+      "version": "0.2.14",
       "transport": {
         "type": "stdio"
       }