@exactpdf/mcp 0.2.12 → 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, narrate, translate, or export PDFs 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.
 
@@ -57,17 +57,19 @@ Safe first run:
 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")
+5. exactpdf_estimate_speech_cost(path="/absolute/path/document.pdf", mode="audiobook") # planning only while background audio is hardened
 ```
 
-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.
+Document outputs are saved to `EXACTPDF_API_OUTPUT_DIR` or your OS temp directory. Paid document tools consume credits only on successful output.
+
+Background PDF speech, audiobook, translate-and-speak, and presentation narration submissions are currently disabled for paid workloads while ExactPDF finishes dedicated worker hardening and queue-completion smoke. `exactpdf_voice_preview` remains available for short free samples, and `exactpdf_estimate_speech_cost` is planning-only until the API is re-enabled.
 
 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.
+- Background audio jobs: planning-only until dedicated worker smoke passes.
 - One-time packs: available in Max Account when you need more; no subscription required for API/MCP.
 
 | Tool | Endpoint | Credits |
@@ -80,71 +82,60 @@ 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 | 1/min |
-| `exactpdf_pdf_to_audiobook` | POST /api/v1/pdf-to-audiobook | 1/min |
-| `exactpdf_generate_audiobook` | POST /api/v1/generate-audiobook | 1/min |
-| `exactpdf_translate_and_speak` | POST /api/v1/translate-and-speak | 3/min |
-| `exactpdf_presentation_narration` | POST /api/v1/presentation-narration | 1/min |
-| `exactpdf_job_status` | GET /api/v1/jobs/:id | 0 |
-| `exactpdf_get_speech_job` | GET /api/v1/speech-jobs/:id | 0 |
-| `exactpdf_download_audio` | GET /api/v1/speech-jobs/:id/download | 0 |
+| `exactpdf_pdf_to_speech` | POST /api/v1/pdf-to-speech | disabled / hardening |
+| `exactpdf_pdf_to_audiobook` | POST /api/v1/pdf-to-audiobook | disabled / hardening |
+| `exactpdf_generate_audiobook` | POST /api/v1/generate-audiobook | disabled / hardening |
+| `exactpdf_translate_and_speak` | POST /api/v1/translate-and-speak | disabled / hardening |
+| `exactpdf_presentation_narration` | POST /api/v1/presentation-narration | disabled / hardening |
+| `exactpdf_job_status` | GET /api/v1/jobs/:id | 0 / legacy polling |
+| `exactpdf_get_speech_job` | GET /api/v1/speech-jobs/:id | 0 / legacy polling |
+| `exactpdf_download_audio` | GET /api/v1/speech-jobs/:id/download | 0 / legacy download |
 
 ## Tool behavior
 
 | 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 |
-| Speech jobs | PDF path, page range, style, callback URL | `job_id`, status URL, pricing estimate |
-| Job polling/download | `job_id` | progress/errors/result URL or saved audio/ZIP |
+| 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 |
 
-Async audiobook flow:
+Background audio status:
 
 ```text
-1. exactpdf_estimate_speech_cost(path="/abs/book.pdf", mode="audiobook")
+1. exactpdf_estimate_speech_cost(path="/abs/book.pdf", mode="audiobook") # planning only
 2. exactpdf_voice_preview(text="Read the first paragraph in an audiobook tone", voice_style="audiobook")
