@exactpdf/mcp 0.2.3

package/README.md

@@ -0,0 +1,76 @@
+# @exactpdf/mcp
+
+<!-- mcp-name: com.exactpdf/mcp -->
+
+Model Context Protocol (stdio) server for **ExactPDF** — use PDF tools from **Cursor**, **Claude Desktop**, **Codex**, and any MCP client.
+
+## Setup
+
+1. Create an API key at [exactpdf.com](https://exactpdf.com) (Max → API keys).
+2. Export:
+
+```bash
+export EXACTPDF_API_KEY="sk_live_…"
+# Optional: default https://exactpdf.com
+export EXACTPDF_API_BASE="https://exactpdf.com"
+# Optional: where API binary outputs are written (default: OS temp dir)
+export EXACTPDF_API_OUTPUT_DIR="/tmp"
+# Backward-compatible alias:
+export EXACTPDF_MERGE_OUTPUT_DIR="/tmp"
+```
+
+3. Add to your MCP config (Cursor → Settings → MCP):
+
+```json
+{
+  "mcpServers": {
+    "exactpdf": {
+      "command": "npx",
+      "args": ["-y", "@exactpdf/mcp"],
+      "env": {
+        "EXACTPDF_API_KEY": "sk_live_…"
+      }
+    }
+  }
+}
+```
+
+For a local checkout of this monorepo:
+
+```json
+"command": "node",
+"args": ["/path/to/ExactPDF/packages/exactpdf-mcp/dist/run.js"]
+```
+
+## Tools
+
+| Tool | Endpoint | Credits |
+|------|----------|--------:|
+| `exactpdf_account` | GET /api/v1/account | 0 |
+| `exactpdf_pdf_info` | POST /api/v1/pdf-info | 0 |
+| `exactpdf_merge_pdfs` | POST /api/v1/merge | 1 |
+| `exactpdf_split_pdf` | POST /api/v1/split | 1 |
+| `exactpdf_rotate_pdf` | POST /api/v1/rotate | 1 |
+| `exactpdf_compress_pdf` | POST /api/v1/compress | 1 |
+| `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 |
+
+## Publish checklist
+
+```bash
+npm run mcp:package:check
+cd packages/exactpdf-mcp
+npm publish --access public --provenance
+npx -y mcp-publisher publish --file server.json
+```
+
+The package must exist on the public npm registry before the MCP Registry can verify `mcpName`.
+
+## Docs
+
+- [https://exactpdf.com/docs/api](https://exactpdf.com/docs/api)
+
+## License
+
+MIT

package/dist/run.d.ts

@@ -0,0 +1,8 @@
+#!/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).
+ *
+ * @see https://exactpdf.com/docs/api
+ */
+export {};

package/dist/run.js

@@ -0,0 +1,387 @@
+#!/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).
+ *
+ * @see https://exactpdf.com/docs/api
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const BASE = (process.env.EXACTPDF_API_BASE ?? 'https://exactpdf.com').replace(/\/$/, '');
+function outputDir() {
+    return (process.env.EXACTPDF_API_OUTPUT_DIR?.trim() ||
+        process.env.EXACTPDF_MERGE_OUTPUT_DIR?.trim() ||
+        tmpdir());
+}
+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_…');
+    }
+    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.',
+});
+server.registerTool('exactpdf_account', {
+    description: 'Return ExactPDF API credit balance and key metadata. Does not consume a credit.',
+    inputSchema: z.object({}),
+}, async () => {
+    const key = requireKey();
+    const res = await fetch(`${BASE}/api/v1/account`, {
+        headers: {
+            Authorization: `Bearer ${key}`,
+            Accept: 'application/json',
+        },
+    });
+    const text = await res.text();
+    return {
+        content: [{ type: 'text', text: `HTTP ${res.status}\n${text}` }],
+    };
+});
+server.registerTool('exactpdf_merge_pdfs', {
+    description: 'Merge two or more local PDF files via ExactPDF API (1 credit). Provide absolute file paths in order.',
+    inputSchema: z.object({
+        paths: z
+            .array(z.string())
+            .min(2)
+            .describe('Absolute paths to PDF files on this machine'),
+    }),
+}, async ({ paths }) => {
+    const key = requireKey();
+    const form = new FormData();
+    for (const p of paths) {
+        const buf = await readFile(p);
+        form.append('file', new Blob([buf], { type: 'application/pdf' }), basename(p));
+    }
+    const res = await fetch(`${BASE}/api/v1/merge`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${key}`,
+        },
+        body: form,
+    });
+    const credits = res.headers.get('x-credits-remaining') ?? '?';
+    if (!res.ok) {
+        const errBody = await res.text();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Merge failed HTTP ${res.status}. Credits: ${credits}\n${errBody.slice(0, 4000)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const dir = outputDir();
+    await mkdir(dir, { recursive: true });
+    const outPath = join(dir, `exactpdf-merged-${Date.now()}.pdf`);
+    await writeFile(outPath, buf);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Merged ${paths.length} PDFs → ${outPath}\nCredits remaining: ${credits}`,
+            },
+        ],
+    };
+});
+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]].',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute path to a PDF file'),
+        at_pages: z
+            .string()
+            .optional()
+            .describe('Comma-separated split points after 1-based page numbers, e.g. "3,7"'),
+        ranges_json: z
+            .string()
+            .optional()
+            .describe('JSON array of inclusive [start,end] page ranges, e.g. "[[1,3],[4,7]]"'),
+    }),
+}, async ({ path, at_pages, ranges_json }) => {
+    const key = requireKey();
+    const form = new FormData();
+    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
+    if (ranges_json?.trim())
+        form.append('ranges', ranges_json.trim());
+    else if (at_pages?.trim())
+        form.append('at_pages', at_pages.trim());
+    const res = await fetch(`${BASE}/api/v1/split`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}` },
+        body: form,
+    });
+    const credits = res.headers.get('x-credits-remaining') ?? '?';
+    if (!res.ok) {
+        const errBody = await res.text();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Split failed HTTP ${res.status}. Credits: ${credits}\n${errBody.slice(0, 4000)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const dir = outputDir();
+    await mkdir(dir, { recursive: true });
+    const outPath = join(dir, `exactpdf-split-${Date.now()}.zip`);
+    await writeFile(outPath, buf);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Split → ${outPath}\nCredits remaining: ${credits}`,
+            },
+        ],
+    };
+});
+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.',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute path to a PDF file'),
+        angle: z
+            .union([z.literal(90), z.literal(180), z.literal(270), z.literal(-90), z.literal(-180), z.literal(-270)])
+            .describe('Clockwise rotation in degrees'),
+    }),
+}, async ({ path, angle }) => {
+    const key = requireKey();
+    const form = new FormData();
+    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
+    form.append('angle', String(angle));
+    const res = await fetch(`${BASE}/api/v1/rotate`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}` },
+        body: form,
+    });
+    const credits = res.headers.get('x-credits-remaining') ?? '?';
+    if (!res.ok) {
+        const errBody = await res.text();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Rotate failed HTTP ${res.status}. Credits: ${credits}\n${errBody.slice(0, 4000)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const dir = outputDir();
+    await mkdir(dir, { recursive: true });
+    const outPath = join(dir, `exactpdf-rotated-${Date.now()}.pdf`);
+    await writeFile(outPath, buf);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Rotated (${angle}°) → ${outPath}\nCredits remaining: ${credits}`,
+            },
+        ],
+    };
+});
+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.',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute path to a PDF file'),
+    }),
+}, async ({ path }) => {
+    const key = requireKey();
+    const form = new FormData();
+    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
+    const res = await fetch(`${BASE}/api/v1/compress`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}` },
+        body: form,
+    });
+    const credits = res.headers.get('x-credits-remaining') ?? '?';
+    if (!res.ok) {
+        const errBody = await res.text();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Compress failed HTTP ${res.status}. Credits: ${credits}\n${errBody.slice(0, 4000)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const dir = outputDir();
+    await mkdir(dir, { recursive: true });
+    const outPath = join(dir, `exactpdf-compressed-${Date.now()}.pdf`);
+    await writeFile(outPath, buf);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Compressed → ${outPath}\nCredits remaining: ${credits}`,
+            },
+        ],
+    };
+});
+server.registerTool('exactpdf_images_to_pdf', {
+    description: 'Combine local PNG/JPEG images into one PDF via ExactPDF API (1 credit). Order matches paths array.',
+    inputSchema: z.object({
+        paths: z.array(z.string()).min(1).describe('Absolute paths to PNG or JPEG files'),
+    }),
+}, async ({ paths }) => {
+    const key = requireKey();
+    const form = new FormData();
+    for (const p of paths) {
+        const buf = await readFile(p);
+        const lower = p.toLowerCase();
+        const type = lower.endsWith('.png')
+            ? 'image/png'
+            : lower.endsWith('.jpg') || lower.endsWith('.jpeg')
+                ? 'image/jpeg'
+                : 'application/octet-stream';
+        form.append('file', new Blob([buf], { type }), basename(p));
+    }
+    const res = await fetch(`${BASE}/api/v1/images-to-pdf`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}` },
+        body: form,
+    });
+    const credits = res.headers.get('x-credits-remaining') ?? '?';
+    if (!res.ok) {
+        const errBody = await res.text();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `images-to-pdf failed HTTP ${res.status}. Credits: ${credits}\n${errBody.slice(0, 4000)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const dir = outputDir();
+    await mkdir(dir, { recursive: true });
+    const outPath = join(dir, `exactpdf-from-images-${Date.now()}.pdf`);
+    await writeFile(outPath, buf);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Built PDF (${paths.length} images) → ${outPath}\nCredits remaining: ${credits}`,
+            },
+        ],
+    };
+});
+server.registerTool('exactpdf_pdf_info', {
+    description: 'Read page count and PDF metadata (title, author, …). POST /api/v1/pdf-info — does not consume a credit.',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute path to a PDF file'),
+    }),
+}, async ({ path }) => {
+    const key = requireKey();
+    const form = new FormData();
+    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
+    const res = await fetch(`${BASE}/api/v1/pdf-info`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${key}`,
+            Accept: 'application/json',
+        },
+        body: form,
+    });
+    const raw = await res.text();
+    return {
+        content: [{ type: 'text', text: `HTTP ${res.status}\n${raw.slice(0, 120_000)}` }],
+    };
+});
+server.registerTool('exactpdf_extract_text', {
+    description: 'Extract plain text from a PDF via ExactPDF API (1 credit). Returns JSON with text and page_count.',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute path to a PDF file'),
+    }),
+}, async ({ path }) => {
+    const key = requireKey();
+    const form = new FormData();
+    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
+    const res = await fetch(`${BASE}/api/v1/extract-text`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${key}`,
+            Accept: 'application/json',
+        },
+        body: form,
+    });
+    const credits = res.headers.get('x-credits-remaining') ?? '?';
+    const raw = await res.text();
+    if (!res.ok) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `extract-text failed HTTP ${res.status}. Credits: ${credits}\n${raw.slice(0, 4000)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: 'text', text: `Credits remaining: ${credits}\n${raw.slice(0, 120_000)}` }],
+    };
+});
+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.',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute path to a PDF file'),
+        mode: z
+            .enum(['developer', 'academic', 'rag'])
+            .optional()
+            .describe('Structured export profile — academic keeps page separators, rag joins short lines.'),
+    }),
+}, async ({ path, mode }) => {
+    const key = requireKey();
+    const form = new FormData();
+    form.append('file', new Blob([await readFile(path)], { type: 'application/pdf' }), basename(path));
+    if (mode)
+        form.append('mode', mode);
+    const res = await fetch(`${BASE}/api/v1/pdf-structured-markdown`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${key}`,
+            Accept: 'application/json',
+        },
+        body: form,
+    });
+    const credits = res.headers.get('x-credits-remaining') ?? '?';
+    const raw = await res.text();
+    if (!res.ok) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `pdf-structured-markdown failed HTTP ${res.status}. Credits: ${credits}\n${raw.slice(0, 8000)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: 'text', text: `Credits remaining: ${credits}\n${raw.slice(0, 120_000)}` }],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@exactpdf/mcp",
+  "version": "0.2.3",
+  "description": "MCP server for ExactPDF — PDF tools (merge, split, rotate, compress, images→PDF, metadata) and API credits.",
+  "mcpName": "com.exactpdf/mcp",
+  "type": "module",
+  "main": "./dist/run.js",
+  "exports": {
+    ".": "./dist/run.js"
+  },
+  "bin": {
+    "exactpdf-mcp": "dist/run.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "server.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://exactpdf.com/docs/api",
+  "bugs": {
+    "url": "https://exactpdf.com/docs/api",
+    "email": "support@exactpdf.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/exactpdf/exactpdf.git",
+    "directory": "packages/exactpdf-mcp"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pdf",
+    "exactpdf",
+    "cursor",
+    "claude",
+    "claude-desktop",
+    "headless-pdf",
+    "pdf-api"
+  ],
+  "author": "ExactPDF",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.17",
+    "typescript": "5.6.3"
+  }
+}

package/server.json

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