@exactpdf/mcp 0.2.9 → 0.2.11

package/README.md

@@ -51,23 +51,27 @@ For a local checkout of this monorepo:
 Safe first run:
 
 ```text
-1. exactpdf_account
-2. exactpdf_pdf_info(path="/absolute/path/document.pdf")
-3. exactpdf_voice_preview(text="Short sample...", voice_style="professional")
-4. exactpdf_estimate_speech_cost(path="/absolute/path/document.pdf", mode="audiobook")
+1. exactpdf_first_run_checklist
+2. exactpdf_account
+3. exactpdf_pdf_info(path="/absolute/path/document.pdf")
+4. exactpdf_voice_preview(text="Short sample...", voice_style="professional")
+5. exactpdf_estimate_speech_cost(path="/absolute/path/document.pdf", mode="audiobook")
 ```
 
 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.
 
 | 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 |

package/dist/run.js

@@ -24,8 +24,8 @@ function requireKey() {
     }
     return k;
 }
-const server = new McpServer({ name: 'exactpdf', version: '0.2.8' }, {
-    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. Free tools: 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.11' }, {
+    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. 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 +47,55 @@ 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({}),
+}, async () => ({
+    content: [
+        {
+            type: 'text',
+            text: JSON.stringify({
+                ok: true,
+                setup: {
+                    required_env: 'EXACTPDF_API_KEY=sk_live_...',
+                    create_key_url: `${BASE}/max/account`,
+                    optional_output_dir: 'EXACTPDF_API_OUTPUT_DIR=/absolute/output/folder',
+                    docs: `${BASE}/docs/api`,
+                    openapi: `${BASE}/openapi.json`,
+                },
+                safe_first_run: [
+                    'Call exactpdf_account to verify the key and credit balance.',
+                    'Call exactpdf_pdf_info with a small absolute PDF path before extraction or conversion.',
+                    'Call exactpdf_voice_preview with a short text sample before long narration.',
+                    'Call exactpdf_estimate_speech_cost before audiobook, speech, translation, or presentation narration.',
+                ],
+                credit_model: {
+                    free: ['exactpdf_first_run_checklist', 'exactpdf_account', 'exactpdf_pdf_info', 'exactpdf_voice_preview', 'exactpdf_estimate_speech_cost', 'job polling'],
+                    standard_document_tools: '1 credit only after successful output',
+                    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',
+                },
+                reliability_rules: [
+                    'Use absolute local file paths; relative paths are client-dependent.',
+                    'Never paste API keys into prompts, screenshots, commits, or logs.',
+                    'Async jobs return a job_id first; poll until succeeded, then download.',
+                    'If a tool returns isError, show the HTTP status and response body to the user.',
+                ],
+            }, null, 2),
+        },
+    ],
+}));
 server.registerTool('exactpdf_account', {
     description: 'Check whether the ExactPDF API key works and return credit balance/key metadata. Free; does not consume credits. Use this before any paid tool.',
     inputSchema: z.object({}),
@@ -63,6 +112,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({
@@ -251,6 +338,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,6 +1,6 @@
 {
   "name": "@exactpdf/mcp",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "MCP server for ExactPDF — PDF tools, voice previews, async PDF speech/audiobook jobs, polling, and API credits.",
   "mcpName": "com.exactpdf/mcp",
   "type": "module",

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.9",
+  "version": "0.2.11",
   "websiteUrl": "https://exactpdf.com/docs/api",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@exactpdf/mcp",
-      "version": "0.2.9",
+      "version": "0.2.11",
       "transport": {
         "type": "stdio"
       }