-3. exactpdf_generate_audiobook(path="/abs/book.pdf", voice_style="audiobook")
-4. exactpdf_get_speech_job(job_id="...", download=false)
-5. exactpdf_download_audio(job_id="...") after status is succeeded
-```
-
-`exactpdf_pdf_to_speech`, `exactpdf_pdf_to_audiobook`, and `exactpdf_generate_audiobook` accept optional `callback_url` and `webhook_secret`. ExactPDF signs webhook bodies with `x-exactpdf-signature: sha256=<hmac>` over `timestamp.body`.
-
-Multilingual speech flow:
-
-```text
-1. exactpdf_translate_and_speak(path="/abs/training.pdf", target_language="hi")
-2. exactpdf_job_status(job_id="...", download=false)
-3. exactpdf_job_status(job_id="...", download=true) after status is succeeded
-```
-
-`segmentation_mode="pages"` is useful for presentation narration because each PDF page becomes a trackable audio section.
-
-Presentation narration flow:
-
-```text
-1. exactpdf_presentation_narration(path="/abs/deck.pdf")
-2. exactpdf_job_status(job_id="...", download=true) after status is succeeded
+3. Do not call exactpdf_generate_audiobook / exactpdf_pdf_to_speech for paid workloads until ExactPDF announces worker smoke has passed.
 ```
 
-The default ZIP includes one MP3 per PDF page plus `manifest.json` with page numbers and duration seconds.
+The disabled background audio tools intentionally return an MCP error message before submitting work. This protects users from paying for a path that is still being hardened.
 
 ## Reliability rules for agent builders
 
 - Always call `exactpdf_account` once before paid tools.
 - Use absolute file paths. Relative paths are client-dependent and may fail.
 - Use `exactpdf_pdf_info` before large jobs to confirm the file is readable.
-- Use `exactpdf_estimate_speech_cost` before speech/audiobook/translation jobs.
-- Use `exactpdf_voice_preview` before full narration when quality matters.
-- Async jobs are not downloads. Submit, poll, then download after `succeeded`.
+- Use `exactpdf_estimate_speech_cost` for audio planning only until worker smoke passes.
+- Use `exactpdf_voice_preview` before making any narration-quality decision.
+- Do not promise PDF-to-MP3/audiobook output through MCP until background audio is re-enabled.
 - If a tool returns `isError`, show the HTTP status and response body to the user. The API returns structured error details.
 - Keep API keys out of prompts, logs, screenshots, and commits.
 

package/dist/run.js

@@ -27,8 +27,16 @@ function requireKey() {
     }
     return k;
 }
-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.',
+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 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());
@@ -60,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({}),
@@ -80,8 +122,8 @@ server.registerTool('exactpdf_first_run_checklist', {
                 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.',
+                    'Call exactpdf_voice_preview with a short text sample before any narration-quality decision.',
+                    'Call exactpdf_estimate_speech_cost only for planning; background audio submission is disabled until worker smoke passes.',
                 ],
                 credit_model: {
                     free: ['exactpdf_first_run_checklist', 'exactpdf_account', 'exactpdf_pdf_info', 'exactpdf_voice_preview', 'exactpdf_estimate_speech_cost', 'job polling'],
@@ -89,13 +131,13 @@ server.registerTool('exactpdf_first_run_checklist', {
                     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',
+                    speech_audiobook_presentation: 'Planning only while background audio jobs are disabled for production hardening.',
+                    translate_and_speak: 'Planning only while background audio jobs are disabled for production hardening.',
                 },
                 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.',
+                    'Background audio tools intentionally return a hardening/disabled message until worker smoke passes.',
                     'If a tool returns isError, show the HTTP status and response body to the user.',
                 ],
             }, null, 2),
@@ -304,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({
@@ -534,52 +597,16 @@ server.registerTool('exactpdf_pdf_structured_markdown', {
         content: [{ type: 'text', text: `Credits remaining: ${credits}\n${raw.slice(0, 120_000)}` }],
     };
 });
-server.registerTool('exactpdf_pdf_to_audiobook', {
-    description: 'Queue an async PDF-to-audiobook job with chapter-aware narration. Metered by generated minutes. Returns job_id/status_url; poll with exactpdf_get_speech_job and download when succeeded.',
+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'),
-        output_format: z.enum(['mp3', 'wav', 'zip']).optional().describe('Audio export format. Default: mp3.'),
-        voice_style: z
-            .enum(['professional', 'audiobook', 'educational', 'presenter', 'conversational'])
-            .optional()
-            .describe('Narration style. Default: audiobook.'),
-        voice_id: z.string().optional().describe('Optional provider voice id, if your account supports it.'),
-        language: z.string().optional().describe('Language hint such as en, hi, es, fr.'),
-        speed: z.number().min(0.5).max(2).optional().describe('Speech speed multiplier, 0.5-2.0.'),
-        page_range: z.string().optional().describe('Optional page range, e.g. "1-10" or "2,4-7".'),
-        normalize_pauses: z.boolean().optional().describe('Normalize pauses between extracted sections.'),
-        preserve_chapters: z.boolean().optional().describe('Keep detected headings as audiobook chapters.'),
-        pronunciation_fixes: z.string().optional().describe('JSON object of pronunciation replacements.'),
-        callback_url: z.string().url().optional().describe('Optional https webhook URL for job completion.'),
-        webhook_secret: z.string().min(12).max(256).optional().describe('Optional webhook HMAC signing secret.'),
     }),
-}, async ({ path, output_format, voice_style, voice_id, language, speed, page_range, normalize_pauses, preserve_chapters, pronunciation_fixes, callback_url, webhook_secret, }) => {
+}, async ({ path }) => {
     const key = requireKey();
     const form = new FormData();
     form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
-    if (output_format)
-        form.append('output_format', output_format);
-    if (voice_style)
-        form.append('voice_style', voice_style);
-    if (voice_id)
-        form.append('voice_id', voice_id);
-    if (language)
-        form.append('language', language);
-    if (typeof speed === 'number')
-        form.append('speed', String(speed));
-    if (page_range)
-        form.append('page_range', page_range);
-    if (typeof normalize_pauses === 'boolean')
-        form.append('normalize_pauses', String(normalize_pauses));
-    if (typeof preserve_chapters === 'boolean')
-        form.append('preserve_chapters', String(preserve_chapters));
-    if (pronunciation_fixes)
-        form.append('pronunciation_fixes', pronunciation_fixes);
-    if (callback_url)
-        form.append('callback_url', callback_url);
-    if (webhook_secret)
-        form.append('webhook_secret', webhook_secret);
-    const res = await fetch(`${BASE}/api/v1/pdf-to-audiobook`, {
+    const res = await fetch(`${BASE}/api/v1/pdf-to-json`, {
         method: 'POST',
         headers: {
             Authorization: `Bearer ${key}`,
@@ -587,25 +614,51 @@ server.registerTool('exactpdf_pdf_to_audiobook', {
         },
         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-audiobook failed HTTP ${res.status}\n${raw.slice(0, 8000)}`,
