uvpdftool-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UV ResearchLabs
+
+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,3 +1,55 @@
-# Temporary Holding Version
+# uvpdftool-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Model Context Protocol](https://modelcontextprotocol.io) server for the
+[UV pdfTool API](https://uvpdftool.com/developers): an AI assistant such as Claude Desktop can
+compress, convert, OCR and check the PDFs in the folders you allow, and tell you where it saved
+the results. Node.js 18.3 or later; it speaks MCP over standard input and output.
+
+## Set it up
+
+Make a key on the [API keys page](https://uvpdftool.com/developers/keys) (a test key is free and
+marks its results), then add the server to the assistant's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "uvpdftool": {
+      "command": "npx",
+      "args": ["-y", "uvpdftool-mcp", "--root", "/Users/you/Documents/PDFs"],
+      "env": { "UVPDFTOOL_API_KEY": "uvp_test_..." }
+    }
+  }
+}
+```
+
+`--root` names a folder the server may read files from and save results in; give it more than
+once for more folders, or set `UVPDFTOOL_MCP_ROOTS` (separated as `PATH` is). Without either, the
+folder the server is started in is the only one, unless that is the whole disk or your home
+folder, where some assistants start their servers: then it stops and asks for `--root`. Anything
+else on its command line stops it too, so a mistyped option never widens what it may use.
+
+A path is judged on its text before the disk is touched, so a path to another machine
+(`\\host\share`) is refused without being opened; then on its real path, so neither `..` nor a
+link leads out. A result is created only where nothing is, a link included, so it never replaces
+or writes through anything.
+
+## What the assistant can do
+
+| Tool              | Does                                                                                                             |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `list_pdf_tools`  | The API's tools, the files each takes and the options each accepts, as JSON Schema.                              |
+| `run_pdf_tool`    | Uploads files from an allowed folder, runs one tool with its options, and saves the results; answers with paths. |
+| `pdf_api_account` | The key in use and the API tasks left.                                                                           |
+
+## What it will not do
+
+- Read a file, or save a result, outside the folders allowed; a path that leads out of them, by
+  `..` or by a link, is refused.
+- Write over a file: a result whose name is taken gets a number added, as `report-compressed (2).pdf`.
+- Keep anything: files go to the API for the one job, and come back.
+
+Each run is one API task, as any other call is. The assistant decides which files to send, so
+allow a folder of the documents you mean it to work on, not your whole home folder, and use a
+test key until you trust what it does.
+
+The tools, their options and the errors are documented at <https://uvpdftool.com/developers>.

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline';
+import { UvPdfTool } from 'uvpdftool';
+import { createServer, rootsFrom, SERVER_VERSION } from './server.js';
+/**
+ * The server as a program for an MCP client: messages on standard input, answers on standard
+ * output, anything else on standard error. The key comes from UVPDFTOOL_API_KEY; the folders it
+ * may use from --root (repeatable), or UVPDFTOOL_MCP_ROOTS, or the folder it was started in
+ * (never the whole disk or the home folder).
+ */
+const chosen = rootsFrom(process.argv.slice(2), process.env, process.cwd(), homedir());
+if ('error' in chosen) {
+    process.stderr.write(`uvpdftool-mcp: ${chosen.error}\n`);
+    process.exit(2);
+}
+const { roots } = chosen;
+const apiKey = process.env.UVPDFTOOL_API_KEY ?? '';
+if (apiKey === '') {
+    process.stderr.write('uvpdftool-mcp: set UVPDFTOOL_API_KEY to an API key (https://uvpdftool.com/developers/keys).\n');
+    process.exit(2);
+}
+const server = await createServer({
+    client: new UvPdfTool({ apiKey, userAgent: `uvpdftool-mcp/${SERVER_VERSION}` }),
+    roots,
+});
+process.stderr.write(`uvpdftool-mcp ${SERVER_VERSION}: serving ${roots.join(', ')}\n`);
+const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+lines.on('line', (line) => {
+    void server.handleLine(line).then((reply) => {
+        if (reply !== null)
+            process.stdout.write(`${JSON.stringify(reply)}\n`);
+    });
+});

package/dist/server.d.ts

@@ -0,0 +1,47 @@
+import { type UvPdfTool } from 'uvpdftool';
+/**
+ * A Model Context Protocol server for the UV pdfTool API, spoken as JSON-RPC 2.0, one message
+ * a line: an assistant lists the tools, runs one on files in the folders it was allowed, and
+ * gets back where the results were saved. Files outside those folders are never read, results
+ * never land outside them, and nothing is written over an existing file.
+ */
+export declare const SERVER_VERSION = "0.1.0";
+/** Newest first: the one the client asks for when it is one of these, the newest otherwise. */
+export declare const PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+type Id = string | number | null;
+export type Reply = {
+    jsonrpc: '2.0';
+    id: Id;
+    result: unknown;
+} | {
+    jsonrpc: '2.0';
+    id: Id;
+    error: {
+        code: number;
+        message: string;
+    };
+};
+export interface ServerOptions {
+    client: Pick<UvPdfTool, 'tools' | 'account' | 'run' | 'download'>;
+    /** The folders the server may read files from and save results in. */
+    roots: readonly string[];
+}
+/**
+ * The folders from the command line (--root, repeatable), else UVPDFTOOL_MCP_ROOTS, else the
+ * folder the server was started in, unless that is the whole disk or the home folder, where an
+ * assistant's app may start servers without saying so. Anything else on the line is an error,
+ * so that a mistyped option never widens what the server may use.
+ */
+export declare function rootsFrom(args: readonly string[], env: Readonly<Record<string, string | undefined>>, cwd: string, home: string): {
+    roots: string[];
+} | {
+    error: string;
+};
+export interface McpServer {
+    /** One line from the client, answered, or null where nothing is to be answered. */
+    handleLine: (line: string) => Promise<Reply | Reply[] | null>;
+    handle: (message: unknown) => Promise<Reply | null>;
+}
+/** The server, over these folders, which must exist; they are taken as their real paths. */
+export declare function createServer(options: ServerOptions): Promise<McpServer>;
+export {};

package/dist/server.js

@@ -0,0 +1,308 @@
+import { createReadStream } from 'node:fs';
+import { mkdir, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { ApiError, contentTypeOf, JobFailedError, safeName, saveResult, } from 'uvpdftool';
+/**
+ * A Model Context Protocol server for the UV pdfTool API, spoken as JSON-RPC 2.0, one message
+ * a line: an assistant lists the tools, runs one on files in the folders it was allowed, and
+ * gets back where the results were saved. Files outside those folders are never read, results
+ * never land outside them, and nothing is written over an existing file.
+ */
+export const SERVER_VERSION = '0.1.0';
+/** Newest first: the one the client asks for when it is one of these, the newest otherwise. */
+export const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const ERRORS = {
+    parse: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internal: -32603,
+};
+/** What a tool call says went wrong, back to the assistant as the call's result. */
+class ToolError extends Error {
+}
+const TOOLS = [
+    {
+        name: 'list_pdf_tools',
+        title: 'List the UV pdfTool tools',
+        description: 'The tools the UV pdfTool API offers (compress, office-to-pdf, pdf-to-office, ocr, pdf-to-pdfa, pdfa-check, web-to-pdf and more), the files each takes, and the options each accepts as JSON Schema. Call it before run_pdf_tool to know a tool’s options.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    {
+        name: 'run_pdf_tool',
+        title: 'Run a UV pdfTool tool on local files',
+        description: 'Uploads local files to the UV pdfTool API, runs one tool on them with the options given, and saves the results in a folder; answers with the paths saved. Each run is one API task. The files and the folder must be inside the folders this server was allowed; a result never replaces an existing file, a number is added to its name instead.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tool: {
+                    type: 'string',
+                    description: 'The tool, as list_pdf_tools names it: for example "compress".',
+                },
+                files: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Paths of the files to send: absolute, or relative to the first allowed folder. None for a tool that takes no files, such as web-to-pdf.',
+                },
+                options: {
+                    type: 'object',
+                    description: 'The tool’s options, as list_pdf_tools describes them.',
+                },
+                outputDir: {
+                    type: 'string',
+                    description: 'Where to save the results; the folder of the first file when not given, or the first allowed folder.',
+                },
+            },
+            required: ['tool'],
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: 'pdf_api_account',
+        title: 'The UV pdfTool API account',
+        description: 'The API key in use (its name, and live or test) and the API tasks left.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+];
+const within = (root, target) => {
+    const relative = path.relative(root, target);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+};
+const text = (value) => ({ content: [{ type: 'text', text: value }] });
+/**
+ * The folders from the command line (--root, repeatable), else UVPDFTOOL_MCP_ROOTS, else the
+ * folder the server was started in, unless that is the whole disk or the home folder, where an
+ * assistant's app may start servers without saying so. Anything else on the line is an error,
+ * so that a mistyped option never widens what the server may use.
+ */
+export function rootsFrom(args, env, cwd, home) {
+    const roots = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        if (arg === '--root') {
+            const value = args[index + 1];
+            if (!value)
+                return { error: '--root needs a folder.' };
+            roots.push(value);
+            index += 1;
+        }
+        else if (arg.startsWith('--root=') && arg.length > '--root='.length) {
+            roots.push(arg.slice('--root='.length));
+        }
+        else {
+            return { error: `unknown argument ${arg}; give the folders with --root <folder>.` };
+        }
+    }
+    if (roots.length === 0 && env.UVPDFTOOL_MCP_ROOTS) {
+        roots.push(...env.UVPDFTOOL_MCP_ROOTS.split(path.delimiter).filter(Boolean));
+    }
+    if (roots.length > 0)
+        return { roots };
+    const here = path.resolve(cwd);
+    if (here === path.parse(here).root || path.relative(path.resolve(home), here) === '') {
+        return {
+            error: `started in ${here}, too wide to serve; give the folders with --root <folder>.`,
+        };
+    }
+    return { roots: [here] };
+}
+/** The server, over these folders, which must exist; they are taken as their real paths. */
+export async function createServer(options) {
+    if (options.roots.length === 0)
+        throw new Error('At least one folder is needed.');
+    const roots = [];
+    for (const root of options.roots)
+        roots.push(await realpath(path.resolve(root)));
+    const [first] = roots;
+    const { client } = options;
+    // The folders as given too: a path written through a link to a folder is inside although its
+    // text is not the folder's real path.
+    const named = options.roots.map((root) => path.resolve(root));
+    const inside = (target) => [...roots, ...named].some((root) => within(root, target));
+    // Judged on the text before anything on disk is touched: opening a path to another machine
+    // (\\host\share) would send the user's Windows sign-in to it, and an answer of "no such
+    // file" would tell what exists outside the folders.
+    const outside = (given) => new ToolError(`${given} is outside the folders this server may use.`);
+    /** A file the assistant named, as its real path, if it is inside a folder allowed. */
+    const allowedFile = async (given) => {
+        const wanted = path.resolve(first, given);
+        if (!inside(wanted))
+            throw outside(given);
+        const real = await realpath(wanted).catch(() => null);
+        if (real === null)
+            throw new ToolError(`${given}: no such file.`);
+        if (!roots.some((root) => within(root, real)))
+            throw outside(given);
+        if (!(await stat(real)).isFile())
+            throw new ToolError(`${given} is not a file.`);
+        return real;
+    };
+    /** A folder to save in, made if need be, if it is inside a folder allowed. */
+    const allowedFolder = async (given) => {
+        const wanted = path.resolve(first, given);
+        if (!inside(wanted))
+            throw outside(given);
+        // The nearest part that exists, as its real path, decides where the rest would land.
+        let existing = wanted;
+        let rest = '';
+        for (;;) {
+            const real = await realpath(existing).catch(() => null);
+            if (real !== null) {
+                const target = path.join(real, rest);
+                if (!roots.some((root) => within(root, target)))
+                    throw outside(given);
+                await mkdir(target, { recursive: true });
+                return target;
+            }
+            const parent = path.dirname(existing);
+            if (parent === existing)
+                throw new ToolError(`${given} cannot be made.`);
+            rest = path.join(path.basename(existing), rest);
+            existing = parent;
+        }
+    };
+    const runTool = async (args) => {
+        const { tool, files, options: toolOptions, outputDir } = args;
+        if (typeof tool !== 'string' || !/^[a-z0-9-]{1,40}$/u.test(tool)) {
+            throw new ToolError('Name the tool, as list_pdf_tools does.');
+        }
+        const given = files ?? [];
+        if (!Array.isArray(given) || !given.every((f) => typeof f === 'string')) {
+            throw new ToolError('Give the files as a list of paths.');
+        }
+        if (toolOptions !== undefined &&
+            (typeof toolOptions !== 'object' || toolOptions === null || Array.isArray(toolOptions))) {
+            throw new ToolError('The options are an object, as list_pdf_tools describes them.');
+        }
+        if (outputDir !== undefined && typeof outputDir !== 'string') {
+            throw new ToolError('outputDir is a folder path.');
+        }
+        const paths = [];
+        for (const file of given)
+            paths.push(await allowedFile(file));
+        const [firstFile] = paths;
+        const folder = await allowedFolder(outputDir ?? (firstFile === undefined ? first : path.dirname(firstFile)));
+        const inputs = [];
+        for (const file of paths) {
+            inputs.push({
+                name: path.basename(file),
+                contentType: contentTypeOf(file),
+                size: (await stat(file)).size,
+                data: Readable.toWeb(createReadStream(file)),
+            });
+        }
+        const job = await client.run({
+            tool,
+            files: inputs,
+            ...(toolOptions ? { options: toolOptions } : {}),
+        });
+        const saved = [];
+        for (const [index, output] of job.outputs.entries()) {
+            const data = await client.download(output);
+            saved.push(await saveResult(folder, safeName(output.name, index), data, false));
+        }
+        return {
+            ...text(`${tool} finished${job.mode === 'test' ? ' (a test job: its results are marked)' : ''}. Saved:\n${saved.join('\n')}`),
+            structuredContent: { job: { id: job.id, tool: job.tool, mode: job.mode }, saved },
+        };
+    };
+    const callTool = async (name, args) => {
+        const given = (typeof args === 'object' && args !== null ? args : {});
+        try {
+            if (name === 'list_pdf_tools') {
+                const tools = await client.tools();
+                return { ...text(JSON.stringify(tools, null, 2)), structuredContent: { tools } };
+            }
+            if (name === 'pdf_api_account') {
+                const account = await client.account();
+                return { ...text(JSON.stringify(account, null, 2)), structuredContent: account };
+            }
+            return await runTool(given);
+        }
+        catch (error) {
+            // Failures of the call itself go back to the assistant as the result, so it can act on them.
+            const message = error instanceof ToolError || error instanceof ApiError || error instanceof JobFailedError
+                ? error.message
+                : `The call failed: ${error instanceof Error ? error.message : String(error)}`;
+            return { ...text(message), isError: true };
+        }
+    };
+    const handle = async (message) => {
+        if (typeof message !== 'object' || message === null || Array.isArray(message)) {
+            return {
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: ERRORS.invalidRequest, message: 'Not a request.' },
+            };
+        }
+        const { id, method, params } = message;
+        // Notifications are not answered; nor are replies to requests this server never makes.
+        if (typeof method !== 'string')
+            return null;
+        if (id === undefined)
+            return null;
+        const ok = (result) => ({ jsonrpc: '2.0', id, result });
+        const fail = (code, text) => ({
+            jsonrpc: '2.0',
+            id,
+            error: { code, message: text },
+        });
+        const given = (typeof params === 'object' && params !== null ? params : {});
+        try {
+            switch (method) {
+                case 'initialize': {
+                    const asked = given.protocolVersion;
+                    const version = PROTOCOL_VERSIONS.find((each) => each === asked) ?? PROTOCOL_VERSIONS[0];
+                    return ok({
+                        protocolVersion: version,
+                        capabilities: { tools: { listChanged: false } },
+                        serverInfo: { name: 'uvpdftool-mcp', title: 'UV pdfTool', version: SERVER_VERSION },
+                        instructions: 'Use list_pdf_tools to see the tools and their options, then run_pdf_tool with paths of files in the allowed folders. Results are saved beside the first file unless outputDir says otherwise.',
+                    });
+                }
+                case 'ping':
+                    return ok({});
+                case 'tools/list':
+                    return ok({ tools: TOOLS });
+                case 'tools/call': {
+                    const name = given.name;
+                    if (!TOOLS.some((tool) => tool.name === name)) {
+                        return fail(ERRORS.invalidParams, `There is no tool ${String(name)}.`);
+                    }
+                    return ok(await callTool(name, given.arguments));
+                }
+                default:
+                    return fail(ERRORS.methodNotFound, `There is no method ${method}.`);
+            }
+        }
+        catch (error) {
+            return fail(ERRORS.internal, error instanceof Error ? error.message : String(error));
+        }
+    };
+    const handleLine = async (line) => {
+        if (line.trim() === '')
+            return null;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return { jsonrpc: '2.0', id: null, error: { code: ERRORS.parse, message: 'Not JSON.' } };
+        }
+        if (Array.isArray(parsed)) {
+            const replies = (await Promise.all(parsed.map(handle))).filter((reply) => reply !== null);
+            return replies.length > 0 ? replies : null;
+        }
+        return handle(parsed);
+    };
+    return { handle, handleLine };
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "uvpdftool-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A Model Context Protocol server for the UV pdfTool API: let an AI assistant compress, convert, OCR and check the PDFs in your folders.",
+  "license": "MIT",
+  "author": "UV ResearchLabs",
+  "homepage": "https://uvpdftool.com/developers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uvresearchlab/UV-pdfTool",
+    "directory": "packages/mcp"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pdf",
+    "compress",
+    "ocr",
+    "convert",
+    "uvpdftool"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18.3"
+  },
+  "bin": {
+    "uvpdftool-mcp": "./dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/server.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "uvpdftool": "^0.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.13.6",
+    "eslint": "^10.11.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^4.1.12"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }