@exactpdf/mcp 0.2.5 → 0.2.7

package/README.md

@@ -55,20 +55,28 @@ For a local checkout of this monorepo:
 | `exactpdf_images_to_pdf` | POST /api/v1/images-to-pdf | 1 |
 | `exactpdf_extract_text` | POST /api/v1/extract-text | 1 |
 | `exactpdf_pdf_structured_markdown` | POST /api/v1/pdf-structured-markdown | 1 |
-| `exactpdf_pdf_to_audiobook` | POST /api/v1/pdf-to-audiobook | 10 |
-| `exactpdf_translate_and_speak` | POST /api/v1/translate-and-speak | 20 |
-| `exactpdf_presentation_narration` | POST /api/v1/presentation-narration | 10 |
+| `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 |
 
 Async audiobook flow:
 
 ```text
-1. exactpdf_pdf_to_audiobook(path="/abs/book.pdf", voice_style="audiobook")
-2. exactpdf_job_status(job_id="...", download=false)
-3. exactpdf_job_status(job_id="...", download=true) after status is succeeded
+1. exactpdf_estimate_speech_cost(path="/abs/book.pdf", mode="audiobook")
+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_audiobook` accepts optional `callback_url` and `webhook_secret`. ExactPDF signs webhook bodies with `x-exactpdf-signature: sha256=<hmac>` over `timestamp.body`.
+`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:
 

package/dist/run.js

@@ -5,7 +5,7 @@
  *
  * @see https://exactpdf.com/docs/api
  */
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -24,8 +24,8 @@ function requireKey() {
     }
     return k;
 }
-const server = new McpServer({ name: 'exactpdf', version: '0.2.5' }, {
-    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); async pdf-to-audiobook (10 credits), translate-and-speak (20 credits), presentation narration (10 credits), plus job polling. Set EXACTPDF_API_KEY.',
+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.',
 });
 async function saveBinaryFromResponse(res, prefix, fallbackExt) {
     const buf = Buffer.from(await res.arrayBuffer());
@@ -652,6 +652,241 @@ server.registerTool('exactpdf_presentation_narration', {
         ],
     };
 });
