Doc2x MCP Server

简体中文 | English

将 Doc2x v2 PDF/图片能力封装为基于 stdio 的 MCP Server，提供稳定、可组合的语义化 tools。

目录

• 项目定位

• 版本与环境

• 快速开始

• 配置参考

• Tool API 总览

• 常见工作流

• 本地开发

• CI / 发布流水线

• 如何发布

• 安装本仓库 Skill（可选）

• 安全与排错

• 问题反馈

• Changelog

• License

Related MCP server: document-parser

项目定位

• 面向 MCP 客户端（Codex CLI / Claude Code / 自定义 Agent）提供 Doc2x 能力。

• 以 submit/status/wait 统一异步任务模型，便于自动化编排。

• 提供可控超时、轮询、下载白名单等运行时安全边界。

版本与环境

• 本地运行：Node.js >=18 即可。

• CI 校验：Node.js 18、20 都会跑构建。

• 发布环境：GitHub Actions 中发布任务使用 Node.js 24。

• 包管理器：统一用 pnpm（锁文件 pnpm-lock.yaml）。

快速开始

方式 A：通过 npx（推荐）

在 MCP client 配置中添加：

{
  "command": "npx",
  "args": ["-y", "@noedgeai-org/doc2x-mcp@latest"],
  "env": {
    "DOC2X_API_KEY": "sk-xxx",
    "DOC2X_BASE_URL": "https://v2.doc2x.noedgeai.com"
  }
}

方式 B：本地源码运行

cd doc2x-mcp
pnpm install --frozen-lockfile
pnpm run build
DOC2X_API_KEY=sk-xxx pnpm start

MCP client 指向本地构建产物：

{
  "command": "node",
  "args": ["<ABS_PATH>/doc2x-mcp/dist/index.js"],
  "env": {
    "DOC2X_API_KEY": "sk-xxx",
    "DOC2X_BASE_URL": "https://v2.doc2x.noedgeai.com"
  }
}

配置参考

Tool API 总览

PDF 解析模型（doc2x_parse_pdf_submit / doc2x_parse_pdf_wait_text）

• 可选参数：model

• 可选值：v2（默认） / v3-2026（最新模型）

• 不传时默认 v2

{
  "model": "v3-2026"
}

PDF Layout JSON 落盘（doc2x_materialize_pdf_layout_json）

• 必选参数：output_path

• uid 与 pdf_path 二选一

• v2 不支持 layout；需要 pages[].layout 时请使用 v3-2026

• 若传 pdf_path 但不传 model，该工具默认使用 v3-2026

• 成功时将原始 result JSON 写到本地

layout 是页面块结构和坐标信息，适合 figure/table 裁剪、区域高亮、结构化抽取和版面分析；如果只想看正文内容，优先使用 Markdown / DOCX 导出。

{
  "pdf_path": "/absolute/path/to/input.pdf",
  "output_path": "/absolute/path/to/input_v3.layout.json"
}

导出公式参数（doc2x_convert_export_submit / doc2x_convert_export_wait）

• 必选参数：formula_mode（normal / dollar）

• 可选参数：formula_level（仅源解析任务为 model=v3-2026 时生效）

• 取值说明：

  • 0：保留公式

  • 1：仅退化行内公式（\\(...\\)、$...$）

  • 2：退化全部公式（\\(...\\)、$...$、\\[...\\]、$$...$$）

导出文件名

filename 是 API 内部导出文件的名称，不影响下载时指定的本地路径。默认 filename_mode="auto" 先取 basename、去掉对应格式的扩展名，再将超过 50 个 Unicode 字符的名称缩短为前缀加稳定哈希后缀，避免服务端文件名校验失败。同名前缀的不同长标题会使用不同后缀。

filename_mode="raw" 保留 basename 及扩展名；超过 50 个 Unicode 字符时，在发送请求前返回不可重试的 invalid_argument。请缩短名称或改用 auto。这些规则也适用于 doc2x_convert_export_wait 的自动提交。

