@exactpdf/mcp 0.2.11 → 0.2.13

package/README.md

@@ -4,13 +4,15 @@
 
 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, extract text, 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.
 
+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
@@ -55,10 +57,20 @@ 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.
+- 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 |
 |------|----------|--------:|
@@ -76,14 +88,14 @@ Document outputs are saved to `EXACTPDF_API_OUTPUT_DIR` or your OS temp director
 | `exactpdf_pdf_structured_markdown` | POST /api/v1/pdf-structured-markdown | 1 |
 | `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
 
@@ -93,48 +105,27 @@ Document outputs are saved to `EXACTPDF_API_OUTPUT_DIR` or your OS temp director
 | 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 |
 | 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.
 
@@ -151,6 +142,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,13 @@ 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.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.',
+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.',
 });
 async function saveBinaryFromResponse(res, prefix, fallbackExt) {
     const buf = Buffer.from(await res.arrayBuffer());
@@ -68,7 +72,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`,
@@ -76,20 +81,22 @@ 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'],
+                    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',
+                    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),
@@ -529,7 +536,7 @@ server.registerTool('exactpdf_pdf_structured_markdown', {
     };
 });
 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.',
+    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.'),
@@ -548,58 +555,14 @@ server.registerTool('exactpdf_pdf_to_audiobook', {
         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, }) => {
-    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`, {
-        method: 'POST',
-        headers: {
-            Authorization: `Bearer ${key}`,
-            Accept: 'application/json',
-        },
-        body: form,
-    });
-    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)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
     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', {
@@ -655,7 +618,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.'),
@@ -673,59 +636,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.'),
@@ -739,48 +661,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({
@@ -801,48 +689,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) {
@@ -906,7 +755,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.'),
@@ -941,7 +790,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),
             },
@@ -1000,22 +849,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.11",
-  "description": "MCP server for ExactPDF — PDF tools, voice previews, async PDF speech/audiobook jobs, polling, and API credits.",
+  "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.",
   "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"
@@ -39,10 +39,19 @@
     "pdf",
     "exactpdf",
     "cursor",
+    "cursor-mcp",
     "claude",
     "claude-desktop",
+    "codex",
     "headless-pdf",
-    "pdf-api"
+    "pdf-api",
+    "pdf-mcp",
+    "pdf-compression",
+    "pdf-to-markdown",
+    "rag",
+    "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.11",
+  "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",
   "websiteUrl": "https://exactpdf.com/docs/api",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@exactpdf/mcp",
-      "version": "0.2.11",
+      "version": "0.2.13",
       "transport": {
         "type": "stdio"
       }