@exactpdf/mcp 0.2.7 → 0.2.9

package/README.md

@@ -2,7 +2,11 @@
 
 <!-- mcp-name: com.exactpdf/mcp -->
 
-Model Context Protocol (stdio) server for **ExactPDF** — use PDF tools from **Cursor**, **Claude Desktop**, **Codex**, and any MCP client.
+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.
+
+**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.
 
 ## Setup
 
@@ -44,6 +48,17 @@ For a local checkout of this monorepo:
 
 ## Tools
 
+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")
+```
+
+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_account` | GET /api/v1/account | 0 |
@@ -66,6 +81,17 @@ For a local checkout of this monorepo:
 | `exactpdf_get_speech_job` | GET /api/v1/speech-jobs/:id | 0 |
 | `exactpdf_download_audio` | GET /api/v1/speech-jobs/:id/download | 0 |
 
+## 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 |
+| 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 |
+
 Async audiobook flow:
 
 ```text
@@ -97,12 +123,23 @@ Presentation narration flow:
 
 The default ZIP includes one MP3 per PDF page plus `manifest.json` with page numbers and duration seconds.
 
+## 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`.
+- 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.
+
 ## Publish checklist
 
 ```bash
 npm run mcp:package:check
 cd packages/exactpdf-mcp
-npm publish --access public --provenance
+npm publish --access public
 npx -y mcp-publisher publish --file server.json
 ```
 

package/dist/run.js

@@ -24,8 +24,8 @@ function requireKey() {
     }
     return k;
 }
