conv2pdf-mcp 0.0.1 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iris Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,103 @@
 # conv2pdf-mcp
 
-Coming soon: the official [Model Context Protocol](https://modelcontextprotocol.io) server of the [conv2pdf API](https://conv2pdf.com/en/api/).
+Official [Model Context Protocol](https://modelcontextprotocol.io) server of the [conv2pdf API](https://conv2pdf.com/en/api/). Your AI assistant converts Word, Excel, PowerPoint, Pages, images and e-books to PDF, converts PDFs to Word or to images, and merges, compresses, protects, rotates or numbers the PDFs that are on your computer. Processing runs on OVHcloud servers in France: no transfer outside the EU, no US service in the chain.
 
-This version only reserves the name. The first release is 1.0.0; its source is on [GitHub](https://github.com/jamalofski/conv2pdf-mcp).
+[Installation](#installation) · [Tools](#tools) · [How it behaves](#how-it-behaves) · [Development](#development)
+
+## Installation
+
+1. Create an account on [conv2pdf.com](https://conv2pdf.com/en/api/). The Dev plan includes 300 free conversions, valid for 12 months; see [pricing](https://conv2pdf.com/en/api/pricing/) for the paid plans.
+2. Create an API key, which starts with `cpdf_live_`, in the **Developer** tab of your dashboard. conv2pdf shows it only once, at creation.
+3. Add the server to your MCP client, with the key in the `CONV2PDF_API_KEY` environment variable. It needs [Node.js](https://nodejs.org) 22 or later.
+
+In Claude Code:
+
+```bash
+claude mcp add --env CONV2PDF_API_KEY=cpdf_live_... --transport stdio conv2pdf -- npx -y conv2pdf-mcp
+```
+
+On Windows, put `cmd /c` before `npx`.
+
+In Claude Desktop, Cursor and the other clients configured with a JSON file:
+
+```json
+{
+  "mcpServers": {
+    "conv2pdf": {
+      "command": "npx",
+      "args": ["-y", "conv2pdf-mcp"],
+      "env": { "CONV2PDF_API_KEY": "cpdf_live_..." }
+    }
+  }
+}
+```
+
+Then ask for what you need: "convert report.docx to PDF", "merge these three PDFs", "compress scan.pdf and protect it with a password".
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `convert_to_pdf` | Word, Excel, PowerPoint, OpenDocument, Apple Pages, RTF, TXT, CSV, PNG, JPG, WebP, GIF, TIFF, HEIC or EPUB file to PDF, chosen from the extension |
+| `convert_heic_to_jpg` | iPhone HEIC or HEIF photo to JPG |
+| `convert_pdf_to_word` | PDF with real text to an editable DOCX document |
+| `convert_pdf_to_images` | One PNG or JPG per page, in a ZIP file |
+| `merge_pdfs` | Combine several PDFs into one, in the order given |
+| `extract_pdf_pages` | Keep the pages you list, such as `1-5,7,10-12`, in a new PDF |
+| `rotate_pdf` | Turn every page by 90, 180 or 270 degrees |
+| `add_page_numbers` | Number the pages, as "3 / 12" or "3", bottom center, left or right |
+| `add_watermark` | Stamp a text of up to 50 characters on every page |
+| `compress_pdf` | Reduce the size, keeping images at 72, 150 or 300 DPI |
+| `protect_pdf` | Set a password, and optionally forbid printing or copying |
+| `unlock_pdf` | Remove a password you know, or the printing and copying restrictions |
+| `get_quota` | Plan, usage and limits of the API key |
+
+## How it behaves
+
+- **Files stay on your computer, except for the conversion.** A tool takes the path of a file, sends the file to conv2pdf and writes the result on your disk. conv2pdf checks the content of the file, not only its name.
+- **Nothing is overwritten.** The result goes next to the input file: `report.docx` gives `report.pdf`, and a PDF tool adds a suffix, such as `report-compressed.pdf`. When that name is taken, the server writes `report (2).pdf`. The assistant can choose the place with `output_path`; if a file is already there, the tool refuses before converting anything.
+- **Deleted from the server.** Once the result is on your disk, the server deletes the job from conv2pdf. Should that fail, conv2pdf deletes the files after one hour.
+- **Quota.** Each conversion counts as one in the quota of your plan, including one that conv2pdf refuses after reading the file, such as an unreadable or scanned PDF, or one with too many pages. A file refused on arrival (wrong type, too large, password missing), a refused setting (a page range that does not exist, a password that is too short) and a failure on the side of conv2pdf count for nothing, and `get_quota` is free. Files can weigh up to 10 MB on the Dev plan and 200 MB on paid plans.
+- **Rate limit.** The API accepts 20 conversions per minute per API key. When it asks to slow down, or when its queue is full, the server waits for the delay the API gives and tries again, twice at most and only for delays of 30 seconds or less; otherwise the assistant gets the delay to wait.
+- **Protected PDFs.** The tools that read a PDF, except `merge_pdfs`, open one that asks for a password when the assistant passes it as `password`. The result has no password. For a merge, unlock the protected PDFs first.
+- **Pages and Numbers.** A Pages document keeps its `.pages` extension: only the name tells it from a Numbers spreadsheet, which conv2pdf does not convert, like Keynote presentations.
+- **Errors.** A refusal comes back to the assistant as a sentence it can act on: the wrong password, the page range that does not exist, the plan limit, the key to set. A cancelled call stops the transfer and leaves no file behind.
+- **Without a key.** The server starts and lists its tools; a call explains how to set `CONV2PDF_API_KEY`.
+
+Every request carries `User-Agent: conv2pdf-mcp/<version>`. Mention it when you contact support: it tells your calls apart in the API's logs.
+
+## Development
+
+The server has no dependency: Node.js runs the sources as they are. It talks to its client over stdio and serves both eras of the protocol from the same process: revision 2026-07-28, where each request carries its protocol version, and the earlier revisions (2025-11-25 down to 2024-11-05), which start with an `initialize` handshake.
+
+```bash
+npm test
+```
+
+runs the tests against a fake conv2pdf API on a local port: no key and no network are needed.
+
+```bash
+npm run check-tools
+```
+
+compares the extensions `convert_to_pdf` routes on with what the live API accepts (`GET /v1/tools`).
+
+### Releasing
+
+1. Set the version in `package.json` and `server.json`, and date its section in `CHANGELOG.md`.
+2. Run `npm test` and `npm run check-tools`.
+3. Commit, then push a tag named after the version: the **Publish** workflow publishes the package to npm through Trusted Publishing, with a provenance statement.
+4. Publish the entry of the [MCP Registry](https://registry.modelcontextprotocol.io): `mcp-publisher login http --domain conv2pdf.com`, then `mcp-publisher publish`. The name `com.conv2pdf/conv2pdf` is proved by the public key served at `https://conv2pdf.com/.well-known/mcp-registry-auth`.
+
+## Resources
+
+- [conv2pdf API documentation](https://conv2pdf.com/en/api/docs/)
+- [Model Context Protocol specification](https://modelcontextprotocol.io/specification/2026-07-28)
+
+## Support
+
+Open an [issue](https://github.com/jamalofski/conv2pdf-mcp/issues) or write to contact@conv2pdf.com.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/bin/conv2pdf-mcp.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { main, version } from '../src/index.js';
+
+const HELP = `conv2pdf-mcp ${version}
+MCP server of the conv2pdf API. An MCP client starts it and talks to it over stdio:
+
+  {
+    "mcpServers": {
+      "conv2pdf": {
+        "command": "npx",
+        "args": ["-y", "conv2pdf-mcp"],
+        "env": { "CONV2PDF_API_KEY": "cpdf_live_..." }
+      }
+    }
+  }
+
+Documentation: https://github.com/jamalofski/conv2pdf-mcp
+`;
+
+const argument = process.argv[2];
+if (argument === '--version' || argument === '-v') {
+  process.stdout.write(`${version}\n`);
+} else if (argument === '--help' || argument === '-h') {
+  process.stdout.write(HELP);
+} else {
+  await main();
+}

package/package.json

@@ -1,15 +1,47 @@
 {
   "name": "conv2pdf-mcp",
-  "version": "0.0.1",
-  "description": "Coming soon: the official MCP server of the conv2pdf API. This version only reserves the name.",
+  "version": "1.0.1",
+  "description": "Official MCP server of the conv2pdf API: an AI assistant converts Office documents, images and e-books to PDF, and merges, splits, compresses, protects or converts the PDFs of your computer. Hosted in France.",
   "license": "MIT",
   "homepage": "https://conv2pdf.com/en/api/",
-  "author": "Jamal Tantaoui",
+  "mcpName": "com.conv2pdf/conv2pdf",
+  "type": "module",
+  "bin": {
+    "conv2pdf-mcp": "bin/conv2pdf-mcp.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "conv2pdf",
+    "pdf",
+    "pdf conversion",
+    "word to pdf",
+    "docx to pdf",
+    "pdf to word",
+    "merge pdf",
+    "compress pdf"
+  ],
+  "author": {
+    "name": "Jamal Tantaoui",
+    "email": "contact@conv2pdf.com"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jamalofski/conv2pdf-mcp.git"
   },
-  "files": [
-    "README.md"
-  ]
+  "bugs": {
+    "url": "https://github.com/jamalofski/conv2pdf-mcp/issues"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "check-tools": "node scripts/check-tools.mjs"
+  }
 }

package/src/api.js

@@ -0,0 +1,110 @@
+// The conv2pdf API, as the tools need it: convert files, download the result, read the quota.
+import { openAsBlob } from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_BASE_URL = 'https://api.conv2pdf.com/v1';
+
+// conv2pdf gives a conversion 90 seconds; the rest of the time is the transfer of a file
+// of up to 200 MB, both ways, on the user's connection. A backstop: the MCP client has
+// its own timeout and cancels the request first.
+const REQUEST_TIMEOUT_MS = 5 * 60_000;
+
+// The API answers 429 `rate_limited` and 503 `server_busy` with a Retry-After header:
+// no conversion was counted, so both are safe to retry. A tool call must not hang for
+// minutes though: beyond these bounds the error goes back to the model, with the delay.
+const MAX_RETRIES = 2;
+const MAX_WAIT_SECONDS = 30;
+const DEFAULT_RETRY_AFTER_SECONDS = 30;
+
+/** A response of the API that is not a success: HTTP status, JSON body, seconds to wait. */
+export class ApiError extends Error {
+  constructor(status, body, retryAfter) {
+    super(`conv2pdf answered HTTP ${status}`);
+    this.status = status;
+    this.body = body;
+    this.code = typeof body.error === 'string' ? body.error : undefined;
+    this.retryAfter = retryAfter;
+  }
+}
+
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+  const timer = setTimeout(resolve, ms);
+  signal?.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }, { once: true });
+});
+
+async function jsonOf(response) {
+  try {
+    const body = await response.json();
+    return body !== null && typeof body === 'object' && !Array.isArray(body) ? body : {};
+  } catch {
+    // Not JSON: an HTML error page from a proxy, for example.
+    return {};
+  }
+}
+
+function retryAfterSeconds(response, body) {
+  const seconds = Number(response.headers.get('retry-after') ?? body.retry_after);
+  return Number.isFinite(seconds) && seconds > 0 ? Math.ceil(seconds) : DEFAULT_RETRY_AFTER_SECONDS;
+}
+
+/**
+ *   apiKey: the conv2pdf API key
+ *   baseUrl: the API root, changed only by the tests
+ *   userAgent: `conv2pdf-mcp/<version>`
+ */
+export function createClient({ apiKey, baseUrl = DEFAULT_BASE_URL, userAgent, wait = sleep }) {
+  // `makeBody` builds the body again for each attempt: a sent body cannot be sent twice.
+  async function request(method, pathname, { makeBody, signal } = {}) {
+    for (let attempt = 0; ; attempt++) {
+      const response = await fetch(`${baseUrl}${pathname}`, {
+        method,
+        headers: { Authorization: `Bearer ${apiKey}`, 'User-Agent': userAgent },
+        body: makeBody ? await makeBody() : undefined,
+        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]) : AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+      if (response.ok) return response;
+      const body = await jsonOf(response);
+      const retryAfter = retryAfterSeconds(response, body);
+      const retryable =
+        (response.status === 429 && body.error === 'rate_limited') ||
+        (response.status === 503 && body.error === 'server_busy');
+      if (!retryable || attempt >= MAX_RETRIES || retryAfter > MAX_WAIT_SECONDS) {
+        throw new ApiError(response.status, body, retryable ? retryAfter : undefined);
+      }
+      await wait(retryAfter * 1000, signal);
+    }
+  }
+
+  return {
+    /**
+     * Sends the files to a tool. Resolves to the job of the API (`job_id`, `size_bytes`,
+     * `quota`) and to the response that streams the result.
+     */
+    async convert(tool, files, fields, { signal } = {}) {
+      const makeBody = async () => {
+        const form = new FormData();
+        // File-backed blobs: a 200 MB file is streamed, never held in memory.
+        for (const file of files) form.append('file', await openAsBlob(file), path.basename(file));
+        for (const [name, value] of Object.entries(fields)) form.append(name, String(value));
+        return form;
+      };
+      const converted = await request('POST', `/convert/${tool}`, { makeBody, signal });
+      const job = await jsonOf(converted);
+      const download = await request('GET', `/download/${encodeURIComponent(job.job_id)}`, { signal });
+      return { job, download };
+    },
+
+    /** Deletes the files of a job from conv2pdf. Best effort: they expire after one hour anyway. */
+    async deleteJob(jobId) {
+      try {
+        await request('DELETE', `/job/${encodeURIComponent(jobId)}`);
+      } catch {
+        // Nothing to report: the result is already on disk.
+      }
+    },
+
+    async quota({ signal } = {}) {
+      return jsonOf(await request('GET', '/quota', { signal }));
+    },
+  };
+}

package/src/files.js

@@ -0,0 +1,66 @@
+// The paths the model gives: where the input is read and where the result is written.
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/** A problem with a path or an argument: its message becomes the tool error. */
+export class InputError extends Error {}
+
+/** An absolute path for what the model wrote: `~` is the home folder, the rest is relative to the working directory. */
+export function resolvePath(given, argument) {
+  if (typeof given !== 'string' || given.trim() === '') {
+    throw new InputError(`"${argument}" must be the path of a file.`);
+  }
+  const inHome = given === '~' || given.startsWith('~/') || given.startsWith('~\\');
+  return path.resolve(inHome ? path.join(os.homedir(), given.slice(1)) : given);
+}
+
+/** The absolute path of an existing input file. */
+export async function inputFile(given, argument) {
+  const file = resolvePath(given, argument);
+  let stats;
+  try {
+    stats = await fs.stat(file);
+  } catch {
+    throw new InputError(`File not found: ${file}`);
+  }
+  if (!stats.isFile()) throw new InputError(`Not a file: ${file}`);
+  return file;
+}
+
+/**
+ * Creates the output file, empty, before the conversion starts, and returns its path and
+ * its handle. Created exclusively: an existing file is never overwritten, and a refusal
+ * comes before any conversion is counted.
+ *   requested: the `output_path` of the model, if any
+ *   input: the input file the default name derives from
+ *   suffix, extension: `report.pdf` + `-compressed` + `.pdf` gives `report-compressed.pdf`
+ */
+export async function reserveOutput({ requested, input, suffix, extension }) {
+  if (requested !== undefined) {
+    const target = resolvePath(requested, 'output_path');
+    try {
+      return { file: target, handle: await fs.open(target, 'wx') };
+    } catch (error) {
+      if (error.code === 'EEXIST') throw new InputError(`${target} already exists: give another "output_path". Nothing was converted.`);
+      if (error.code === 'ENOENT') throw new InputError(`The folder ${path.dirname(target)} does not exist. Nothing was converted.`);
+      throw new InputError(`Cannot write ${target}: ${error.message}. Nothing was converted.`);
+    }
+  }
+  const { dir, name } = path.parse(input);
+  for (let n = 1; ; n++) {
+    const target = path.join(dir, `${name}${suffix}${n === 1 ? '' : ` (${n})`}${extension}`);
+    try {
+      return { file: target, handle: await fs.open(target, 'wx') };
+    } catch (error) {
+      if (error.code === 'EEXIST') continue;
+      throw new InputError(`Cannot write ${target}: ${error.message}. Give an "output_path" in a folder that can be written. Nothing was converted.`);
+    }
+  }
+}
+
+/** Removes the reserved file when no result came to fill it. */
+export async function discardOutput({ file, handle }) {
+  await handle.close().catch(() => {});
+  await fs.unlink(file).catch(() => {});
+}

package/src/index.js

@@ -0,0 +1,29 @@
+import { createRequire } from 'node:module';
+
+import { DEFAULT_BASE_URL, createClient } from './api.js';
+import { createServer, serveStdio } from './protocol.js';
+import { INSTRUCTIONS, createTools } from './tools.js';
+
+export const { version } = createRequire(import.meta.url)('../package.json');
+
+/**
+ * Runs the MCP server on the standard streams until the client closes the input.
+ *   CONV2PDF_API_KEY: the API key, required to call a tool
+ *   CONV2PDF_API_URL: another root for the API, for the tests
+ */
+export function main({ env = process.env, input = process.stdin, output = process.stdout } = {}) {
+  const apiKey = (env.CONV2PDF_API_KEY ?? '').trim();
+  const api = createClient({
+    apiKey,
+    baseUrl: env.CONV2PDF_API_URL || DEFAULT_BASE_URL,
+    userAgent: `conv2pdf-mcp/${version}`,
+  });
+  const { tools, callTool } = createTools({ api, hasKey: apiKey !== '' });
+  const server = createServer({
+    info: { name: 'conv2pdf', title: 'conv2pdf', version, websiteUrl: 'https://conv2pdf.com/en/api/' },
+    instructions: INSTRUCTIONS,
+    tools,
+    callTool,
+  });
+  return serveStdio(server, { input, output });
+}

package/src/messages.js

@@ -0,0 +1,119 @@
+// What a refusal of the conv2pdf API means, said to the model: it reads this text, so it
+// must tell what to change or what to report to the user.
+
+const PRICING_URL = 'https://conv2pdf.com/en/api/pricing/';
+export const KEYS_URL = 'https://conv2pdf.com/en/dashboard/#developer';
+
+export const NO_KEY =
+  'No conv2pdf API key. Set the CONV2PDF_API_KEY environment variable in the configuration of this MCP server. ' +
+  `Keys are created in the Developer tab of the conv2pdf dashboard: ${KEYS_URL}`;
+
+// A table entry for a value from the API, never a property every object inherits.
+const own = (table, key) => (typeof key === 'string' && Object.hasOwn(table, key) ? table[key] : undefined);
+
+const megabytes = (bytes) => `${Math.round(bytes / (1024 * 1024))} MB`;
+
+const OFFICE_ELSEWHERE = 'This file is an office document: use convert_to_pdf, with the extension of its real format.';
+const IMAGE_ELSEWHERE = 'This file is an image: use convert_to_pdf, with the extension of its real format.';
+const WEB_PAGE = 'This file contains a web page, not the expected document.';
+
+// What conv2pdf found in a file that does not match the tool (`detected_type`).
+const CONTENT_HINTS = {
+  pdf: 'This file is already a PDF.',
+  epub: 'This file is an EPUB e-book: give it the .epub extension and use convert_to_pdf.',
+  pages: OFFICE_ELSEWHERE,
+  docx: OFFICE_ELSEWHERE,
+  xlsx: OFFICE_ELSEWHERE,
+  pptx: OFFICE_ELSEWHERE,
+  odt: OFFICE_ELSEWHERE,
+  ods: OFFICE_ELSEWHERE,
+  odp: OFFICE_ELSEWHERE,
+  odg: OFFICE_ELSEWHERE,
+  png: IMAGE_ELSEWHERE,
+  jpeg: IMAGE_ELSEWHERE,
+  gif: IMAGE_ELSEWHERE,
+  webp: IMAGE_ELSEWHERE,
+  tiff: IMAGE_ELSEWHERE,
+  heic: 'This file is a HEIC photo: give it the .heic extension and use convert_to_pdf or convert_heic_to_jpg.',
+  html: WEB_PAGE,
+  xml: WEB_PAGE,
+  svg: WEB_PAGE,
+  text: 'This file contains plain text, not the expected document.',
+  image_corrupt: 'This image is damaged or incomplete.',
+  zip_corrupt: 'This file is damaged or incomplete.',
+  msg: 'This file is an Outlook message (.msg), not a document.',
+  iwork_numbers:
+    'This file is a Numbers spreadsheet, which conv2pdf does not convert. In Numbers, choose File > Export To > PDF.',
+  iwork_keynote:
+    'This file is a Keynote presentation, which conv2pdf does not convert. In Keynote, choose File > Export To > PDF.',
+  iwork: 'conv2pdf converts Apple Pages documents only, named with their .pages extension.',
+};
+
+// One entry per code of the `error` field, as text or built from the response body.
+const MESSAGES = {
+  invalid_api_key: `conv2pdf did not accept the API key. Check CONV2PDF_API_KEY in the configuration of this MCP server. Keys are created in the Developer tab of the conv2pdf dashboard: ${KEYS_URL}`,
+  account_not_provisioned: `This API key has no conv2pdf API plan. Plans: ${PRICING_URL}`,
+  quota_exceeded: `The conv2pdf quota of this API key is used up. Paid plans renew it every month, the Dev trial does not. Plans: ${PRICING_URL}`,
+  credits_expired: `The conv2pdf trial credits have expired. Plans: ${PRICING_URL}`,
+  rate_limited: (body, retryAfter) => `The conv2pdf rate limit is reached. Try again in ${retryAfter} seconds.`,
+  server_busy: (body, retryAfter) => `The conv2pdf conversion queue is full. Try again in ${retryAfter} seconds.`,
+  file_too_large: (body) =>
+    `The file is larger than ${Number.isInteger(body.max_bytes) ? `the ${megabytes(body.max_bytes)} per file` : 'what'} this conv2pdf plan allows. Plans: ${PRICING_URL}`,
+  payload_too_large: 'The request is larger than conv2pdf accepts.',
+  plan_limit_files: `This conv2pdf plan does not merge that many files at once: 2 on the Dev plan, up to 20 on paid plans. Plans: ${PRICING_URL}`,
+  not_enough_files: 'Merging needs at least 2 PDFs.',
+  too_many_files: 'conv2pdf merges up to 20 PDFs at a time.',
+  unsupported_content: (body) =>
+    own(CONTENT_HINTS, body.detected_type) ||
+    'The content of the file does not match this tool: conv2pdf checks what the file contains, not only its name.',
+  unsupported_format: 'conv2pdf cannot read this image format. Use a PNG, JPG, WebP, GIF or TIFF image.',
+  empty_file: 'The file is empty.',
+  source_unreadable: 'conv2pdf could not read this file: it may be damaged or incomplete.',
+  field_required: (body) => `The "${typeof body.field === 'string' ? body.field : 'required'}" field is empty.`,
+  invalid_page_range: (body) =>
+    `The pages${typeof body.range === 'string' ? ` "${body.range}"` : ''} are not valid${Number.isInteger(body.total_pages) ? ` for this PDF of ${body.total_pages} page${body.total_pages === 1 ? '' : 's'}` : ''}. Use page numbers and ranges separated by commas, such as 1-5,7,10-12.`,
+  invalid_rotation: 'The rotation must be 90, 180 or 270 degrees.',
+  invalid_format: 'This format is not accepted by the tool.',
+  invalid_quality: 'The quality must be low, medium or high.',
+  password_protected: 'The file is protected with a password. For a PDF, remove it first with unlock_pdf. A DRM-protected e-book or a locked iWork document cannot be converted.',
+  needs_password: 'The PDF asks for a password to open: pass it as "password".',
+  wrong_password: 'The password does not open this PDF.',
+  password_too_short: (body) => `The password must have at least ${Number.isInteger(body.min) ? body.min : 6} characters.`,
+  password_too_long: (body) => `The password must have at most ${Number.isInteger(body.max) ? body.max : 64} characters.`,
+  pdf_already_protected: 'The PDF is already protected with a password. Remove it first with unlock_pdf.',
+  pdf_not_protected: 'The PDF has no password or restriction to remove.',
+  pdf_scanned_needs_ocr: 'This PDF is a scan without text, so it cannot be converted to Word.',
+  pdf_too_many_pages: 'The PDF has too many pages for this tool.',
+  too_many_pages: (body) =>
+    Number.isInteger(body.max_pages)
+      ? `The document has more than the ${body.max_pages.toLocaleString('en-US')} pages this tool accepts.`
+      : 'The document has too many pages for this tool.',
+  unsupported_characters: 'The watermark text has no character conv2pdf can print: use Latin letters, digits and punctuation.',
+  epub_blank_output:
+    'This e-book cannot be converted: its pages are full-screen images (comics, picture books, manga), and their layout does not survive the conversion to PDF.',
+  epub_too_long: 'The e-book is longer than the 1,500 pages conv2pdf converts at once.',
+  output_too_large: 'The result is too large to be delivered.',
+  // The API refunds the quota on these two, and on a refused setting (page range, rotation,
+  // password length). A refusal that follows the reading of the file (unreadable or scanned
+  // PDF, too many pages) stays counted.
+  conversion_failed: 'conv2pdf could not process this file. The failure is on its side and is not counted against the quota.',
+  conversion_timeout: 'The conversion took too long and was stopped. It is not counted against the quota.',
+  file_expired: 'The converted file is no longer available on conv2pdf.',
+  job_deleted: 'The conversion was deleted on conv2pdf before it could be downloaded.',
+};
+MESSAGES.missing_bearer_token = MESSAGES.invalid_api_key;
+
+/**
+ * The text of a tool error for an ApiError. A tool words a code itself through `overrides`,
+ * when the general text would point the model at the wrong fix.
+ */
+export function apiErrorText(error, overrides = {}) {
+  const { status, body, code, retryAfter } = error;
+  const message = own(overrides, code) ?? own(MESSAGES, code);
+  if (message) return typeof message === 'function' ? message(body, retryAfter) : message;
+  if (status === 401) return MESSAGES.invalid_api_key;
+  if (status >= 500) {
+    return 'conv2pdf is temporarily unavailable: try again in a few minutes.';
+  }
+  return code ? `conv2pdf refused the request (${code}).` : `conv2pdf returned HTTP ${status}.`;
+}

package/src/protocol.js

@@ -0,0 +1,206 @@
+// The Model Context Protocol over stdio, for a server that only offers tools.
+//
+// No dependency and no state: one JSON-RPC message per line in, one per line out. Both
+// protocol eras are served by the same process, chosen request by request as the
+// specification asks of a "dual-era" server:
+//   - 2026-07-28: no handshake, each request carries its protocol version and the client
+//     capabilities in `_meta`, and `server/discover` describes the server;
+//   - 2025-11-25 and earlier: `initialize`, then plain requests.
+// Specification: https://modelcontextprotocol.io/specification/2026-07-28
+
+export const MODERN_VERSIONS = ['2026-07-28'];
+export const LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+export const SUPPORTED_VERSIONS = [...MODERN_VERSIONS, ...LEGACY_VERSIONS];
+
+const META_VERSION = 'io.modelcontextprotocol/protocolVersion';
+const META_CLIENT_CAPABILITIES = 'io.modelcontextprotocol/clientCapabilities';
+const META_SERVER_INFO = 'io.modelcontextprotocol/serverInfo';
+
+// JSON-RPC codes, then the one the MCP specification reserves (2026-07-28).
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+
+// The tool list only changes with a new version of the package: a client may keep it
+// for an hour, and it is the same for everyone.
+const CACHE_HINTS = { ttlMs: 60 * 60 * 1000, cacheScope: 'public' };
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const rpcError = (id, code, message, data) => ({
+  jsonrpc: '2.0',
+  id: id === undefined ? null : id,
+  error: data === undefined ? { code, message } : { code, message, data },
+});
+
+/**
+ * A tools-only MCP server.
+ *   info: { name, title, version, websiteUrl }
+ *   instructions: guidance for the model
+ *   tools: [{ name, title, description, inputSchema, annotations }]
+ *   callTool(name, args, { signal }): the tool result, { content, structuredContent?, isError? }
+ * Returns { handle(message), close() }: `handle` resolves to the response to write, or to
+ * undefined when there is none (a notification, a cancelled request).
+ */
+export function createServer({ info, instructions, tools, callTool }) {
+  const names = new Set(tools.map((tool) => tool.name));
+  // The requests being processed, to abort one when the client cancels it.
+  const running = new Map();
+
+  async function runTool(id, params) {
+    const name = isObject(params) ? params.name : undefined;
+    if (!names.has(name)) return { error: [INVALID_PARAMS, `Unknown tool: ${String(name).slice(0, 100)}`] };
+    const args = params.arguments === undefined ? {} : params.arguments;
+    if (!isObject(args)) return { error: [INVALID_PARAMS, 'Invalid params: "arguments" must be an object'] };
+    const controller = new AbortController();
+    running.set(id, controller);
+    try {
+      const result = await callTool(name, args, { signal: controller.signal });
+      return controller.signal.aborted ? { cancelled: true } : { result };
+    } catch (error) {
+      if (controller.signal.aborted) return { cancelled: true };
+      throw error;
+    } finally {
+      running.delete(id);
+    }
+  }
+
+  async function handle(message) {
+    if (!isObject(message) || message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+      return rpcError(undefined, INVALID_REQUEST, 'Invalid request: expected one JSON-RPC 2.0 request or notification');
+    }
+    const { id, method, params } = message;
+    if (id === undefined) {
+      // On stdio a client cancels a request with a notification; the others need no action.
+      if (method === 'notifications/cancelled' && isObject(params)) running.get(params.requestId)?.abort();
+      return undefined;
+    }
+    if (typeof id !== 'string' && typeof id !== 'number') {
+      return rpcError(undefined, INVALID_REQUEST, 'Invalid request: "id" must be a string or a number');
+    }
+    if (params !== undefined && !isObject(params)) {
+      return rpcError(id, INVALID_REQUEST, 'Invalid request: "params" must be an object');
+    }
+
+    try {
+      // The body decides the era: a request that carries its version in `_meta` belongs
+      // to 2026-07-28, any other to the handshake era.
+      const meta = isObject(params) && isObject(params._meta) ? params._meta : {};
+      const claimed = meta[META_VERSION];
+
+      if (claimed !== undefined) {
+        if (typeof claimed !== 'string') {
+          return rpcError(id, INVALID_PARAMS, `Invalid params: _meta field ${META_VERSION} must be a string`);
+        }
+        if (!MODERN_VERSIONS.includes(claimed)) {
+          return rpcError(id, UNSUPPORTED_PROTOCOL_VERSION, 'Unsupported protocol version', {
+            supported: SUPPORTED_VERSIONS,
+            requested: claimed,
+          });
+        }
+        if (!isObject(meta[META_CLIENT_CAPABILITIES])) {
+          return rpcError(id, INVALID_PARAMS, `Invalid params: missing required _meta field ${META_CLIENT_CAPABILITIES}`);
+        }
+        const complete = (result, cacheable) => ({
+          jsonrpc: '2.0',
+          id,
+          result: {
+            resultType: 'complete',
+            ...result,
+            ...(cacheable ? CACHE_HINTS : {}),
+            _meta: { [META_SERVER_INFO]: info },
+          },
+        });
+        if (method === 'server/discover') {
+          return complete({ supportedVersions: SUPPORTED_VERSIONS, capabilities: { tools: {} }, instructions }, true);
+        }
+        if (method === 'tools/list') return complete({ tools }, true);
+        if (method === 'tools/call') {
+          const outcome = await runTool(id, params);
+          if (outcome.cancelled) return undefined;
+          return outcome.error ? rpcError(id, ...outcome.error) : complete(outcome.result, false);
+        }
+        return rpcError(id, METHOD_NOT_FOUND, `Method not found: ${method.slice(0, 100)}`);
+      }
+
+      if (method === 'initialize') {
+        const requested = isObject(params) ? params.protocolVersion : undefined;
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: {
+            // The requested version when we speak it, else our latest of this era: the
+            // client decides whether it can do with it.
+            protocolVersion: LEGACY_VERSIONS.includes(requested) ? requested : LEGACY_VERSIONS[0],
+            capabilities: { tools: {} },
+            serverInfo: info,
+            instructions,
+          },
+        };
+      }
+      if (method === 'ping') return { jsonrpc: '2.0', id, result: {} };
+      if (method === 'tools/list') return { jsonrpc: '2.0', id, result: { tools } };
+      if (method === 'tools/call') {
+        const outcome = await runTool(id, params);
+        if (outcome.cancelled) return undefined;
+        return outcome.error ? rpcError(id, ...outcome.error) : { jsonrpc: '2.0', id, result: outcome.result };
+      }
+      return rpcError(id, METHOD_NOT_FOUND, `Method not found: ${method.slice(0, 100)}`);
+    } catch (error) {
+      return rpcError(id, INTERNAL_ERROR, `Internal error: ${error && error.message ? error.message : 'unknown'}`);
+    }
+  }
+
+  // Stops the requests still running: the client is gone, nobody reads their result.
+  function close() {
+    for (const controller of running.values()) controller.abort();
+  }
+
+  return { handle, close };
+}
+
+/**
+ * Connects a server to a pair of streams: newline-delimited JSON-RPC, nothing else on
+ * the output. Resolves when the input ends and the last response is written.
+ */
+export function serveStdio(server, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    const pending = new Set();
+    let buffer = '';
+    let ended = false;
+    const write = (response) => output.write(`${JSON.stringify(response)}\n`);
+    const settle = () => { if (ended && pending.size === 0) resolve(); };
+
+    const dispatch = (line) => {
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        write(rpcError(undefined, PARSE_ERROR, 'Parse error: the line is not valid JSON'));
+        return;
+      }
+      const task = server.handle(message).then((response) => { if (response) write(response); });
+      pending.add(task);
+      task.finally(() => { pending.delete(task); settle(); });
+    };
+
+    input.setEncoding('utf8');
+    input.on('data', (chunk) => {
+      buffer += chunk;
+      for (let end = buffer.indexOf('\n'); end !== -1; end = buffer.indexOf('\n')) {
+        const line = buffer.slice(0, end).trim();
+        buffer = buffer.slice(end + 1);
+        if (line) dispatch(line);
+      }
+    });
+    // A closed input is the client's way to stop the server.
+    input.on('end', () => {
+      ended = true;
+      server.close();
+      settle();
+    });
+  });
+}

package/src/tools.js

@@ -0,0 +1,349 @@
+// The tools of the server: what the model reads, and what a call does.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+import { ApiError } from './api.js';
+import { InputError, discardOutput, inputFile, reserveOutput } from './files.js';
+import { NO_KEY, apiErrorText } from './messages.js';
+
+export const INSTRUCTIONS =
+  'conv2pdf converts and edits files that are on this computer: Office documents, images and e-books to PDF, ' +
+  'PDF to Word or to images, and merging, extracting pages, rotating, numbering, watermarking, compressing, ' +
+  'protecting or unlocking PDFs. Give a tool the path of the file: the result is written next to it, or at ' +
+  'output_path, and its path is returned. The files are uploaded to conv2pdf, hosted in France, which deletes ' +
+  'them once the result is downloaded. Each conversion uses one unit of the quota of the API key, including one ' +
+  'that conv2pdf refuses after reading the file (an unreadable or scanned PDF, too many pages); a refused setting, ' +
+  'such as a page range that does not exist, and a failure on the side of conv2pdf are not counted. get_quota ' +
+  'tells what is left.';
+
+// convert_to_pdf picks the conv2pdf tool from the extension of the file. These lists are
+// the `accepted_exts` of GET /v1/tools: `npm run check-tools` compares them.
+export const TO_PDF_TOOLS = {
+  'office-to-pdf': [
+    '.doc', '.docx', '.docm', '.odt', '.rtf', '.txt', '.xls', '.xlsx', '.xlsm', '.ods', '.csv', '.ppt', '.pptx',
+    '.pptm', '.odp', '.odg', '.sxw', '.sxc', '.sxi', '.sxd', '.pages', '.fodt', '.fods', '.fodp', '.fodg',
+  ],
+  'image-to-pdf': ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.tiff', '.tif'],
+  'heic-to-pdf': ['.heic', '.heif'],
+  'epub-to-pdf': ['.epub'],
+};
+
+function toPdfTool(input) {
+  const extension = path.extname(input).toLowerCase();
+  for (const [tool, extensions] of Object.entries(TO_PDF_TOOLS)) {
+    if (extensions.includes(extension)) return tool;
+  }
+  throw new InputError(
+    `convert_to_pdf cannot convert ${extension ? `a ${extension} file` : 'a file without extension'}. ` +
+    `It accepts: ${Object.values(TO_PDF_TOOLS).flat().join(' ')}`,
+  );
+}
+
+const SENT = 'The file is uploaded to conv2pdf and the call counts as one conversion.';
+
+const INPUT_PATH = {
+  type: 'string',
+  description: 'Path of the file on this computer: absolute, or relative to the working directory of the server.',
+};
+const OUTPUT_PATH = {
+  type: 'string',
+  description:
+    'Where to write the result. Optional: by default next to the input file, under a name that is not taken. An existing file is never overwritten.',
+};
+const PDF_PASSWORD = {
+  type: 'string',
+  description: 'Password of the PDF, only if it asks for one to open. The result has no password.',
+};
+
+// One entry per tool that converts files:
+//   api: the conv2pdf tool, or a function of the input file that names it
+//   properties, required: the arguments besides input_path and output_path
+//   fields: the form fields sent with the file, from the arguments
+//   suffix, extension: the default name of the result
+//   messages: the API error codes this tool words itself
+const FILE_TOOLS = [
+  {
+    name: 'convert_to_pdf',
+    title: 'Convert to PDF',
+    description:
+      'Converts a document, an image or an e-book to PDF: Word, Excel, PowerPoint, OpenDocument, Apple Pages, RTF, TXT, CSV, PNG, JPG, WebP, GIF, TIFF, HEIC and EPUB. The converter is chosen from the extension of the file.',
+    api: toPdfTool,
+    extension: '.pdf',
+  },
+  {
+    name: 'convert_heic_to_jpg',
+    title: 'Convert HEIC to JPG',
+    description: 'Converts an iPhone HEIC or HEIF photo to a JPG image.',
+    api: 'heic-to-jpg',
+    extension: '.jpg',
+  },
+  {
+    name: 'convert_pdf_to_word',
+    title: 'Convert PDF to Word',
+    description:
+      'Converts a PDF that contains real text to an editable Word document (DOCX). A scanned PDF, made of images without text, is refused.',
+    api: 'pdf-to-word',
+    properties: { password: PDF_PASSWORD },
+    fields: (args) => ({ password: args.password }),
+    extension: '.docx',
+  },
+  {
+    name: 'convert_pdf_to_images',
+    title: 'Convert PDF to Images',
+    description:
+      'Renders each page of a PDF as an image at 150 DPI. The result is one ZIP archive with an image per page. Up to 100 pages.',
+    api: 'pdf-to-image',
+    properties: {
+      format: { type: 'string', enum: ['png', 'jpg'], description: 'Format of the images. Default: png.' },
+      password: PDF_PASSWORD,
+    },
+    fields: (args) => ({ format: args.format, password: args.password }),
+    extension: '.zip',
+  },
+  {
+    name: 'merge_pdfs',
+    title: 'Merge PDFs',
+    description:
+      'Combines several PDFs into one, in the order given. 2 files on the Dev plan, up to 20 on paid plans. The result is written next to the first file.',
+    api: 'merge-pdf',
+    multiple: true,
+    suffix: '-merged',
+    messages: {
+      needs_password: 'One of the PDFs is protected with a password: remove it first with unlock_pdf.',
+      password_protected: 'One of the PDFs is protected with a password: remove it first with unlock_pdf.',
+    },
+  },
+  {
+    name: 'extract_pdf_pages',
+    title: 'Extract Pages From PDF',
+    description: 'Keeps some pages of a PDF in a new PDF. The pages keep the order they have in the document.',
+    api: 'split-pdf',
+    properties: {
+      pages: {
+        type: 'string',
+        description: 'Pages to keep: numbers and ranges separated by commas, such as 1-5,7,10-12.',
+      },
+      password: PDF_PASSWORD,
+    },
+    required: ['pages'],
+    fields: (args) => ({ ranges: args.pages, password: args.password }),
+    suffix: '-pages',
+  },
+  {
+    name: 'rotate_pdf',
+    title: 'Rotate PDF',
+    description: 'Rotates every page of a PDF clockwise.',
+    api: 'rotate-pdf',
+    properties: {
+      rotation: { type: 'integer', enum: [90, 180, 270], description: 'Rotation in degrees, clockwise.' },
+      password: PDF_PASSWORD,
+    },
+    required: ['rotation'],
+    fields: (args) => ({ rotation: args.rotation, password: args.password }),
+    suffix: '-rotated',
+  },
+  {
+    name: 'add_page_numbers',
+    title: 'Add Page Numbers to PDF',
+    description: 'Prints the page number at the bottom of every page of a PDF.',
+    api: 'page-numbers-pdf',
+    properties: {
+      position: {
+        type: 'string',
+        enum: ['bottom-center', 'bottom-left', 'bottom-right'],
+        description: 'Where the number goes. Default: bottom-center.',
+      },
+      format: {
+        type: 'string',
+        enum: ['full', 'simple'],
+        description: 'full prints the page and the total, as "3 / 12"; simple prints "3". Default: full.',
+      },
+      password: PDF_PASSWORD,
+    },
+    fields: (args) => ({ position: args.position, format: args.format, password: args.password }),
+    suffix: '-numbered',
+  },
+  {
+    name: 'add_watermark',
+    title: 'Add Watermark to PDF',
+    description: 'Stamps a text diagonally across every page of a PDF.',
+    api: 'watermark-pdf',
+    properties: {
+      text: {
+        type: 'string',
+        description: 'Text of the watermark, such as CONFIDENTIAL: 50 characters at most, Latin letters, digits and punctuation.',
+      },
+      password: PDF_PASSWORD,
+    },
+    required: ['text'],
+    fields: (args) => ({ text: args.text, password: args.password }),
+    suffix: '-watermarked',
+  },
+  {
+    name: 'compress_pdf',
+    title: 'Compress PDF',
+    description: 'Reduces the size of a PDF by lowering the resolution of its images.',
+    api: 'compress-pdf',
+    properties: {
+      quality: {
+        type: 'string',
+        enum: ['low', 'medium', 'high'],
+        description: 'Resolution kept for the images: low is 72 DPI and gives the smallest file, medium 150 DPI, high 300 DPI. Default: medium.',
+      },
+      password: PDF_PASSWORD,
+    },
+    fields: (args) => ({ quality: args.quality, password: args.password }),
+    suffix: '-compressed',
+  },
+  {
+    name: 'protect_pdf',
+    title: 'Protect PDF With Password',
+    description: 'Encrypts a PDF (AES-256) so that it asks for a password to open, and optionally forbids printing or copying.',
+    api: 'protect-pdf',
+    properties: {
+      password: { type: 'string', description: 'Password needed to open the PDF, 6 to 64 characters.' },
+      prevent_print: { type: 'boolean', description: 'Forbid printing. Default: false.' },
+      prevent_copy: { type: 'boolean', description: 'Forbid copying text. Default: false.' },
+    },
+    required: ['password'],
+    // The API reads any value of these two fields as a yes: they are sent only when true.
+    fields: (args) => ({
+      password: args.password,
+      prevent_print: args.prevent_print === true ? 'on' : undefined,
+      prevent_copy: args.prevent_copy === true ? 'on' : undefined,
+    }),
+    suffix: '-protected',
+  },
+  {
+    name: 'unlock_pdf',
+    title: 'Unlock PDF',
+    description:
+      'Removes the password and the restrictions of a PDF whose password is known. It does not find a forgotten password.',
+    api: 'unlock-pdf',
+    properties: {
+      password: {
+        type: 'string',
+        description:
+          'Current password of the PDF. Leave it out for a PDF that opens without a password but restricts printing or copying.',
+      },
+    },
+    fields: (args) => ({ password: args.password }),
+    suffix: '-unlocked',
+    messages: { needs_password: 'This PDF needs its current password to be unlocked: pass it as "password".' },
+  },
+];
+
+function definition(spec) {
+  const input = spec.multiple
+    ? {
+        input_paths: {
+          type: 'array',
+          items: { type: 'string' },
+          minItems: 2,
+          maxItems: 20,
+          description: 'Paths of the PDFs on this computer, in the order they must appear in the result.',
+        },
+      }
+    : { input_path: INPUT_PATH };
+  return {
+    name: spec.name,
+    title: spec.title,
+    description: `${spec.description} ${SENT}`,
+    inputSchema: {
+      type: 'object',
+      properties: { ...input, ...spec.properties, output_path: OUTPUT_PATH },
+      required: [spec.multiple ? 'input_paths' : 'input_path', ...(spec.required ?? [])],
+      additionalProperties: false,
+    },
+    // Each call writes a new file and never replaces one; the input leaves this computer.
+    annotations: { title: spec.title, readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  };
+}
+
+const GET_QUOTA = {
+  name: 'get_quota',
+  title: 'Get Quota',
+  description:
+    'Returns the plan of the conv2pdf API key and how many conversions it has used and may still use. Reading the quota is free.',
+  inputSchema: { type: 'object', additionalProperties: false },
+  annotations: { title: 'Get Quota', readOnlyHint: true, openWorldHint: false },
+};
+
+const toolResult = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data) }], structuredContent: data });
+// A tool error is a result, not a protocol error: it is the form the model reads, so the
+// only one it can act on.
+const toolError = (text) => ({ content: [{ type: 'text', text }], isError: true });
+
+async function inputFiles(spec, args) {
+  if (!spec.multiple) return [await inputFile(args.input_path, 'input_path')];
+  if (!Array.isArray(args.input_paths) || args.input_paths.length < 2) {
+    throw new InputError('"input_paths" must list at least 2 PDFs.');
+  }
+  const files = [];
+  for (const given of args.input_paths) files.push(await inputFile(given, 'input_paths'));
+  return files;
+}
+
+async function convertFile(spec, args, api, signal) {
+  for (const name of spec.required ?? []) {
+    if (args[name] === undefined || args[name] === '') throw new InputError(`"${name}" is required.`);
+  }
+  const inputs = await inputFiles(spec, args);
+  const tool = typeof spec.api === 'function' ? spec.api(inputs[0]) : spec.api;
+  const fields = Object.fromEntries(
+    Object.entries(spec.fields ? spec.fields(args) : {}).filter(([, value]) => value !== undefined && value !== ''),
+  );
+  const output = await reserveOutput({
+    requested: args.output_path,
+    input: inputs[0],
+    suffix: spec.suffix ?? '',
+    extension: spec.extension ?? '.pdf',
+  });
+  let job;
+  try {
+    const converted = await api.convert(tool, inputs, fields, { signal });
+    job = converted.job;
+    await pipeline(Readable.fromWeb(converted.download.body), output.handle.createWriteStream(), { signal });
+  } catch (error) {
+    await discardOutput(output);
+    throw error;
+  }
+  await api.deleteJob(job.job_id);
+  const { size } = await fs.stat(output.file);
+  return { output_path: output.file, size_bytes: size, quota: job.quota };
+}
+
+/**
+ *   api: the conv2pdf client (api.js)
+ *   hasKey: whether an API key is configured
+ * Returns the tool definitions and the function that runs a call.
+ */
+export function createTools({ api, hasKey }) {
+  const specs = new Map(FILE_TOOLS.map((spec) => [spec.name, spec]));
+  const tools = [...FILE_TOOLS.map(definition), GET_QUOTA];
+
+  async function callTool(name, args, { signal }) {
+    if (!hasKey) return toolError(NO_KEY);
+    const spec = specs.get(name);
+    try {
+      if (!spec) return toolResult(await api.quota({ signal }));
+      return toolResult(await convertFile(spec, args, api, signal));
+    } catch (error) {
+      if (error instanceof InputError) return toolError(error.message);
+      if (error instanceof ApiError) return toolError(apiErrorText(error, spec?.messages));
+      if (error.name === 'TimeoutError') return toolError('conv2pdf did not answer in time. Try again in a moment.');
+      if (error instanceof TypeError && error.message === 'fetch failed') {
+        return toolError('Could not reach conv2pdf. Check the network connection and try again.');
+      }
+      if (typeof error.code === 'string' && error.syscall) {
+        return toolError(`Could not write the result: ${error.message}`);
+      }
+      // A call cancelled by the client ends here too: the protocol layer sends nothing back.
+      throw error;
+    }
+  }
+
+  return { tools, callTool };
+}