+const speechJobSchema = 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.'),
+    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 array 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 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)}` }],
+    };
+}
+async function pollSpeechJob(jobId, download, downloadEndpoint = false) {
+    const key = requireKey();
+    const endpoint = downloadEndpoint
+        ? `/api/v1/speech-jobs/${encodeURIComponent(jobId)}/download`
+        : `/api/v1/speech-jobs/${encodeURIComponent(jobId)}`;
+    const res = await fetch(`${BASE}${endpoint}`, {
+        redirect: downloadEndpoint ? 'manual' : 'follow',
+        headers: {
+            Authorization: `Bearer ${key}`,
+            Accept: downloadEndpoint ? '*/*' : 'application/json',
+        },
+    });
+    if (downloadEndpoint) {
+        const location = res.headers.get('location');
+        if (res.status >= 300 && res.status < 400 && location) {
+            const fileRes = await fetch(location);
+            if (!fileRes.ok) {
+                return {
+                    content: [{ type: 'text', text: `download-audio signed URL failed HTTP ${fileRes.status}` }],
+                    isError: true,
+                };
+            }
+            const ext = extensionFromContentType(fileRes.headers.get('content-type'), 'mp3');
+            return {
+                content: [{ type: 'text', text: `Saved audio: ${await saveBinaryFromResponse(fileRes, `exactpdf-audio-${jobId}`, ext)}` }],
+            };
+        }
+        const raw = await res.text();
+        return {
+            content: [{ type: 'text', text: `download-audio failed HTTP ${res.status}\n${raw.slice(0, 8000)}` }],
+            isError: true,
+        };
+    }
+    const raw = await res.text();
+    if (!res.ok) {
+        return {
+            content: [{ type: 'text', text: `get-speech-job failed HTTP ${res.status}\n${raw.slice(0, 8000)}` }],
+            isError: true,
+        };
+    }
+    let saved = '';
+    if (download) {
+        const parsed = JSON.parse(raw);
+        const resultUrl = parsed.job?.result_url;
+        if (parsed.job?.status === 'succeeded' && resultUrl) {
+            const fileRes = await fetch(resultUrl);
+            if (!fileRes.ok) {
+                return {
+                    content: [{ type: 'text', text: `Job succeeded, but result download failed HTTP ${fileRes.status}\n${raw.slice(0, 8000)}` }],
+                    isError: true,
+                };
+            }
+            const ext = extensionFromContentType(fileRes.headers.get('content-type'), 'mp3');
+            saved = `\nSaved result: ${await saveBinaryFromResponse(fileRes, `exactpdf-speech-job-${jobId}`, ext)}`;
+        }
+    }
+    return {
+        content: [{ type: 'text', text: `HTTP ${res.status}\n${raw.slice(0, 120_000)}${saved}` }],
+    };
+}
+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.',
+    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.'),
+    }),
+}, async ({ path, characters, minutes, mode, target_language }) => {
+    let estimatedChars = characters ?? 0;
+    let fileBytes = null;
+    if (!estimatedChars && path) {
+        const info = await stat(path);
+        fileBytes = info.size;
+        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 creditsPerMinute = selectedMode === 'translate' ? 3 : 1;
+    const credits = Math.max(1, estimatedMinutes * creditsPerMinute);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    ok: true,
+                    estimate: {
+                        mode: selectedMode,
+                        file_bytes: fileBytes,
+                        characters: estimatedChars || null,
+                        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.',
+                    },
+                }, null, 2),
+            },
+        ],
+    };
+});
+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.',
+    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.'),
+        voice_style: z
+            .enum(['professional', 'audiobook', 'educational', 'presenter', 'conversational'])
+            .optional()
+            .describe('Narration style. Default: professional.'),
+        voice_id: z.string().optional().describe('Optional Google Cloud voice name, e.g. en-US-Standard-H.'),
+        language: z.string().optional().describe('Language hint such as en, hi, es, fr. Default: en.'),
+        speed: z.number().min(0.5).max(2).optional().describe('Speech speed multiplier, 0.5-2.0.'),
+    }),
+}, async ({ text, output_format, voice_style, voice_id, language, speed }) => {
+    const key = requireKey();
+    const res = await fetch(`${BASE}/api/v1/voice-preview`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${key}`,
+            Accept: '*/*',
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            ...(text ? { text } : {}),
+            ...(output_format ? { output_format } : {}),
+            ...(voice_style ? { voice_style } : {}),
+            ...(voice_id ? { voice_id } : {}),
+            ...(language ? { language } : {}),
+            ...(typeof speed === 'number' ? { speed } : {}),
+        }),
+    });
+    if (!res.ok) {
+        const raw = await res.text();
+        return {
+            content: [{ type: 'text', text: `voice-preview failed HTTP ${res.status}\n${raw.slice(0, 8000)}` }],
+            isError: true,
+        };
+    }
+    const ext = extensionFromContentType(res.headers.get('content-type'), output_format ?? 'mp3');
+    const outPath = await saveBinaryFromResponse(res, 'exactpdf-voice-preview', ext);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Voice preview saved: ${outPath}\n` +
+                    `Credits used: ${res.headers.get('x-credits-used') ?? '0'}\n` +
+                    `Provider: ${res.headers.get('x-exactpdf-provider') ?? 'unknown'}`,
+            },
+        ],
+    };
+});
+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.',
+    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.',
+    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.',
+    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.',
+    inputSchema: z.object({
+        job_id: z.string().describe('ExactPDF speech job id.'),
+    }),
+}, async ({ job_id }) => pollSpeechJob(job_id, true, true));
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exactpdf/mcp",
-  "version": "0.2.5",
-  "description": "MCP server for ExactPDF — PDF tools, async PDF to audiobook jobs, polling, and API credits.",
+  "version": "0.2.7",
+  "description": "MCP server for ExactPDF — PDF tools, voice previews, async PDF speech/audiobook jobs, polling, and API credits.",
   "mcpName": "com.exactpdf/mcp",
   "type": "module",
   "main": "./dist/run.js",

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, async audiobook, multilingual speech, and presentation narration jobs.",
-  "version": "0.2.5",
+  "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",
   "websiteUrl": "https://exactpdf.com/docs/api",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@exactpdf/mcp",
-      "version": "0.2.5",
+      "version": "0.2.7",
       "transport": {
         "type": "stdio"
       }