-const server = new McpServer({ name: 'exactpdf', version: '0.2.7' }, {
-    instructions: 'ExactPDF API tools: exactpdf_account + exactpdf_pdf_info (free); merge, split, rotate, compress, images→PDF, extract-text, pdf-structured-markdown (1 credit each on success); voice-preview (free), async pdf-to-speech/pdf-to-audiobook/generate-audiobook (10 credits), translate-and-speak (20 credits), presentation narration (10 credits), plus speech job polling/download. Set EXACTPDF_API_KEY.',
+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.',
 });
 async function saveBinaryFromResponse(res, prefix, fallbackExt) {
     const buf = Buffer.from(await res.arrayBuffer());
@@ -48,7 +48,7 @@ function extensionFromContentType(contentType, fallback) {
     return fallback;
 }
 server.registerTool('exactpdf_account', {
-    description: 'Return ExactPDF API credit balance and key metadata. Does not consume a credit.',
+    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({}),
 }, async () => {
     const key = requireKey();
@@ -64,7 +64,7 @@ server.registerTool('exactpdf_account', {
     };
 });
 server.registerTool('exactpdf_merge_pdfs', {
-    description: 'Merge two or more local PDF files via ExactPDF API (1 credit). Provide absolute file paths in order.',
+    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({
         paths: z
             .array(z.string())
@@ -113,7 +113,7 @@ server.registerTool('exactpdf_merge_pdfs', {
     };
 });
 server.registerTool('exactpdf_split_pdf', {
-    description: 'Split one PDF via ExactPDF API (1 credit). Default: one PDF per page (ZIP). Optional at_pages (e.g. "3,7" splits after pages 3 and 7) or ranges JSON string like [[1,3],[4,10]].',
+    description: 'Split one local PDF into a ZIP of PDFs. Costs 1 credit on success. Default is one PDF per page; use at_pages for split points or ranges_json for explicit inclusive ranges.',
     inputSchema: z.object({
         path: z.string().describe('Absolute path to a PDF file'),
         at_pages: z
@@ -166,7 +166,7 @@ server.registerTool('exactpdf_split_pdf', {
     };
 });
 server.registerTool('exactpdf_rotate_pdf', {
-    description: 'Rotate every page of a PDF via ExactPDF API (1 credit). angle: 90, 180, 270, -90, -180, or -270.',
+    description: 'Rotate every page of a local PDF by 90/180/270 degrees. Costs 1 credit on success. Saves the rotated PDF locally and returns its path.',
     inputSchema: z.object({
         path: z.string().describe('Absolute path to a PDF file'),
         angle: z
@@ -211,7 +211,7 @@ server.registerTool('exactpdf_rotate_pdf', {
     };
 });
 server.registerTool('exactpdf_compress_pdf', {
-    description: 'Compress / repack a PDF via ExactPDF API (1 credit). Uses object-stream save; may not shrink image-heavy PDFs.',
+    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.',
     inputSchema: z.object({
         path: z.string().describe('Absolute path to a PDF file'),
     }),
@@ -252,7 +252,7 @@ server.registerTool('exactpdf_compress_pdf', {
     };
 });
 server.registerTool('exactpdf_images_to_pdf', {
-    description: 'Combine local PNG/JPEG images into one PDF via ExactPDF API (1 credit). Order matches paths array.',
+    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({
         paths: z.array(z.string()).min(1).describe('Absolute paths to PNG or JPEG files'),
     }),
@@ -302,7 +302,7 @@ server.registerTool('exactpdf_images_to_pdf', {
     };
 });
 server.registerTool('exactpdf_pdf_info', {
-    description: 'Read page count and PDF metadata (title, author, …). POST /api/v1/pdf-info — does not consume a credit.',
+    description: 'Read PDF page count and metadata before deciding what to do next. Free; does not consume credits. Good first step before merge/split/speech jobs.',
     inputSchema: z.object({
         path: z.string().describe('Absolute path to a PDF file'),
     }),
@@ -324,7 +324,7 @@ server.registerTool('exactpdf_pdf_info', {
     };
 });
 server.registerTool('exactpdf_extract_text', {
-    description: 'Extract plain text from a PDF via ExactPDF API (1 credit). Returns JSON with text and page_count.',
+    description: 'Extract plain text from a local PDF. Costs 1 credit on success. Returns JSON with text and page_count for summarizers, search, and downstream agents.',
     inputSchema: z.object({
         path: z.string().describe('Absolute path to a PDF file'),
     }),
@@ -358,7 +358,7 @@ server.registerTool('exactpdf_extract_text', {
     };
 });
 server.registerTool('exactpdf_pdf_structured_markdown', {
-    description: 'Convert PDF→structured Markdown JSON via ExactPDF API (1 credit). mode developer|academic|rag mirrors the web tool presets.',
+    description: 'Convert a local PDF into structured Markdown JSON. Costs 1 credit on success. Use developer for docs/API PDFs, academic for papers, and rag for retrieval chunks.',
     inputSchema: z.object({
         path: z.string().describe('Absolute path to a PDF file'),
         mode: z
@@ -398,7 +398,7 @@ server.registerTool('exactpdf_pdf_structured_markdown', {
     };
 });
 server.registerTool('exactpdf_pdf_to_audiobook', {
-    description: 'Create an async PDF→audiobook job via ExactPDF API (10 credits). Returns a job_id; poll with exactpdf_job_status.',
+    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.',
     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.'),
@@ -472,7 +472,7 @@ server.registerTool('exactpdf_pdf_to_audiobook', {
     };
 });
 server.registerTool('exactpdf_job_status', {
-    description: 'Poll an ExactPDF async API job. Set download=true to save the result when the job has succeeded.',
+    description: 'Poll a general ExactPDF async job and optionally save the result when succeeded. Free. Prefer exactpdf_get_speech_job for speech/audiobook jobs.',
     inputSchema: z.object({
         job_id: z.string().describe('ExactPDF async job id returned by exactpdf_pdf_to_audiobook.'),
         download: z.boolean().optional().describe('When true, save result_url to EXACTPDF_API_OUTPUT_DIR.'),
@@ -524,7 +524,7 @@ server.registerTool('exactpdf_job_status', {
     };
 });
 server.registerTool('exactpdf_translate_and_speak', {
-    description: 'Create an async PDF translation + native speech job via ExactPDF API (20 credits). Start with target_language hi, es, or fr; poll with exactpdf_job_status.',
+    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.',
     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.'),
@@ -594,7 +594,7 @@ server.registerTool('exactpdf_translate_and_speak', {
     };
 });
 server.registerTool('exactpdf_presentation_narration', {
-    description: 'Create an audio-first PDF presentation narration job (10 credits). Each page becomes a narrated slide track in a ZIP manifest.',
+    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.',
     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.'),
@@ -775,13 +775,13 @@ async function pollSpeechJob(jobId, download, downloadEndpoint = false) {
     };
 }
 server.registerTool('exactpdf_estimate_speech_cost', {
-    description: 'Estimate PDF speech duration and current ExactPDF API credit cost before submitting a paid job. No API credits consumed.',
+    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.',
     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.'),
         minutes: z.number().positive().optional().describe('Known generated minutes, if already estimated.'),
         mode: z.enum(['speech', 'audiobook', 'presentation', 'translate']).optional().describe('Default: audiobook.'),
-        target_language: z.string().optional().describe('Set for translation + speech estimates.'),
+        target_language: z.string().optional().describe('Only set when mode is translate. Leave empty for English speech/audiobook/presentation estimates.'),
     }),
 }, async ({ path, characters, minutes, mode, target_language }) => {
     let estimatedChars = characters ?? 0;
@@ -792,7 +792,7 @@ server.registerTool('exactpdf_estimate_speech_cost', {
         estimatedChars = Math.max(1_000, Math.round(info.size / 8));
     }
     const estimatedMinutes = minutes ?? Math.max(1, Math.ceil(estimatedChars / 900));
-    const selectedMode = target_language ? 'translate' : (mode ?? 'audiobook');
+    const selectedMode = mode === 'translate' ? 'translate' : (mode ?? 'audiobook');
     const creditsPerMinute = selectedMode === 'translate' ? 3 : 1;
     const credits = Math.max(1, estimatedMinutes * creditsPerMinute);
     return {
@@ -808,7 +808,9 @@ server.registerTool('exactpdf_estimate_speech_cost', {
                         generated_minutes: estimatedMinutes,
                         credits_per_minute: creditsPerMinute,
                         current_credit_cost: credits,
-                        note: 'ExactPDF charges async speech jobs by estimated generated minutes: 1 credit/minute for standard speech, 3 credits/minute for translate-and-speak. Path-based estimates are rough until the API extracts PDF text.',
+                        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.',
                     },
                 }, null, 2),
             },
@@ -816,7 +818,7 @@ server.registerTool('exactpdf_estimate_speech_cost', {
     };
 });
 server.registerTool('exactpdf_voice_preview', {
-    description: 'Generate a short server-side voice preview before submitting a paid PDF speech job. Saves MP3/WAV locally. Does not consume credits.',
+    description: 'Generate a short MP3/WAV voice sample before spending credits on a full PDF speech job. Free. Saves audio locally so users can judge quality first.',
     inputSchema: z.object({
         text: z.string().optional().describe('Preview text, capped server-side at 600 characters.'),
         output_format: z.enum(['mp3', 'wav']).optional().describe('Audio preview format. Default: mp3.'),
@@ -867,22 +869,22 @@ server.registerTool('exactpdf_voice_preview', {
     };
 });
 server.registerTool('exactpdf_pdf_to_speech', {
-    description: 'Create an async PDF→speech job via /api/v1/pdf-to-speech (10 credits). Alias of the production audiobook pipeline.',
+    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.',
     inputSchema: speechJobSchema,
 }, async (args) => submitSpeechJob('/api/v1/pdf-to-speech', args, 'pdf-to-speech'));
 server.registerTool('exactpdf_generate_audiobook', {
-    description: 'Create an async audiobook job via /api/v1/generate-audiobook (10 credits). Alias of the production audiobook pipeline.',
+    description: 'Queue async audiobook generation with voice style, page range, chapters, pause normalization, and optional webhook. Metered by generated minutes.',
     inputSchema: speechJobSchema,
 }, async (args) => submitSpeechJob('/api/v1/generate-audiobook', args, 'generate-audiobook'));
 server.registerTool('exactpdf_get_speech_job', {
-    description: 'Poll /api/v1/speech-jobs/:id for async PDF speech, audiobook, translation, or presentation narration jobs.',
+    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.',
     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 job through /api/v1/speech-jobs/:id/download and save it locally.',
+    description: 'Download a succeeded speech/audiobook job and save the audio/ZIP locally. Free. Use only after exactpdf_get_speech_job reports succeeded.',
     inputSchema: z.object({
         job_id: z.string().describe('ExactPDF speech job id.'),
     }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exactpdf/mcp",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "MCP server for ExactPDF — PDF tools, voice previews, async PDF speech/audiobook jobs, polling, and API credits.",
   "mcpName": "com.exactpdf/mcp",
   "type": "module",
@@ -17,8 +17,7 @@
     "server.json"
   ],
   "publishConfig": {
-    "access": "public",
-    "provenance": true
+    "access": "public"
   },
   "homepage": "https://exactpdf.com/docs/api",
   "bugs": {

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