@noedgeai-org/doc2x-mcp 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# Doc2x MCP Server
+
+本项目提供一个基于 stdio 的 MCP Server，把 Doc2x v2 的 PDF/图片接口封装成语义化 tools。
+
+## 1) 运行环境
+
+- Node.js >= 18
+
+## 2) 配置
+
+通过环境变量配置：
+
+- `DOC2X_API_KEY`：必填（形如 `sk-xxx`）
+- `DOC2X_BASE_URL`：可选，默认 `https://v2.doc2x.noedgeai.com`
+- `DOC2X_HTTP_TIMEOUT_MS`：可选，默认 `60000`
+- `DOC2X_POLL_INTERVAL_MS`：可选，默认 `2000`
+- `DOC2X_MAX_WAIT_MS`：可选，默认 `600000`
+- `DOC2X_DOWNLOAD_URL_ALLOWLIST`：可选，默认 `".amazonaws.com.cn,.aliyuncs.com,.noedgeai.com"`；设为 `*` 可允许任意 host（不推荐）
+
+## 3) 启动
+
+### 方式 A：通过 npx
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@noedgeai/doc2x-mcp"],
+  "env": {
+    "DOC2X_API_KEY": "sk-xxx",
+    "DOC2X_BASE_URL": "https://v2.doc2x.noedgeai.com"
+  }
+}
+```
+
+### 方式 B：本地源码运行
+
+```bash
+cd doc2x-mcp
+npm install
+npm run build
+DOC2X_API_KEY=sk-xxx npm start
+```
+```json
+{
+  "command": "node",
+  "args": ["<ABS_PATH>/doc2x-mcp/dist/index.js"],
+  "env": {
+    "DOC2X_API_KEY": "sk-xxx",
+    "DOC2X_BASE_URL": "https://v2.doc2x.noedgeai.com"
+  }
+}
+```
+## 4) Tools
+
+- `doc2x_parse_pdf_submit`
+- `doc2x_parse_pdf_status`
+- `doc2x_parse_pdf_wait_text`
+- `doc2x_convert_export_submit`
+- `doc2x_convert_export_result`
+- `doc2x_convert_export_wait`
+- `doc2x_download_url_to_file`
+- `doc2x_parse_image_layout_sync`
+- `doc2x_parse_image_layout_submit`
+- `doc2x_parse_image_layout_status`
+- `doc2x_parse_image_layout_wait_text`
+- `doc2x_materialize_convert_zip`
+- `doc2x_debug_config`

package/dist/config.js

@@ -0,0 +1,94 @@
+const INLINE_DOC2X_API_KEY = "";
+function parseDoc2xApiKey(raw) {
+    const v = String(raw).trim();
+    if (!v)
+        return "";
+    // Common misconfig: Alma/Codex passes literal "${DOC2X_API_KEY}" without expansion.
+    if (v.includes("${") && v.includes("}"))
+        return "";
+    const bearerPrefix = /^bearer\s+/i;
+    if (bearerPrefix.test(v))
+        return v.replace(bearerPrefix, "").trim();
+    return v;
+}
+function resolveApiKey() {
+    const inline = parseDoc2xApiKey(INLINE_DOC2X_API_KEY);
+    if (inline)
+        return { apiKey: inline, source: "inline" };
+    const env = parseDoc2xApiKey(process.env.DOC2X_API_KEY || "");
+    if (env)
+        return { apiKey: env, source: "env" };
+    return { apiKey: "", source: "missing" };
+}
+function getEnvInt(name, def) {
+    const raw = process.env[name];
+    if (raw == null || String(raw).trim() === "")
+        return def;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new Error(`Invalid env ${name}: ${raw}`);
+    return Math.floor(n);
+}
+function parsePositiveDurationMs(raw, defaultUnit) {
+    const v = String(raw).trim().toLowerCase();
+    if (!v)
+        throw new Error("empty duration");
+    const m = v.match(/^(\d+(?:\.\d+)?)(ms|s|m)?$/);
+    if (!m)
+        throw new Error(`invalid duration: ${raw}`);
+    const num = Number(m[1]);
+    if (!Number.isFinite(num) || num <= 0)
+        throw new Error(`invalid duration: ${raw}`);
+    const unit = m[2] ?? defaultUnit;
+    const ms = unit === "ms" ? num : unit === "s" ? num * 1000 : num * 60_000;
+    if (!Number.isFinite(ms) || ms <= 0)
+        throw new Error(`invalid duration: ${raw}`);
+    return Math.floor(ms);
+}
+function resolveHttpTimeoutMs() {
+    const msRaw = process.env.DOC2X_HTTP_TIMEOUT_MS;
+    if (msRaw != null && String(msRaw).trim() !== "")
+        return parsePositiveDurationMs(msRaw, "ms");
+    const raw = process.env.DOC2X_HTTP_TIMEOUT;
+    if (raw != null && String(raw).trim() !== "")
+        return parsePositiveDurationMs(raw, "s");
+    return 60_000;
+}
+export const RESOLVED_KEY = resolveApiKey();
+export const CONFIG = Object.freeze({
+    baseUrl: (process.env.DOC2X_BASE_URL || "https://v2.doc2x.noedgeai.com").replace(/\/+$/, ""),
+    apiKey: RESOLVED_KEY.apiKey,
+    httpTimeoutMs: resolveHttpTimeoutMs(),
+    pollIntervalMs: getEnvInt("DOC2X_POLL_INTERVAL_MS", 2_000),
+    maxWaitMs: getEnvInt("DOC2X_MAX_WAIT_MS", 600_000)
+});
+const DEFAULT_DOWNLOAD_HOST_SUFFIX_ALLOWLIST = Object.freeze([".amazonaws.com.cn", ".aliyuncs.com", ".noedgeai.com"]);
+export function parseDownloadUrlAllowlist() {
+    const raw = String(process.env.DOC2X_DOWNLOAD_URL_ALLOWLIST || "").trim();
+    if (!raw)
+        return [...DEFAULT_DOWNLOAD_HOST_SUFFIX_ALLOWLIST];
+    if (raw === "*")
+        return ["*"];
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export function isHostAllowedByAllowlist(hostname, allowlist) {
+    const host = hostname.toLowerCase();
+    for (const rule of allowlist) {
+        const r = rule.toLowerCase();
+        if (r === "*")
+            return true;
+        if (r.startsWith(".")) {
+            if (host.endsWith(r))
+                return true;
+            continue;
+        }
+        if (host === r)
+            return true;
+        if (host.endsWith("." + r))
+            return true;
+    }
+    return false;
+}

package/dist/doc2x/client.js

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import { CONFIG } from "../config.js";
+import { ToolError } from "../errors.js";
+import { jitteredBackoffMs, sleep } from "../utils.js";
+async function fetchJson(url, init, timeoutMs) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { ...init, signal: ctrl.signal });
+        const text = await res.text();
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            json = null;
+        }
+        return { res, text, json };
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+export function normalizeUrl(u) {
+    return String(u).replace(/\\u0026/g, "&");
+}
+export function isRetryableDoc2xBusinessCode(code) {
+    switch (code) {
+        case "parse_error":
+        case "parse_create_task_error":
+        case "parse_task_limit_exceeded":
+        case "parse_concurrency_limit":
+        case "parse_status_not_found":
+            return true;
+        default:
+            return false;
+    }
+}
+export function doc2xHeaders(extra) {
+    if (!CONFIG.apiKey) {
+        throw new ToolError({
+            code: "missing_api_key",
+            message: "Doc2x API key is not configured (set INLINE_DOC2X_API_KEY in src/config.ts or provide DOC2X_API_KEY env).",
+            retryable: false
+        });
+    }
+    return {
+        Authorization: `Bearer ${CONFIG.apiKey}`,
+        ...(extra || {})
+    };
+}
+export async function doc2xRequestJson(method, pathname, opts) {
+    const url = new URL(CONFIG.baseUrl + pathname);
+    if (opts?.query) {
+        for (const [k, v] of Object.entries(opts.query))
+            url.searchParams.set(k, v);
+    }
+    const init = { method, headers: doc2xHeaders() };
+    if (opts?.body != null) {
+        init.headers = doc2xHeaders({ "Content-Type": "application/json" });
+        init.body = JSON.stringify(opts.body);
+    }
+    let attempt = 0;
+    while (true) {
+        const { res, json, text } = await fetchJson(url.toString(), init, CONFIG.httpTimeoutMs);
+        if (res.status === 429) {
+            await sleep(jitteredBackoffMs(attempt++));
+            continue;
+        }
+        if (!res.ok) {
+            const snippet = text ? text.slice(0, 300) : "";
+            throw new ToolError({
+                code: `http_${res.status}`,
+                message: `Doc2x HTTP error: ${res.status} ${res.statusText}${snippet ? `; body=${JSON.stringify(snippet)}` : ""}`,
+                retryable: res.status >= 500 || res.status === 408 || res.status === 429
+            });
+        }
+        if (!json) {
+            throw new ToolError({ code: "invalid_json", message: `Doc2x returned non-JSON: ${text.slice(0, 200)}`, retryable: false });
+        }
+        if (json.code !== "success") {
+            const code = String(json.code || "doc2x_error");
+            throw new ToolError({
+                code,
+                message: String(json.msg || "Doc2x error"),
+                retryable: isRetryableDoc2xBusinessCode(code)
+            });
+        }
+        return json.data;
+    }
+}
+export async function putToSignedUrl(signedUrl, filePath) {
+    const stat = await fsp.stat(filePath);
+    const body = fs.createReadStream(filePath);
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), CONFIG.httpTimeoutMs);
+    try {
+        const res = await fetch(signedUrl, {
+            method: "PUT",
+            body: body,
+            duplex: "half",
+            headers: {
+                "Content-Type": "application/pdf",
+                "Content-Length": String(stat.size)
+            },
+            signal: ctrl.signal
+        });
+        if (!res.ok) {
+            const txt = await res.text().catch(() => "");
+            throw new ToolError({
+                code: `put_failed_${res.status}`,
+                message: `PUT to signed url failed: ${res.status} ${res.statusText} ${txt.slice(0, 200)}`,
+                retryable: res.status >= 500 || res.status === 408
+            });
+        }
+    }
+    finally {
+        clearTimeout(t);
+    }
+}

package/dist/doc2x/convert.js

@@ -0,0 +1,95 @@
+import path from "node:path";
+import { CONFIG } from "../config.js";
+import { ToolError } from "../errors.js";
+import { jitteredBackoffMs, sleep } from "../utils.js";
+import { doc2xRequestJson, normalizeUrl } from "./client.js";
+function normalizeExportFilename(filename, to, mode) {
+    const v = String(filename).trim();
+    if (!v)
+        return v;
+    const base = path.basename(v);
+    if (mode === "raw")
+        return base;
+    if (to === "md")
+        return base.replace(/\.md$/i, "");
+    if (to === "tex")
+        return base.replace(/\.tex$/i, "");
+    if (to === "docx")
+        return base.replace(/\.docx$/i, "");
+    return base;
+}
+function exportUrlLooksLike(url, to) {
+    const u = String(url || "").toLowerCase();
+    if (!u)
+        return false;
+    if (to === "docx")
+        return u.includes("convert_docx");
+    return u.includes(`convert_${to}_`);
+}
+export async function convertExportSubmit(args) {
+    const body = {
+        uid: args.uid,
+        to: args.to,
+        formula_mode: args.formula_mode
+    };
+    if (args.merge_cross_page_forms != null)
+        body.merge_cross_page_forms = args.merge_cross_page_forms;
+    if (args.filename != null)
+        body.filename = normalizeExportFilename(args.filename, args.to, args.filename_mode ?? "auto");
+    const data = await doc2xRequestJson("POST", "/api/v2/convert/parse", { body });
+    return { uid: args.uid, status: String(data.status), url: String(data.url || "") };
+}
+export async function convertExportResult(uid) {
+    const data = await doc2xRequestJson("GET", "/api/v2/convert/parse/result", { query: { uid } });
+    return { uid, status: String(data.status), url: data.url ? normalizeUrl(String(data.url)) : "" };
+}
+export async function convertExportWaitByUid(args) {
+    const pollInterval = args.poll_interval_ms ?? CONFIG.pollIntervalMs;
+    const maxWait = args.max_wait_ms ?? CONFIG.maxWaitMs;
+    const start = Date.now();
+    let attempt = 0;
+    while (true) {
+        if (Date.now() - start > maxWait) {
+            throw new ToolError({
+                code: "timeout",
+                message: `wait timeout after ${maxWait}ms (hint: exports for the same uid should be run sequentially, not in parallel)`,
+                retryable: true,
+                uid: args.uid
+            });
+        }
+        let st;
+        try {
+            st = await convertExportResult(args.uid);
+            attempt = 0;
+        }
+        catch (e) {
+            if (e instanceof ToolError && e.retryable) {
+                await sleep(jitteredBackoffMs(attempt++));
+                continue;
+            }
+            throw e;
+        }
+        if (st.status === "success") {
+            if (st.url && exportUrlLooksLike(st.url, args.to))
+                return st;
+            await sleep(pollInterval);
+            continue;
+        }
+        if (st.status === "failed")
+            throw new ToolError({ code: "convert_failed", message: "convert failed", retryable: true, uid: args.uid });
+        await sleep(pollInterval);
+    }
+}
+export async function convertExportWait(args) {
+    const pollInterval = args.poll_interval_ms ?? CONFIG.pollIntervalMs;
+    const maxWait = args.max_wait_ms ?? CONFIG.maxWaitMs;
+    await convertExportSubmit({
+        uid: args.uid,
+        to: args.to,
+        formula_mode: args.formula_mode,
+        filename: args.filename,
+        filename_mode: args.filename_mode,
+        merge_cross_page_forms: args.merge_cross_page_forms
+    });
+    return convertExportWaitByUid({ uid: args.uid, to: args.to, poll_interval_ms: pollInterval, max_wait_ms: maxWait });
+}

package/dist/doc2x/download.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { CONFIG, isHostAllowedByAllowlist, parseDownloadUrlAllowlist } from "../config.js";
+import { ToolError } from "../errors.js";
+import { normalizeUrl } from "./client.js";
+export async function downloadUrlToFile(args) {
+    const outPath = path.resolve(args.output_path);
+    await fsp.mkdir(path.dirname(outPath), { recursive: true });
+    const normalizedUrl = normalizeUrl(args.url);
+    let parsed;
+    try {
+        parsed = new URL(normalizedUrl);
+    }
+    catch {
+        throw new ToolError({ code: "invalid_url", message: "download failed: invalid url", retryable: false });
+    }
+    if (parsed.protocol !== "https:") {
+        throw new ToolError({ code: "unsafe_url", message: `download blocked: only https URLs are allowed (${parsed.protocol})`, retryable: false });
+    }
+    const allowlist = parseDownloadUrlAllowlist();
+    if (!isHostAllowedByAllowlist(parsed.hostname, allowlist)) {
+        throw new ToolError({
+            code: "unsafe_url",
+            message: `download blocked: host not allowed (${parsed.hostname}); set DOC2X_DOWNLOAD_URL_ALLOWLIST=\"*\" to allow any host, or provide a comma-separated allowlist`,
+            retryable: false
+        });
+    }
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), CONFIG.httpTimeoutMs);
+    try {
+        const res = await fetch(normalizedUrl, { method: "GET", signal: ctrl.signal });
+        if (!res.ok) {
+            throw new ToolError({
+                code: `http_${res.status}`,
+                message: `download failed: ${res.status} ${res.statusText}`,
+                retryable: res.status >= 500 || res.status === 408 || res.status === 429
+            });
+        }
+        if (!res.body)
+            throw new ToolError({ code: "empty_body", message: "download failed: empty body", retryable: true });
+        const file = fs.createWriteStream(outPath);
+        await new Promise((resolve, reject) => {
+            file.on("error", reject);
+            file.on("finish", resolve);
+            Readable.fromWeb(res.body).on("error", reject).pipe(file);
+        });
+        const stat = await fsp.stat(outPath);
+        return { output_path: outPath, bytes_written: stat.size };
+    }
+    finally {
+        clearTimeout(t);
+    }
+}

