@exactpdf/mcp 0.2.8 → 0.2.10

package/README.md

@@ -51,16 +51,18 @@ For a local checkout of this monorepo:
 Safe first run:
 
 ```text
-1. exactpdf_account
-2. exactpdf_pdf_info(path="/absolute/path/document.pdf")
-3. exactpdf_voice_preview(text="Short sample...", voice_style="professional")
-4. exactpdf_estimate_speech_cost(path="/absolute/path/document.pdf", mode="audiobook")
+1. exactpdf_first_run_checklist
+2. exactpdf_account
+3. exactpdf_pdf_info(path="/absolute/path/document.pdf")
+4. exactpdf_voice_preview(text="Short sample...", voice_style="professional")
+5. exactpdf_estimate_speech_cost(path="/absolute/path/document.pdf", mode="audiobook")
 ```
 
 Document outputs are saved to `EXACTPDF_API_OUTPUT_DIR` or your OS temp directory. Paid document tools consume credits only on successful output. Async speech jobs are metered by generated minutes.
 
 | Tool | Endpoint | Credits |
 |------|----------|--------:|
+| `exactpdf_first_run_checklist` | local guidance | 0 |
 | `exactpdf_account` | GET /api/v1/account | 0 |
 | `exactpdf_pdf_info` | POST /api/v1/pdf-info | 0 |
 | `exactpdf_merge_pdfs` | POST /api/v1/merge | 1 |

package/dist/run.js

@@ -24,8 +24,8 @@ function requireKey() {
     }
     return k;
 }
-const server = new McpServer({ name: 'exactpdf', version: '0.2.8' }, {
-    instructions: 'ExactPDF turns local PDFs into production outputs for agents: inspect metadata, merge/split/rotate/compress, extract text/structured Markdown, create voice previews, and queue async PDF speech/audiobook/translation/presentation narration jobs. Free tools: account, pdf-info, voice-preview, speech cost estimate. Standard document tools cost 1 credit on success. Async speech jobs are metered by generated minutes. Use absolute local file paths; binary outputs are saved to EXACTPDF_API_OUTPUT_DIR or the OS temp directory. For async jobs, submit first, then poll exactpdf_get_speech_job, then download with exactpdf_download_audio when succeeded.',
+const server = new McpServer({ name: 'exactpdf', version: '0.2.10' }, {
+    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. 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. Async speech jobs are metered by generated minutes. Use absolute local file paths; binary outputs are saved to EXACTPDF_API_OUTPUT_DIR or the OS temp directory. For async jobs, submit first, then poll exactpdf_get_speech_job, then download with exactpdf_download_audio when succeeded.',
 });
 async function saveBinaryFromResponse(res, prefix, fallbackExt) {
     const buf = Buffer.from(await res.arrayBuffer());
@@ -47,6 +47,44 @@ function extensionFromContentType(contentType, fallback) {
         return 'pdf';
     return fallback;
 }
+server.registerTool('exactpdf_first_run_checklist', {
+    description: 'Return the safest first-run sequence for ExactPDF MCP clients, including API key setup, free probe tools, credit rules, output directory behavior, and docs links. Free; no API key required.',
+    inputSchema: z.object({}),
+}, async () => ({
+    content: [
+        {
+            type: 'text',
+            text: JSON.stringify({
+                ok: true,
+                setup: {
+                    required_env: 'EXACTPDF_API_KEY=sk_live_...',
+                    create_key_url: `${BASE}/max/account`,
+                    optional_output_dir: 'EXACTPDF_API_OUTPUT_DIR=/absolute/output/folder',
+                    docs: `${BASE}/docs/api`,
+                    openapi: `${BASE}/openapi.json`,
+                },
+                safe_first_run: [
+                    'Call exactpdf_account to verify the key and credit balance.',
+                    'Call exactpdf_pdf_info with a small absolute PDF path before extraction or conversion.',
+                    'Call exactpdf_voice_preview with a short text sample before long narration.',
+                    'Call exactpdf_estimate_speech_cost before audiobook, speech, translation, or presentation narration.',
+                ],
+                credit_model: {
+                    free: ['exactpdf_first_run_checklist', 'exactpdf_account', 'exactpdf_pdf_info', 'exactpdf_voice_preview', 'exactpdf_estimate_speech_cost', 'job polling'],
+                    standard_document_tools: '1 credit only after successful output',
+                    speech_audiobook_presentation: '1 credit per generated minute',
+                    translate_and_speak: '3 credits per generated minute',
+                },
+                reliability_rules: [
+                    'Use absolute local file paths; relative paths are client-dependent.',
+                    'Never paste API keys into prompts, screenshots, commits, or logs.',
+                    'Async jobs return a job_id first; poll until succeeded, then download.',
+                    'If a tool returns isError, show the HTTP status and response body to the user.',
+                ],
+            }, null, 2),
+        },
+    ],
+}));
 server.registerTool('exactpdf_account', {
     description: 'Check whether the ExactPDF API key works and return credit balance/key metadata. Free; does not consume credits. Use this before any paid tool.',
     inputSchema: z.object({}),
@@ -781,7 +819,7 @@ server.registerTool('exactpdf_estimate_speech_cost', {
         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 +830,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 +846,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),
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exactpdf/mcp",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "MCP server for ExactPDF — PDF tools, voice previews, async PDF speech/audiobook jobs, polling, and API credits.",
   "mcpName": "com.exactpdf/mcp",
   "type": "module",

package/server.json

@@ -3,13 +3,13 @@
   "name": "com.exactpdf/mcp",
   "title": "ExactPDF",
   "description": "Agent-facing PDF API: merge, split, rotate, compress, images, metadata, text, Markdown, voice previews, async speech/audiobook, multilingual speech, and presentation narration jobs.",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "websiteUrl": "https://exactpdf.com/docs/api",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@exactpdf/mcp",
-      "version": "0.2.8",
+      "version": "0.2.10",
       "transport": {
         "type": "stdio"
       }