+                    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({
+        path: z.string().describe('Absolute path to a PDF file'),
+        output_format: z.enum(['mp3', 'wav', 'zip']).optional().describe('Audio export format. Default: mp3.'),
+        voice_style: z
+            .enum(['professional', 'audiobook', 'educational', 'presenter', 'conversational'])
+            .optional()
+            .describe('Narration style. Default: audiobook.'),
+        voice_id: z.string().optional().describe('Optional provider voice id, if your account supports it.'),
+        language: z.string().optional().describe('Language hint such as en, hi, es, fr.'),
+        speed: z.number().min(0.5).max(2).optional().describe('Speech speed multiplier, 0.5-2.0.'),
+        page_range: z.string().optional().describe('Optional page range, e.g. "1-10" or "2,4-7".'),
+        normalize_pauses: z.boolean().optional().describe('Normalize pauses between extracted sections.'),
+        preserve_chapters: z.boolean().optional().describe('Keep detected headings as audiobook chapters.'),
+        pronunciation_fixes: z.string().optional().describe('JSON object of pronunciation replacements.'),
+        callback_url: z.string().url().optional().describe('Optional https webhook URL for job completion.'),
+        webhook_secret: z.string().min(12).max(256).optional().describe('Optional webhook HMAC signing secret.'),
+    }),
+}, async ({ path, output_format, voice_style, voice_id, language, speed, page_range, normalize_pauses, preserve_chapters, pronunciation_fixes, callback_url, webhook_secret, }) => {
     return {
         content: [
             {
                 type: 'text',
-                text: `Audiobook job submitted HTTP ${res.status}\n${raw.slice(0, 120_000)}`,
+                text: `pdf-to-audiobook disabled: ${BACKGROUND_AUDIO_HARDENING_MESSAGE}`,
             },
         ],
+        isError: true,
     };
 });
 server.registerTool('exactpdf_job_status', {
@@ -661,7 +714,7 @@ server.registerTool('exactpdf_job_status', {
     };
 });
 server.registerTool('exactpdf_translate_and_speak', {
-    description: 'Queue async translate-and-speak: translate PDF content, preserve structure, then generate native-accent audio. Costs more than standard speech; start with hi/es/fr. Poll with exactpdf_get_speech_job.',
+    description: 'Planning-only placeholder while translate-and-speak workers are hardened. Do not use for paid workloads; use estimates for planning only.',
     inputSchema: z.object({
         path: z.string().describe('Absolute path to a PDF file'),
         target_language: z.string().describe('Target language code, e.g. hi, es, fr, mr, de, ja, ar.'),
@@ -679,59 +732,18 @@ server.registerTool('exactpdf_translate_and_speak', {
         webhook_secret: z.string().min(12).max(256).optional().describe('Optional webhook HMAC signing secret.'),
     }),
 }, async ({ path, target_language, source_language, output_format, voice_style, speed, page_range, segmentation_mode, translation_glossary, callback_url, webhook_secret, }) => {
-    const key = requireKey();
-    const form = new FormData();
-    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
-    form.append('target_language', target_language);
-    if (source_language)
-        form.append('source_language', source_language);
-    if (output_format)
-        form.append('output_format', output_format);
-    if (voice_style)
-        form.append('voice_style', voice_style);
-    if (typeof speed === 'number')
-        form.append('speed', String(speed));
-    if (page_range)
-        form.append('page_range', page_range);
-    if (segmentation_mode)
-        form.append('segmentation_mode', segmentation_mode);
-    if (translation_glossary)
-        form.append('translation_glossary', translation_glossary);
-    if (callback_url)
-        form.append('callback_url', callback_url);
-    if (webhook_secret)
-        form.append('webhook_secret', webhook_secret);
-    const res = await fetch(`${BASE}/api/v1/translate-and-speak`, {
-        method: 'POST',
-        headers: {
-            Authorization: `Bearer ${key}`,
-            Accept: 'application/json',
-        },
-        body: form,
-    });
-    const raw = await res.text();
-    if (!res.ok) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `translate-and-speak failed HTTP ${res.status}\n${raw.slice(0, 8000)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
     return {
         content: [
             {
                 type: 'text',
-                text: `Multilingual speech job submitted HTTP ${res.status}\n${raw.slice(0, 120_000)}`,
+                text: `translate-and-speak disabled: ${BACKGROUND_AUDIO_HARDENING_MESSAGE}`,
             },
         ],
+        isError: true,
     };
 });
 server.registerTool('exactpdf_presentation_narration', {
-    description: 'Queue audio-first presentation narration for a PDF deck. Each page becomes a narrated slide track in a ZIP with manifest timings. Metered by generated minutes.',
+    description: 'Planning-only placeholder while presentation narration workers are hardened. Do not use for paid workloads; use estimates for planning only.',
     inputSchema: z.object({
         path: z.string().describe('Absolute path to a PDF presentation file'),
         output_format: z.enum(['mp3', 'wav', 'zip']).optional().describe('Default: zip for per-slide tracks and manifest.'),
@@ -745,48 +757,14 @@ server.registerTool('exactpdf_presentation_narration', {
         webhook_secret: z.string().min(12).max(256).optional().describe('Optional webhook HMAC signing secret.'),
     }),
 }, async ({ path, output_format, voice_style, speed, page_range, callback_url, webhook_secret }) => {
-    const key = requireKey();
-    const form = new FormData();
-    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
-    if (output_format)
-        form.append('output_format', output_format);
-    if (voice_style)
-        form.append('voice_style', voice_style);
-    if (typeof speed === 'number')
-        form.append('speed', String(speed));
-    if (page_range)
-        form.append('page_range', page_range);
-    if (callback_url)
-        form.append('callback_url', callback_url);
-    if (webhook_secret)
-        form.append('webhook_secret', webhook_secret);
-    const res = await fetch(`${BASE}/api/v1/presentation-narration`, {
-        method: 'POST',
-        headers: {
-            Authorization: `Bearer ${key}`,
-            Accept: 'application/json',
-        },
-        body: form,
-    });
-    const raw = await res.text();
-    if (!res.ok) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `presentation-narration failed HTTP ${res.status}\n${raw.slice(0, 8000)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
     return {
         content: [
             {
                 type: 'text',
-                text: `Presentation narration job submitted HTTP ${res.status}\n${raw.slice(0, 120_000)}`,
+                text: `presentation-narration disabled: ${BACKGROUND_AUDIO_HARDENING_MESSAGE}`,
             },
         ],
+        isError: true,
     };
 });
 const speechJobSchema = z.object({
@@ -807,48 +785,9 @@ const speechJobSchema = z.object({
     webhook_secret: z.string().min(12).max(256).optional().describe('Optional webhook HMAC signing secret.'),
 });
 async function submitSpeechJob(endpoint, args, label) {
-    const key = requireKey();
-    const form = new FormData();
-    form.append('file', new Blob([await readFile(args.path)], { type: 'application/pdf' }), basename(args.path));
-    if (args.output_format)
-        form.append('output_format', args.output_format);
-    if (args.voice_style)
-        form.append('voice_style', args.voice_style);
-    if (args.voice_id)
-        form.append('voice_id', args.voice_id);
-    if (args.language)
-        form.append('language', args.language);
-    if (typeof args.speed === 'number')
-        form.append('speed', String(args.speed));
-    if (args.page_range)
-        form.append('page_range', args.page_range);
-    if (typeof args.normalize_pauses === 'boolean')
-        form.append('normalize_pauses', String(args.normalize_pauses));
-    if (typeof args.preserve_chapters === 'boolean')
-        form.append('preserve_chapters', String(args.preserve_chapters));
-    if (args.pronunciation_fixes)
-        form.append('pronunciation_fixes', args.pronunciation_fixes);
-    if (args.callback_url)
-        form.append('callback_url', args.callback_url);
-    if (args.webhook_secret)
-        form.append('webhook_secret', args.webhook_secret);
-    const res = await fetch(`${BASE}${endpoint}`, {
-        method: 'POST',
-        headers: {
-            Authorization: `Bearer ${key}`,
-            Accept: 'application/json',
-        },
-        body: form,
-    });
-    const raw = await res.text();
-    if (!res.ok) {
-        return {
-            content: [{ type: 'text', text: `${label} failed HTTP ${res.status}\n${raw.slice(0, 8000)}` }],
-            isError: true,
-        };
-    }
     return {
-        content: [{ type: 'text', text: `${label} job submitted HTTP ${res.status}\n${raw.slice(0, 120_000)}` }],
+        content: [{ type: 'text', text: `${label} disabled: ${BACKGROUND_AUDIO_HARDENING_MESSAGE}` }],
+        isError: true,
     };
 }
 async function pollSpeechJob(jobId, download, downloadEndpoint = false) {
@@ -912,7 +851,7 @@ async function pollSpeechJob(jobId, download, downloadEndpoint = false) {
     };
 }
 server.registerTool('exactpdf_estimate_speech_cost', {
-    description: 'Estimate generated minutes and credits before submitting a paid PDF speech/audiobook/translation job. Local-only rough estimate; free and safe to call repeatedly.',
+    description: 'Estimate generated minutes and credits for planning only while background PDF speech/audiobook/translation jobs are hardened. Local-only rough estimate; free and safe to call repeatedly.',
     inputSchema: z.object({
         path: z.string().optional().describe('Absolute path to a PDF file. Used for a rough size-based duration estimate.'),
         characters: z.number().int().positive().optional().describe('Known narration character count, if already extracted.'),
@@ -947,7 +886,7 @@ server.registerTool('exactpdf_estimate_speech_cost', {
                         current_credit_cost: credits,
                         target_language_applied: selectedMode === 'translate' ? (target_language ?? null) : null,
                         ignored_target_language: selectedMode !== 'translate' && target_language ? target_language : null,
-                        note: 'ExactPDF charges async speech jobs by estimated generated minutes: 1 credit/minute for standard speech/audiobook/presentation, 3 credits/minute for translate-and-speak. A target language only changes pricing when mode is translate. Path-based estimates are rough until the API extracts PDF text.',
+                        note: 'Planning-only while background audio jobs are disabled for production hardening. Intended pricing after re-enable is 1 credit/minute for standard speech/audiobook/presentation and 3 credits/minute for translate-and-speak. A target language only changes pricing when mode is translate. Path-based estimates are rough until the API extracts PDF text.',
                     },
                 }, null, 2),
             },
@@ -1006,22 +945,22 @@ server.registerTool('exactpdf_voice_preview', {
     };
 });
 server.registerTool('exactpdf_pdf_to_speech', {
-    description: 'Queue async PDF-to-speech for reports, study notes, or accessibility audio. Metered by generated minutes. Returns job_id; poll exactpdf_get_speech_job.',
+    description: 'Planning-only placeholder while PDF-to-speech workers are hardened. Do not use for paid workloads; use exactpdf_voice_preview and exactpdf_estimate_speech_cost instead.',
     inputSchema: speechJobSchema,
 }, async (args) => submitSpeechJob('/api/v1/pdf-to-speech', args, 'pdf-to-speech'));
 server.registerTool('exactpdf_generate_audiobook', {
-    description: 'Queue async audiobook generation with voice style, page range, chapters, pause normalization, and optional webhook. Metered by generated minutes.',
+    description: 'Planning-only placeholder while audiobook workers are hardened. Do not use for paid workloads; use exactpdf_voice_preview and exactpdf_estimate_speech_cost instead.',
     inputSchema: speechJobSchema,
 }, async (args) => submitSpeechJob('/api/v1/generate-audiobook', args, 'generate-audiobook'));
 server.registerTool('exactpdf_get_speech_job', {
-    description: 'Poll a speech/audiobook/translation/presentation job. Free. Returns status, progress, error details, and result_url when succeeded; set download=true to save result_url locally.',
+    description: 'Poll a legacy speech/audiobook/translation/presentation job. Background audio submission is currently disabled for paid workloads.',
     inputSchema: z.object({
         job_id: z.string().describe('ExactPDF speech job id.'),
         download: z.boolean().optional().describe('When true, save result_url to EXACTPDF_API_OUTPUT_DIR if job succeeded.'),
     }),
 }, async ({ job_id, download }) => pollSpeechJob(job_id, Boolean(download)));
 server.registerTool('exactpdf_download_audio', {
-    description: 'Download a succeeded speech/audiobook job and save the audio/ZIP locally. Free. Use only after exactpdf_get_speech_job reports succeeded.',
+    description: 'Download a legacy succeeded speech/audiobook job and save the audio/ZIP locally. New background audio submission is currently disabled for paid workloads.',
     inputSchema: z.object({
         job_id: z.string().describe('ExactPDF speech job id.'),
     }),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exactpdf/mcp",
-  "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.",
+  "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",
@@ -39,10 +39,23 @@
     "pdf",
     "exactpdf",
     "cursor",
+    "cursor-mcp",
     "claude",
     "claude-desktop",
+    "codex",
     "headless-pdf",
-    "pdf-api"
+    "pdf-api",
+    "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"
   ],
   "author": "ExactPDF",
   "license": "MIT",

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, metadata, text, Markdown, voice previews, async speech/audiobook, multilingual speech, and presentation narration jobs.",
-  "version": "0.2.12",
+  "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.12",
+      "version": "0.2.14",
       "transport": {
         "type": "stdio"
       }