package/dist/doc2x/image.js

@@ -0,0 +1,146 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { CONFIG } from "../config.js";
+import { ToolError } from "../errors.js";
+import { jitteredBackoffMs, sleep } from "../utils.js";
+import { doc2xHeaders, doc2xRequestJson, isRetryableDoc2xBusinessCode } from "./client.js";
+async function readFileChecked(filePath, maxBytes) {
+    const p = path.resolve(filePath);
+    const st = await fsp.stat(p);
+    if (st.size > maxBytes)
+        throw new ToolError({ code: "file_too_large", message: `file too large: ${st.size} bytes`, retryable: false });
+    return await fsp.readFile(p);
+}
+export async function parseImageLayoutSync(imagePath) {
+    const buf = await readFileChecked(imagePath, 7 * 1024 * 1024);
+    const url = CONFIG.baseUrl + "/api/v2/parse/img/layout";
+    let attempt = 0;
+    while (true) {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), CONFIG.httpTimeoutMs);
+        try {
+            const res = await fetch(url, { method: "POST", headers: doc2xHeaders(), body: new Uint8Array(buf), signal: ctrl.signal });
+            if (res.status === 429) {
+                await sleep(jitteredBackoffMs(attempt++));
+                continue;
+            }
+            const text = await res.text();
+            let json = null;
+            try {
+                json = text ? JSON.parse(text) : null;
+            }
+            catch {
+                json = null;
+            }
+            if (!res.ok)
+                throw new ToolError({ code: `http_${res.status}`, message: `Doc2x HTTP error: ${res.status}`, retryable: res.status >= 500 || res.status === 429 });
+            if (!json || json.code !== "success") {
+                const code = String(json?.code || "doc2x_error");
+                const retryable = isRetryableDoc2xBusinessCode(code);
+                if (retryable) {
+                    await sleep(jitteredBackoffMs(attempt++));
+                    continue;
+                }
+                throw new ToolError({ code, message: String(json?.msg || "Doc2x error"), retryable });
+            }
+            return { uid: String(json.data.uid), result: json.data.result, convert_zip: json.data.convert_zip ?? null };
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+}
+export async function parseImageLayoutSubmit(imagePath) {
+    const buf = await readFileChecked(imagePath, 7 * 1024 * 1024);
+    const url = CONFIG.baseUrl + "/api/v2/async/parse/img/layout";
+    let attempt = 0;
+    while (true) {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), CONFIG.httpTimeoutMs);
+        try {
+            const res = await fetch(url, { method: "POST", headers: doc2xHeaders(), body: new Uint8Array(buf), signal: ctrl.signal });
+            if (res.status === 429) {
+                await sleep(jitteredBackoffMs(attempt++));
+                continue;
+            }
+            const text = await res.text();
+            let json = null;
+            try {
+                json = text ? JSON.parse(text) : null;
+            }
+            catch {
+                json = null;
+            }
+            if (!res.ok)
+                throw new ToolError({ code: `http_${res.status}`, message: `Doc2x HTTP error: ${res.status}`, retryable: res.status >= 500 || res.status === 429 });
+            if (!json || json.code !== "success") {
+                const code = String(json?.code || "doc2x_error");
+                const retryable = isRetryableDoc2xBusinessCode(code);
+                if (retryable) {
+                    await sleep(jitteredBackoffMs(attempt++));
+                    continue;
+                }
+                throw new ToolError({ code, message: String(json?.msg || "Doc2x error"), retryable });
+            }
+            return { uid: String(json.data.uid) };
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+}
+export async function parseImageLayoutStatus(uid) {
+    const data = await doc2xRequestJson("GET", "/api/v2/parse/img/layout/status", { query: { uid } });
+    return { uid, status: String(data.status), result: data.result ?? null, convert_zip: data.convert_zip ?? null };
+}
+export async function parseImageLayoutWaitTextByUid(args) {
+    const pollInterval = args.poll_interval_ms ?? CONFIG.pollIntervalMs;
+    const maxWait = args.max_wait_ms ?? Math.min(CONFIG.maxWaitMs, 300_000);
+    const uid = String(args.uid || "").trim();
+    if (!uid)
+        throw new ToolError({ code: "invalid_argument", message: "uid is required", retryable: false });
+    const start = Date.now();
+    let attempt = 0;
+    while (true) {
+        if (Date.now() - start > maxWait)
+            throw new ToolError({ code: "timeout", message: `wait timeout after ${maxWait}ms`, retryable: true, uid });
+        let st;
+        try {
+            st = await parseImageLayoutStatus(uid);
+            attempt = 0;
+        }
+        catch (e) {
+            if (e instanceof ToolError && e.retryable) {
+                await sleep(jitteredBackoffMs(attempt++));
+                continue;
+            }
+            throw e;
+        }
+        if (st.status === "success") {
+            const md = String(st?.result?.pages?.[0]?.md || "");
+            return { uid, status: "success", text: md };
+        }
+        if (st.status === "failed")
+            throw new ToolError({ code: "parse_failed", message: "parse failed", retryable: true, uid });
+        await sleep(pollInterval);
+    }
+}
+export async function parseImageLayoutWaitText(args) {
+    const uid = String(args.uid || "").trim();
+    if (uid) {
+        return parseImageLayoutWaitTextByUid({ uid, poll_interval_ms: args.poll_interval_ms, max_wait_ms: args.max_wait_ms });
+    }
+    const imagePath = String(args.image_path || "").trim();
+    if (!imagePath)
+        throw new ToolError({ code: "invalid_argument", message: "Either uid or image_path is required", retryable: false });
+    const pollInterval = args.poll_interval_ms ?? CONFIG.pollIntervalMs;
+    const maxWait = args.max_wait_ms ?? Math.min(CONFIG.maxWaitMs, 300_000);
+    const useAsyncMode = args.async !== false;
+    if (!useAsyncMode) {
+        const data = await parseImageLayoutSync(imagePath);
+        const md = String(data?.result?.pages?.[0]?.md || "");
+        return { uid: data.uid, status: "success", text: md };
+    }
+    const { uid: newUid } = await parseImageLayoutSubmit(imagePath);
+    return parseImageLayoutWaitTextByUid({ uid: newUid, poll_interval_ms: pollInterval, max_wait_ms: maxWait });
+}

