@exactpdf/mcp 0.2.3 → 0.2.5

package/README.md

@@ -55,6 +55,39 @@ 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_job_status` | GET /api/v1/jobs/:id | 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
+```
+
+`exactpdf_pdf_to_audiobook` accepts 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
+```
+
+The default ZIP includes one MP3 per PDF page plus `manifest.json` with page numbers and duration seconds.
 
 ## Publish checklist
 

package/dist/run.js

@@ -24,9 +24,29 @@ function requireKey() {
     }
     return k;
 }
-const server = new McpServer({ name: 'exactpdf', version: '0.2.3' }, {
-    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). Set EXACTPDF_API_KEY.',
+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.',
 });
+async function saveBinaryFromResponse(res, prefix, fallbackExt) {
+    const buf = Buffer.from(await res.arrayBuffer());
+    const dir = outputDir();
+    await mkdir(dir, { recursive: true });
+    const outPath = join(dir, `${prefix}-${Date.now()}.${fallbackExt}`);
+    await writeFile(outPath, buf);
+    return outPath;
+}
+function extensionFromContentType(contentType, fallback) {
+    const ct = contentType?.toLowerCase() ?? '';
+    if (ct.includes('audio/mpeg') || ct.includes('audio/mp3'))
+        return 'mp3';
+    if (ct.includes('audio/wav') || ct.includes('audio/x-wav'))
+        return 'wav';
+    if (ct.includes('zip'))
+        return 'zip';
+    if (ct.includes('pdf'))
+        return 'pdf';
+    return fallback;
+}
 server.registerTool('exactpdf_account', {
     description: 'Return ExactPDF API credit balance and key metadata. Does not consume a credit.',
     inputSchema: z.object({}),
@@ -377,6 +397,261 @@ 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: 'Create an async PDF→audiobook job via ExactPDF API (10 credits). Returns a job_id; poll with exactpdf_job_status.',
+    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, }) => {
+    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)}`,
+            },
+        ],
+    };
+});
+server.registerTool('exactpdf_job_status', {
+    description: 'Poll an ExactPDF async API job. Set download=true to save the result when the job has succeeded.',
+    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.'),
+    }),
+}, async ({ job_id, download }) => {
+    const key = requireKey();
+    const res = await fetch(`${BASE}/api/v1/jobs/${encodeURIComponent(job_id)}`, {
+        headers: {
+            Authorization: `Bearer ${key}`,
+            Accept: 'application/json',
+        },
+    });
+    const raw = await res.text();
+    if (!res.ok) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `job-status 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 fallback = parsed.job?.kind === 'audiobook' ? 'mp3' : 'pdf';
+            const ext = extensionFromContentType(fileRes.headers.get('content-type'), fallback);
+            saved = `\nSaved result: ${await saveBinaryFromResponse(fileRes, `exactpdf-job-${job_id}`, ext)}`;
+        }
+    }
+    return {
+        content: [{ type: 'text', text: `HTTP ${res.status}\n${raw.slice(0, 120_000)}${saved}` }],
+    };
+});
+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.',
+    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.'),
+        source_language: z.string().optional().describe('Source language code. Default: auto.'),
+        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.'),
+        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".'),
+        segmentation_mode: z.enum(['chapters', 'pages']).optional().describe('Use pages for slide/page narration.'),
+        translation_glossary: z.string().optional().describe('JSON array like [{"source":"ExactPDF","target":"ExactPDF"}].'),
+        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, 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)}`,
+            },
+        ],
+    };
+});
+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.',
+    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.'),
+        voice_style: z
+            .enum(['professional', 'audiobook', 'educational', 'presenter', 'conversational'])
+            .optional()
+            .describe('Narration style. Default: presenter.'),
+        speed: z.number().min(0.5).max(2).optional().describe('Speech speed multiplier, 0.5-2.0.'),
+        page_range: z.string().optional().describe('Optional slide/page range, e.g. "1-10" or "2,4-7".'),
+        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, 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)}`,
+            },
+        ],
+    };
+});
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exactpdf/mcp",
-  "version": "0.2.3",
-  "description": "MCP server for ExactPDF — PDF tools (merge, split, rotate, compress, images→PDF, metadata) and API credits.",
+  "version": "0.2.5",
+  "description": "MCP server for ExactPDF — PDF tools, async PDF to audiobook jobs, polling, and API credits.",
   "mcpName": "com.exactpdf/mcp",
   "type": "module",
   "main": "./dist/run.js",
@@ -27,7 +27,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/exactpdf/exactpdf.git",
+    "url": "git+https://github.com/exactpdf/exactpdf.git",
     "directory": "packages/exactpdf-mcp"
   },
   "scripts": {

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": "MCP server for ExactPDF's agent-facing PDF API: merge, split, rotate, compress, images to PDF, PDF metadata, text extraction, and structured Markdown export.",
-  "version": "0.2.3",
+  "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",
   "websiteUrl": "https://exactpdf.com/docs/api",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@exactpdf/mcp",
-      "version": "0.2.3",
+      "version": "0.2.5",
       "transport": {
         "type": "stdio"
       }