@tlelabs/md-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lê Phước Lộc (TLE Labs)
+
+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,78 @@
-# Temporary Holding Version
+# @tlelabs/md-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.
+MCP server for [md. by TLE Labs](https://md.tlelabs.com): lets an AI agent (Claude Code, Cursor, Codex, Claude Desktop…) convert local PDF, DOCX, PPTX, XLSX and HTML files to Markdown.
+
+The server runs on your machine over stdio, reads the file from disk and sends it to the md. API with your API key. Nothing is stored by the API.
+
+## Set up
+
+1. Sign in at [md.tlelabs.com](https://md.tlelabs.com/login) and create an API key under [API keys](https://md.tlelabs.com/keys). New accounts get free credits; buy more under [Billing](https://md.tlelabs.com/billing).
+2. Add the server to your client with the key in `MD_API_KEY`. Node.js 20 or newer is required.
+
+**Claude Code**
+
+```sh
+claude mcp add md -e MD_API_KEY=mdw_live_... -- npx -y @tlelabs/md-mcp
+```
+
+**Cursor, Claude Desktop and other clients using `mcpServers` JSON**
+
+```json
+{
+  "mcpServers": {
+    "md": {
+      "command": "npx",
+      "args": ["-y", "@tlelabs/md-mcp"],
+      "env": { "MD_API_KEY": "mdw_live_..." }
+    }
+  }
+}
+```
+
+**Codex** (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.md]
+command = "npx"
+args = ["-y", "@tlelabs/md-mcp"]
+env = { MD_API_KEY = "mdw_live_..." }
+tool_timeout_sec = 600
+```
+
+Long PDFs that need OCR can take a few minutes. If your client stops waiting before the conversion ends, raise its tool timeout (Codex `tool_timeout_sec`, Claude Code `MCP_TOOL_TIMEOUT` in milliseconds).
+
+## Tool: `convert_file`
+
+| Argument | Type | Description |
+|---|---|---|
+| `path` | string | File to convert. Relative paths resolve against the server's working directory; absolute paths are safest |
+| `output_path` | string, optional | Write the Markdown to this file instead of returning it (use it for long documents). Parent directories are created |
+| `overwrite` | boolean, optional | Replace `output_path` if it exists (default `false`: an existing file is never replaced) |
+| `ocr` | `auto` \| `force` \| `off`, optional | OCR mode (default `auto`; `force` only changes PDFs) |
+| `ocr_model` | string, optional | `auto` (default) or a model id such as `openparser/mistral-ocr-4` |
+| `preserve_images` | boolean, optional | Keep image placeholders with their OCR text (default `true`) |
+
+The result holds the Markdown (or the path it was saved to) and a summary: format, pages, OCR pages, credits charged and remaining, and any warnings.
+
+## Billing
+
+Every call is a new conversion and is charged: 1 credit per page, more for pages read with OCR (see [pricing](https://md.tlelabs.com/docs/formats-and-pricing/)). Calling again with the same file is charged again. The server never retries on its own.
+
+Checks that can fail locally (missing file, file over 50 MB, `output_path` already exists, parent directory cannot be created) run before upload and cost nothing.
+
+If the connection drops, or the API answers with something unexpected, the result says the conversion may have been charged: check [Usage](https://md.tlelabs.com/usage) before converting again. Cancelling a call stops waiting for it and nothing is written, but a conversion the API already finished is still charged.
+
+If the Markdown cannot be saved to `output_path` after a paid conversion (for example the file appeared meanwhile, or the disk is full), it is returned in the result instead and any existing file is left unchanged.
+
+## Environment
+
+| Variable | Required | Default |
+|---|---|---|
+| `MD_API_KEY` | yes | — |
+| `MD_API_BASE` | no | `https://api.md.tlelabs.com` |
+
+The key is sent only to `MD_API_BASE` and never logged.
+
+## License
+
+MIT

package/dist/convert.js

@@ -0,0 +1,183 @@
+import { randomBytes } from "node:crypto";
+import { openAsBlob } from "node:fs";
+import { link, lstat, mkdir, open, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { apiErrorText, AMBIGUOUS_CHARGE } from "./errors.js";
+/** Same limit as the Worker (`MAX_FILE_SIZE` in src/routes/convert.ts): larger files are refused before upload. */
+export const MAX_FILE_SIZE = 50 * 1024 * 1024;
+export const KEYS_URL = "https://md.tlelabs.com/keys";
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
+const defaultTempName = () => `.md-mcp-${randomBytes(4).toString("hex")}.tmp`;
+export async function convertFile(input, deps) {
+    if (!deps.apiKey) {
+        return fail(`MD_API_KEY is not set. Create an API key at ${KEYS_URL} and add it to this MCP server's env as MD_API_KEY.`);
+    }
+    const source = resolve(deps.cwd, input.path);
+    let size;
+    try {
+        const info = await stat(source);
+        if (!info.isFile())
+            return fail(`${source} is not a regular file.`);
+        size = info.size;
+    }
+    catch (e) {
+        return fail(`Cannot read ${source}: ${e.code ?? String(e)}.`);
+    }
+    if (size > MAX_FILE_SIZE) {
+        return fail(`file_too_large: ${source} is ${size} bytes; the limit is ${MAX_FILE_SIZE} bytes (50 MB). Nothing was uploaded.`);
+    }
+    // Everything that can fail at the destination is checked before upload, so it costs no credits.
+    let destination;
+    if (input.output_path !== undefined) {
+        destination = resolve(deps.cwd, input.output_path);
+        try {
+            await mkdir(dirname(destination), { recursive: true });
+        }
+        catch (e) {
+            return fail(`Cannot create the directory of ${destination}: ${e.code ?? String(e)}. Nothing was uploaded.`);
+        }
+        let existing;
+        try {
+            existing = await lstat(destination);
+        }
+        catch (e) {
+            // Only "does not exist" means the destination is free; anything else (EACCES, ENAMETOOLONG…) fails before upload
+            const code = e.code;
+            if (code !== "ENOENT")
+                return fail(`Cannot use ${destination}: ${code ?? String(e)}. Nothing was uploaded.`);
+        }
+        if (existing?.isDirectory())
+            return fail(`${destination} is a directory. Nothing was uploaded.`);
+        if (existing && !input.overwrite) {
+            return fail(`${destination} already exists; pass overwrite: true to replace it. Nothing was uploaded.`);
+        }
+    }
+    const form = new FormData();
+    form.append("file", await openAsBlob(source), basename(source));
+    if (input.ocr !== undefined)
+        form.append("ocr", input.ocr);
+    if (input.ocr_model !== undefined)
+        form.append("ocr_model", input.ocr_model);
+    if (input.preserve_images !== undefined)
+        form.append("preserve_images", String(input.preserve_images));
+    // No automatic retry: the API does not deduplicate, so a second request is a second charge.
+    let status;
+    let retryAfter;
+    let body;
+    try {
+        const response = await deps.fetch(`${deps.apiBase}/v1/convert`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${deps.apiKey}`, Accept: "application/json", "User-Agent": deps.userAgent },
+            body: form,
+            signal: deps.signal,
+        });
+        status = response.status;
+        retryAfter = response.headers.get("retry-after");
+        body = await response.text();
+    }
+    catch (e) {
+        if (deps.signal?.aborted)
+            return fail(`Cancelled. ${AMBIGUOUS_CHARGE}`);
+        return fail(`Network error talking to ${deps.apiBase}: ${e.message}. ${AMBIGUOUS_CHARGE}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(body);
+    }
+    catch {
+        return fail(`HTTP ${status} with a non-JSON response from ${deps.apiBase}. ${AMBIGUOUS_CHARGE}`);
+    }
+    if (status < 200 || status >= 300) {
+        const error = isObject(json) ? json.error : undefined;
+        if (!isObject(error) || typeof error.code !== "string" || typeof error.message !== "string")
+            return fail(`HTTP ${status} with an unexpected response. ${AMBIGUOUS_CHARGE}`);
+        return fail(apiErrorText(status, error, retryAfter));
+    }
+    if (!isObject(json) || typeof json.markdown !== "string" || !isObject(json.usage)) {
+        return fail(`HTTP ${status} with an unexpected response. ${AMBIGUOUS_CHARGE}`);
+    }
+    const result = {
+        ...json,
+        warnings: Array.isArray(json.warnings) ? json.warnings.filter((w) => typeof w === "string") : [],
+    };
+    const summary = summarize(source, result);
+    const structured = {
+        format: result.format,
+        usage: result.usage,
+        metadata: result.metadata,
+        warnings: result.warnings,
+    };
+    if (destination === undefined) {
+        return { content: [{ type: "text", text: result.markdown }, { type: "text", text: summary }], structuredContent: structured };
+    }
+    if (deps.signal?.aborted)
+        return fail(`Cancelled after conversion; ${destination} was not written. ${result.usage.credits_charged} credits were charged.`);
+    const saveError = await publish(result.markdown, destination, input.overwrite === true, deps);
+    if (saveError === undefined) {
+        return {
+            content: [{ type: "text", text: `${summary}\nSaved to ${destination}` }],
+            structuredContent: { ...structured, output_path: destination },
+        };
+    }
+    if (saveError === "cancelled")
+        return fail(`Cancelled after conversion; ${destination} was not written. ${result.usage.credits_charged} credits were charged.`);
+    // The conversion is paid for: hand the Markdown back rather than lose it.
+    return {
+        content: [
+            { type: "text", text: result.markdown },
+            { type: "text", text: `${summary}\nCould not save to ${destination} (${saveError}); the Markdown is returned above instead. Any existing file there is unchanged.` },
+        ],
+        structuredContent: { ...structured, save_error: saveError },
+    };
+}
+/**
+ * Writes to a scratch file in the destination's directory, then publishes it atomically:
+ * rename when overwriting, hard link otherwise (an existing destination fails with EEXIST and is kept).
+ * Returns undefined on success, "cancelled", or the error code; never leaves a partial destination.
+ */
+async function publish(markdown, destination, overwrite, deps) {
+    const scratch = join(dirname(destination), (deps.tempName ?? defaultTempName)());
+    let handle;
+    try {
+        handle = await open(scratch, "wx");
+    }
+    catch (e) {
+        return e.code ?? String(e);
+    }
+    let owned = true;
+    try {
+        try {
+            await handle.writeFile(markdown, "utf8");
+        }
+        finally {
+            await handle.close();
+        }
+        if (deps.signal?.aborted)
+            return "cancelled";
+        if (overwrite) {
+            await rename(scratch, destination);
+            owned = false;
+        }
+        else {
+            await (deps.link ?? link)(scratch, destination);
+        }
+        return undefined;
+    }
+    catch (e) {
+        return e.code ?? String(e);
+    }
+    finally {
+        if (owned)
+            await unlink(scratch).catch(() => { });
+    }
+}
+function summarize(source, result) {
+    const { pages, ocr_pages, credits_charged, credits_remaining } = result.usage;
+    const lines = [
+        `Converted ${basename(source)} (${result.format}): ${pages} pages, ${ocr_pages} OCR pages; charged ${credits_charged} credits, ${credits_remaining} remaining.`,
+    ];
+    for (const warning of result.warnings)
+        lines.push(`Warning: ${warning}`);
+    return lines.join("\n");
+}

package/dist/errors.js

@@ -0,0 +1,23 @@
+export const USAGE_URL = "https://md.tlelabs.com/usage";
+export const BILLING_URL = "https://md.tlelabs.com/billing";
+const KEYS_URL = "https://md.tlelabs.com/keys";
+export const AMBIGUOUS_CHARGE = `The conversion may have been charged; check ${USAGE_URL} before converting again (a new request is charged again).`;
+/** Text for an API error envelope: the server's code and message, plus what the agent can do about it. */
+export function apiErrorText(status, error, retryAfter) {
+    // The Worker puts the request id in details (src/errors.ts jsonError); a top-level one is accepted too
+    const requestId = error.details?.request_id ?? error.request_id;
+    const head = `${error.code}: ${error.message}${typeof requestId === "string" ? ` (request_id ${requestId})` : ""}`;
+    switch (error.code) {
+        case "invalid_api_key":
+            return `${head}\nCheck MD_API_KEY in this MCP server's env; create or rotate a key at ${KEYS_URL}.`;
+        case "insufficient_credits":
+            return `${head}\nTop up credits at ${BILLING_URL}. Nothing was charged.`;
+        case "rate_limited":
+        case "too_many_concurrent":
+            return `${head}\n${retryAfter ? `Retry after ${retryAfter} seconds.` : "Retry later."} Nothing was charged.`;
+    }
+    // A 503 carrying details.request_id means the charge could not be confirmed (docs/api.md, Errors).
+    if (status === 503 && error.details?.request_id !== undefined)
+        return `${head}\n${AMBIGUOUS_CHARGE}`;
+    return head;
+}

package/dist/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { convertFile } from "./convert.js";
+const { version } = createRequire(import.meta.url)("../package.json");
+const apiBase = (process.env.MD_API_BASE || "https://api.md.tlelabs.com").replace(/\/+$/, "");
+const server = new McpServer({ name: "md", version });
+/** Tool calls still running, awaited on shutdown. */
+const active = new Set();
+server.registerTool("convert_file", {
+    title: "Convert a file to Markdown",
+    description: "Convert a local PDF, DOCX, PPTX, XLSX or HTML file (up to 50 MB) to Markdown with md. by TLE Labs. " +
+        "Each call is billed in credits (1 per page; pages that need OCR cost more) and is charged again if repeated. " +
+        "Prefer absolute paths. For long documents pass output_path so the Markdown is written to a file instead of returned.",
+    inputSchema: {
+        path: z.string().min(1).describe("File to convert; relative paths resolve against the server's working directory"),
+        output_path: z.string().min(1).optional().describe("Write the Markdown to this file instead of returning it"),
+        overwrite: z.boolean().optional().describe("Replace output_path if it already exists (default false)"),
+        ocr: z.enum(["auto", "force", "off"]).optional().describe("OCR mode: auto (default), force (PDF only: OCR every page), off"),
+        ocr_model: z.string().min(1).optional().describe("OCR model: auto (default) or a provider/model id"),
+        preserve_images: z.boolean().optional().describe("Keep image placeholders with OCR text (default true)"),
+    },
+}, (args, extra) => {
+    const call = convertFile(args, {
+        apiKey: process.env.MD_API_KEY,
+        apiBase,
+        fetch,
+        signal: extra.signal,
+        cwd: process.cwd(),
+        userAgent: `md-mcp/${version}`,
+    });
+    active.add(call);
+    void call.finally(() => active.delete(call)).catch(() => { });
+    return call;
+});
+let closing = false;
+// The client went away (stdin closed) or asked us to stop: closing the server aborts every
+// in-flight call's signal, so their requests stop and nothing is written; wait for that cleanup, then exit.
+async function shutdown() {
+    if (closing)
+        return;
+    closing = true;
+    await server.close();
+    await Promise.allSettled([...active]);
+    process.exit(0);
+}
+process.stdin.on("end", shutdown);
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@tlelabs/md-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for md. by TLE Labs: convert local PDF, DOCX, PPTX, XLSX and HTML files to Markdown",
+  "type": "module",
+  "bin": {
+    "md-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "homepage": "https://md.tlelabs.com/docs/mcp/",
+  "keywords": [
+    "mcp",
+    "markdown",
+    "pdf",
+    "docx",
+    "pptx",
+    "xlsx",
+    "converter"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc -p tsconfig.build.json && vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.12"
+  }
+}