package/dist/doc2x/materialize.js

@@ -0,0 +1,19 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+function spawnUnzip(zipPath, outputDir) {
+    return new Promise((resolve) => {
+        const child = spawn("unzip", ["-o", zipPath, "-d", outputDir], { stdio: "ignore" });
+        child.on("error", () => resolve(false));
+        child.on("exit", (code) => resolve(code === 0));
+    });
+}
+export async function materializeConvertZip(args) {
+    const outDir = path.resolve(args.output_dir);
+    await fsp.mkdir(outDir, { recursive: true });
+    const buf = Buffer.from(args.convert_zip_base64, "base64");
+    const zipPath = path.join(outDir, "assets.zip");
+    await fsp.writeFile(zipPath, buf);
+    const extracted = await spawnUnzip(zipPath, outDir);
+    return { output_dir: outDir, zip_path: zipPath, extracted };
+}

package/dist/doc2x/pdf.js

@@ -0,0 +1,89 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { CONFIG } from "../config.js";
+import { ToolError } from "../errors.js";
+import { jitteredBackoffMs, sleep } from "../utils.js";
+import { doc2xRequestJson, putToSignedUrl } from "./client.js";
+function mergePagesToText(result, joinWith) {
+    const pages = Array.isArray(result?.pages) ? result.pages.slice() : [];
+    pages.sort((a, b) => (a.page_idx ?? 0) - (b.page_idx ?? 0));
+    return pages.map((p) => String(p.md || "")).join(joinWith);
+}
+async function preuploadPdfWithRetry() {
+    let attempt = 0;
+    while (true) {
+        try {
+            const data = await doc2xRequestJson("POST", "/api/v2/parse/preupload");
+            return { uid: String(data.uid), url: String(data.url) };
+        }
+        catch (e) {
+            if (e instanceof ToolError && e.retryable) {
+                await sleep(jitteredBackoffMs(attempt++));
+                continue;
+            }
+            throw e;
+        }
+    }
+}
+export async function parsePdfSubmit(pdfPath) {
+    const p = path.resolve(pdfPath);
+    if (!p.toLowerCase().endsWith(".pdf"))
+        throw new ToolError({ code: "invalid_argument", message: "pdf_path must end with .pdf", retryable: false });
+    await fsp.access(p);
+    let data = await preuploadPdfWithRetry();
+    try {
+        await putToSignedUrl(String(data.url), p);
+    }
+    catch {
+        data = await preuploadPdfWithRetry();
+        await putToSignedUrl(String(data.url), p);
+    }
+    return { uid: String(data.uid) };
+}
+export async function parsePdfStatus(uid) {
+    const data = await doc2xRequestJson("GET", "/api/v2/parse/status", { query: { uid } });
+    return { uid, status: String(data.status), progress: Number(data.progress ?? 0), detail: String(data.detail || ""), result: data.result ?? null };
+}
+export async function parsePdfWaitTextByUid(args) {
+    const pollInterval = args.poll_interval_ms ?? CONFIG.pollIntervalMs;
+    const maxWait = args.max_wait_ms ?? CONFIG.maxWaitMs;
+    const joinWith = args.join_with ?? "\n\n---\n\n";
+    const uid = String(args.uid || "").trim();
+    if (!uid)
+        throw new ToolError({ code: "invalid_argument", message: "uid is required", retryable: false });
+    const start = Date.now();
+    let attempt = 0;
+    while (true) {
+        if (Date.now() - start > maxWait)
+            throw new ToolError({ code: "timeout", message: `wait timeout after ${maxWait}ms`, retryable: true, uid });
+        let st;
+        try {
+            st = await parsePdfStatus(uid);
+            attempt = 0;
+        }
+        catch (e) {
+            if (e instanceof ToolError && e.retryable) {
+                await sleep(jitteredBackoffMs(attempt++));
+                continue;
+            }
+            throw e;
+        }
+        if (st.status === "success")
+            return { uid, status: "success", text: mergePagesToText(st.result, joinWith) };
+        if (st.status === "failed")
+            throw new ToolError({ code: "parse_failed", message: st.detail || "parse failed", retryable: true, uid });
+        await sleep(pollInterval);
+    }
+}
+export async function parsePdfWaitText(args) {
+    const uid = String(args.uid || "").trim();
+    if (uid) {
+        return parsePdfWaitTextByUid({ uid, poll_interval_ms: args.poll_interval_ms, max_wait_ms: args.max_wait_ms, join_with: args.join_with });
+    }
+    const pdfPath = String(args.pdf_path || "").trim();
+    if (!pdfPath) {
+        throw new ToolError({ code: "invalid_argument", message: "Either uid or pdf_path is required", retryable: false });
+    }
+    const { uid: newUid } = await parsePdfSubmit(pdfPath);
+    return parsePdfWaitTextByUid({ uid: newUid, poll_interval_ms: args.poll_interval_ms, max_wait_ms: args.max_wait_ms, join_with: args.join_with });
+}