等待导出同时支持当前 API 的不透明下载地址和旧格式地址。同一 uid 的不同格式导出请按顺序进行，避免读取到另一笔导出的结果。

常见工作流

工作流 1：PDF -> Markdown 本地文件

1. doc2x_parse_pdf_submit 提交 PDF 解析。

2. doc2x_convert_export_wait 等待导出（to=md，并指定 formula_mode）。

3. doc2x_convert_export_result 获取下载 URL。

4. doc2x_download_url_to_file 下载到目标路径。

工作流 2：图片版面 OCR 快速结果

1. doc2x_parse_image_layout_sync 直接同步解析。

2. 若需要稳态轮询，改用 submit/status/wait 组合。

工作流 3：PDF -> v3 layout JSON 本地文件

1. 调用 doc2x_materialize_pdf_layout_json，传入 pdf_path 和 output_path。

2. 工具会等待 parse 成功，并将原始 result JSON 落到本地。

3. 该 JSON 可直接提供给后续 figure/table 裁剪脚本使用。

本地开发

环境要求

• Node.js >=18

• pnpm（与仓库锁文件一致）

常用命令

pnpm install --frozen-lockfile
pnpm run build
pnpm run test
pnpm run format:check

运行服务：

DOC2X_API_KEY=sk-xxx pnpm start

CI / 发布流水线

仓库使用 GitHub Actions：

• CI：.github/workflows/ci.yml

  • 触发：push 到 main、pull_request、workflow_dispatch、每周一 UTC 03:17

  • 文档-only 变更（**/*.md、LICENSE）自动跳过

  • 任务：

    • dependency-review（仅 PR）

    • build（Node.js 18/20 矩阵）

    • package-smoke（npm pack --dry-run）

    • security-audit（仅手动/定时）

• Publish：.github/workflows/publish.yml

  • dev 分支 push：发布 npm dev tag

  • v*.*.* tag push：发布 npm latest

  • 发布前校验 tag 版本与 package.json 版本一致

  • 发布命令：npm publish --provenance

建议提交前本地对齐：

pnpm install --frozen-lockfile
pnpm run build
npm pack --dry-run
pnpm audit --prod --audit-level high

如何发布

• 开发预发布（dev）：push 到 dev 分支后自动发布到 npm dev tag。版本会自动改成 x.y.z-dev.<run>.<attempt>。

• 正式发布（latest）：push v*.*.* tag 后发布到 npm latest。tag 版本必须和 package.json 版本一致。

安装本仓库 Skill（可选）

用于给 Codex CLI / Claude Code 增加一个"教大模型如何使用 doc2x-mcp tools 的 Skill"。

提示： 每次升级 doc2x-mcp 版本后，建议重新运行安装命令以更新 Skill，确保大模型使用最新的 tool 描述与工作流。

不需要 clone 仓库的一键安装（推荐）：

curl -fsSL https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.sh | sh

在本仓库源码目录安装：

pnpm run skill:install

默认安装目录：

• Codex CLI：~/.codex/skills/public/doc2x-mcp（可用 CODEX_HOME 覆盖）

• Claude Code：~/.claude/skills/doc2x-mcp（可用 CLAUDE_HOME 覆盖）

说明：

• --target auto（默认）会同时安装到 Codex + Claude。

• PowerShell 7+：irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex

• Windows PowerShell 5.1：irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill-winps.ps1 | iex

安全与排错

• 不要在仓库提交真实 DOC2X_API_KEY。

• 白名单默认限制下载域名；如需放开，评估风险后再使用 DOC2X_DOWNLOAD_URL_ALLOWLIST=*。

• 配置异常时优先调用 doc2x_debug_config 定位环境变量来源与解析结果。

问题反馈

• 使用问题或缺陷反馈：GitHub Issues
  https://github.com/NoEdgeAI/doc2x-mcp/issues

• 建议在 issue 中附上最小复现输入、触发的 tool 名称、以及 doc2x_debug_config 结果（可脱敏）。

License

MIT License，详见 LICENSE。