package/dist/errors.js

@@ -0,0 +1,15 @@
+export class ToolError extends Error {
+    code;
+    retryable;
+    uid;
+    constructor(args) {
+        super(args.message);
+        this.name = "ToolError";
+        this.code = args.code;
+        this.retryable = args.retryable;
+        this.uid = args.uid;
+    }
+    toPayload() {
+        return { error: { code: this.code, message: this.message, retryable: this.retryable, uid: this.uid } };
+    }
+}

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./mcp/registerTools.js";
+function readPackageVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkgPath = path.resolve(here, "../package.json");
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const server = new McpServer({ name: "doc2x-mcp", version: readPackageVersion() });
+registerTools(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    process.stderr.write(JSON.stringify({ ts: new Date().toISOString(), err: String(e?.stack || e) }) + os.EOL);
+    process.exitCode = 1;
+});

package/dist/mcp/registerTools.js

@@ -0,0 +1,307 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { CONFIG, RESOLVED_KEY, parseDownloadUrlAllowlist } from "../config.js";
+import { convertExportResult, convertExportSubmit, convertExportWaitByUid } from "../doc2x/convert.js";
+import { downloadUrlToFile } from "../doc2x/download.js";
+import { parseImageLayoutStatus, parseImageLayoutSubmit, parseImageLayoutSync, parseImageLayoutWaitTextByUid } from "../doc2x/image.js";
+import { materializeConvertZip } from "../doc2x/materialize.js";
+import { parsePdfStatus, parsePdfSubmit, parsePdfWaitTextByUid } from "../doc2x/pdf.js";
+import { ToolError } from "../errors.js";
+import { asErrorResult, asJsonResult, asTextResult } from "./results.js";
+async function fileSig(p) {
+    const absPath = path.resolve(p);
+    const st = await fsp.stat(absPath);
+    return { absPath, size: st.size, mtimeMs: st.mtimeMs };
+}
+function sameSig(a, b) {
+    return a.absPath === b.absPath && a.size === b.size && a.mtimeMs === b.mtimeMs;
+}
+export function registerTools(server) {
+    const pdfUidCache = new Map();
+    const imageUidCache = new Map();
+    const convertSubmitCache = new Set();
+    server.registerTool("doc2x_parse_pdf_submit", {
+        description: "Create a Doc2x PDF parse task for a local file and return {uid}. After this, call doc2x_parse_pdf_wait_text (with uid) or doc2x_parse_pdf_status.",
+        inputSchema: {
+            pdf_path: z
+                .string()
+                .min(1)
+                .describe("Absolute path to a local PDF file. Use an absolute path (relative paths are resolved from the MCP server process cwd, which may be '/'). Must end with '.pdf'.")
+        }
+    }, async ({ pdf_path }) => {
+        try {
+            const sig = await fileSig(pdf_path);
+            const res = await parsePdfSubmit(pdf_path);
+            pdfUidCache.set(sig.absPath, { sig, uid: res.uid });
+            return asJsonResult(res);
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_parse_pdf_status", {
+        description: "Get status/result for an existing Doc2x PDF parse task by uid.",
+        inputSchema: { uid: z.string().min(1).describe("Doc2x parse task uid returned by doc2x_parse_pdf_submit.") }
+    }, async ({ uid }) => {
+        try {
+            return asJsonResult(await parsePdfStatus(uid));
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_parse_pdf_wait_text", {
+        description: "Wait for a PDF parse task until success and return merged text. Prefer passing uid (no re-submit). If only pdf_path is provided, it will (a) reuse an in-process cached uid if available, otherwise (b) submit a new task then wait.",
+        inputSchema: {
+            uid: z.string().min(1).optional().describe("Doc2x parse task uid returned by doc2x_parse_pdf_submit."),
+            pdf_path: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Absolute path to a local PDF file. If uid is not provided, this tool will reuse cached uid (if any) or submit a new task."),
+            poll_interval_ms: z.number().int().positive().optional(),
+            max_wait_ms: z.number().int().positive().optional(),
+            join_with: z.string().optional()
+        }
+    }, async (args) => {
+        try {
+            const uid = String(args.uid || "").trim();
+            if (uid) {
+                const out = await parsePdfWaitTextByUid({
+                    uid,
+                    poll_interval_ms: args.poll_interval_ms,
+                    max_wait_ms: args.max_wait_ms,
+                    join_with: args.join_with
+                });
+                return asTextResult(out.text);
+            }
+            const pdfPath = String(args.pdf_path || "").trim();
+            if (!pdfPath)
+                throw new ToolError({ code: "invalid_argument", message: "Either uid or pdf_path is required.", retryable: false });
+            const sig = await fileSig(pdfPath);
+            const cached = pdfUidCache.get(sig.absPath);
+            const resolvedUid = cached && sameSig(cached.sig, sig) ? cached.uid : "";
+            const finalUid = resolvedUid || (await parsePdfSubmit(pdfPath)).uid;
+            pdfUidCache.set(sig.absPath, { sig, uid: finalUid });
+            const out = await parsePdfWaitTextByUid({
+                uid: finalUid,
+                poll_interval_ms: args.poll_interval_ms,
+                max_wait_ms: args.max_wait_ms,
+                join_with: args.join_with
+            });
+            return asTextResult(out.text);
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_convert_export_submit", {
+        description: "Start an export (convert) job for a parsed PDF uid. After this, poll with doc2x_convert_export_wait or doc2x_convert_export_result. Do NOT call doc2x_convert_export_submit twice for the same uid+format in parallel.",
+        inputSchema: {
+            uid: z.string().min(1).describe("Doc2x parse task uid returned by doc2x_parse_pdf_submit."),
+            to: z.enum(["md", "tex", "docx"]),
+            formula_mode: z.enum(["normal", "dollar"]),
+            filename: z
+                .string()
+                .describe("Optional output filename (for md/tex only). Tip: pass a basename WITHOUT extension to avoid getting 'name.md.md' / 'name.tex.tex'.")
+                .optional(),
+            filename_mode: z
+                .enum(["auto", "raw"])
+                .describe("How to treat filename. 'auto' strips common extensions for the target format; 'raw' passes basename as-is.")
+                .optional(),
+            merge_cross_page_forms: z.boolean().optional()
+        }
+    }, async (args) => {
+        try {
+            const key = JSON.stringify({
+                uid: args.uid,
+                to: args.to,
+                formula_mode: args.formula_mode,
+                filename: args.filename ?? null,
+                filename_mode: args.filename_mode ?? null,
+                merge_cross_page_forms: args.merge_cross_page_forms ?? null
+            });
+            const res = await convertExportSubmit(args);
+            convertSubmitCache.add(key);
+            return asJsonResult(res);
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_convert_export_result", {
+        description: "Get the latest export (convert) result for a parsed PDF uid (may contain an escaped URL).",
+        inputSchema: { uid: z.string().min(1).describe("Doc2x parse task uid returned by doc2x_parse_pdf_submit.") }
+    }, async ({ uid }) => {
+        try {
+            return asJsonResult(await convertExportResult(uid));
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_convert_export_wait", {
+        description: "Wait for an export job to finish. Prefer calling doc2x_convert_export_submit first, then wait with uid+to. For backward compatibility, if formula_mode is provided and this job was not submitted in-process, this tool will submit once then wait.",
+        inputSchema: {
+            uid: z.string().min(1).describe("Doc2x parse task uid returned by doc2x_parse_pdf_submit."),
+            to: z.enum(["md", "tex", "docx"]).describe("Expected target format. Used to verify the result URL."),
+            formula_mode: z.enum(["normal", "dollar"]).optional(),
+            filename: z.string().optional(),
+            filename_mode: z.enum(["auto", "raw"]).optional(),
+            merge_cross_page_forms: z.boolean().optional(),
+            poll_interval_ms: z.number().int().positive().optional(),
+            max_wait_ms: z.number().int().positive().optional()
+        }
+    }, async (args) => {
+        try {
+            if (args.formula_mode) {
+                const key = JSON.stringify({
+                    uid: args.uid,
+                    to: args.to,
+                    formula_mode: args.formula_mode,
+                    filename: args.filename ?? null,
+                    filename_mode: args.filename_mode ?? null,
+                    merge_cross_page_forms: args.merge_cross_page_forms ?? null
+                });
+                if (!convertSubmitCache.has(key)) {
+                    await convertExportSubmit({
+                        uid: args.uid,
+                        to: args.to,
+                        formula_mode: args.formula_mode,
+                        filename: args.filename,
+                        filename_mode: args.filename_mode,
+                        merge_cross_page_forms: args.merge_cross_page_forms
+                    });
+                    convertSubmitCache.add(key);
+                }
+            }
+            return asJsonResult(await convertExportWaitByUid(args));
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_download_url_to_file", {
+        description: "Download a Doc2x-provided URL (e.g. from doc2x_convert_export_result) to a local file path.",
+        inputSchema: {
+            url: z.string().min(1).describe("A URL returned by doc2x_convert_export_result (may contain escaped '\\u0026')."),
+            output_path: z.string().min(1).describe("Absolute path for the output file. The file will be overwritten if it exists.")
+        }
+    }, async (args) => {
+        try {
+            return asJsonResult(await downloadUrlToFile(args));
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_parse_image_layout_sync", {
+        description: "Parse an image layout synchronously and return the raw Doc2x result JSON (including convert_zip when present).",
+        inputSchema: {
+            image_path: z
+                .string()
+                .min(1)
+                .describe("Absolute path to a local image file (png/jpg). Use an absolute path (relative paths are resolved from the MCP server process cwd, which may be '/').")
+        }
+    }, async ({ image_path }) => {
+        try {
+            return asJsonResult(await parseImageLayoutSync(image_path));
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_parse_image_layout_submit", {
+        description: "Create an async image-layout parse task and return {uid}. After this, call doc2x_parse_image_layout_wait_text (with uid) or doc2x_parse_image_layout_status.",
+        inputSchema: {
+            image_path: z
+                .string()
+                .min(1)
+                .describe("Absolute path to a local image file (png/jpg). Use an absolute path (relative paths are resolved from the MCP server process cwd, which may be '/').")
+        }
+    }, async ({ image_path }) => {
+        try {
+            const sig = await fileSig(image_path);
+            const res = await parseImageLayoutSubmit(image_path);
+            imageUidCache.set(sig.absPath, { sig, uid: res.uid });
+            return asJsonResult(res);
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_parse_image_layout_status", {
+        description: "Get status/result for an existing async image-layout parse task by uid.",
+        inputSchema: { uid: z.string().min(1).describe("Doc2x image-layout parse task uid returned by doc2x_parse_image_layout_submit.") }
+    }, async ({ uid }) => {
+        try {
+            return asJsonResult(await parseImageLayoutStatus(uid));
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_parse_image_layout_wait_text", {
+        description: "Wait for an image-layout parse task until success, returning first page markdown. Prefer passing uid (no re-submit). If only image_path is provided, it will (a) reuse an in-process cached uid if available, otherwise (b) submit a new async task then wait.",
+        inputSchema: {
+            uid: z.string().min(1).optional().describe("Doc2x image-layout parse task uid returned by doc2x_parse_image_layout_submit."),
+            image_path: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Absolute path to a local image file (png/jpg). Used to reuse cached uid or submit a new async task."),
+            poll_interval_ms: z.number().int().positive().optional(),
+            max_wait_ms: z.number().int().positive().optional()
+        }
+    }, async (args) => {
+        try {
+            const uid = String(args.uid || "").trim();
+            if (uid) {
+                const out = await parseImageLayoutWaitTextByUid({ uid, poll_interval_ms: args.poll_interval_ms, max_wait_ms: args.max_wait_ms });
+                return asTextResult(out.text);
+            }
+            const imagePath = String(args.image_path || "").trim();
+            if (!imagePath)
+                throw new ToolError({ code: "invalid_argument", message: "Either uid or image_path is required.", retryable: false });
+            const sig = await fileSig(imagePath);
+            const cached = imageUidCache.get(sig.absPath);
+            const resolvedUid = cached && sameSig(cached.sig, sig) ? cached.uid : "";
+            const finalUid = resolvedUid || (await parseImageLayoutSubmit(imagePath)).uid;
+            imageUidCache.set(sig.absPath, { sig, uid: finalUid });
+            const out = await parseImageLayoutWaitTextByUid({ uid: finalUid, poll_interval_ms: args.poll_interval_ms, max_wait_ms: args.max_wait_ms });
+            return asTextResult(out.text);
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_materialize_convert_zip", {
+        description: "Materialize convert_zip (base64) into output_dir. Best-effort: tries system unzip first; otherwise writes the zip file.",
+        inputSchema: { convert_zip_base64: z.string().min(1), output_dir: z.string().min(1) }
+    }, async (args) => {
+        try {
+            return asJsonResult(await materializeConvertZip({ convert_zip_base64: args.convert_zip_base64, output_dir: args.output_dir }));
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+    server.registerTool("doc2x_debug_config", { description: "Debug helper: return resolved config and API key source for troubleshooting.", inputSchema: {} }, async () => {
+        try {
+            return asJsonResult({
+                baseUrl: CONFIG.baseUrl,
+                apiKeySource: RESOLVED_KEY.source,
+                apiKeyLen: CONFIG.apiKey.length,
+                apiKeyPrefix: CONFIG.apiKey ? CONFIG.apiKey.slice(0, 6) : "",
+                pollIntervalMs: CONFIG.pollIntervalMs,
+                httpTimeoutMs: CONFIG.httpTimeoutMs,
+                maxWaitMs: CONFIG.maxWaitMs,
+                downloadUrlAllowlist: parseDownloadUrlAllowlist()
+            });
+        }
+        catch (e) {
+            return asErrorResult(e);
+        }
+    });
+}

package/dist/mcp/results.js

@@ -0,0 +1,13 @@
+import { ToolError } from "../errors.js";
+export function asTextResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+export function asJsonResult(obj) {
+    return { content: [{ type: "text", text: JSON.stringify(obj, null, 2) }] };
+}
+export function asErrorResult(e) {
+    const payload = e instanceof ToolError
+        ? e.toPayload()
+        : { error: { code: "internal_error", message: String(e?.message || e), retryable: false } };
+    return { isError: true, content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}

package/dist/utils.js

@@ -0,0 +1,21 @@
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, ms);
+        if (!signal)
+            return;
+        if (signal.aborted) {
+            clearTimeout(t);
+            reject(new Error("aborted"));
+            return;
+        }
+        signal.addEventListener("abort", () => {
+            clearTimeout(t);
+            reject(new Error("aborted"));
+        }, { once: true });
+    });
+}
+export function jitteredBackoffMs(attempt) {
+    const base = Math.min(30_000, 1_000 * Math.pow(2, Math.max(0, attempt)));
+    const jitter = Math.floor(Math.random() * 250);
+    return base + jitter;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@noedgeai-org/doc2x-mcp",
+  "version": "0.1.0",
+  "description": "Doc2x MCP server (stdio, MCP SDK).",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "doc2x-mcp": "dist/index.js"
+  },
+  "files": [
+    "./dist",
+    "./README.md",
+    "./package.json"
+  ],
+  "scripts": {
+    "build": "node ./node_modules/typescript/bin/tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "zod": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "typescript": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NoEdgeAI/doc2x-mcp.git"
+  },
+  "keywords": [
+    "doc2x"
+  ],
+  "author": "hsn",
+  "bugs": {
+    "url": "https://github.com/NoEdgeAI/doc2x-mcp/issues"
+  },
+  "homepage": "https://github.com/NoEdgeAI/doc2x-mcp#readme"
+}