Doc2X 文档

简体中文

English

简体中文

English

主题

Doc2X MCP 使用指南 ​

本指南介绍如何在不同客户端中接入 Doc2X MCP，并通过 MCP 调用 Doc2X 服务解析 PDF 等文档。

说明：MCP（stdio）本质上是“客户端启动一个本地进程（这里是 npx ...doc2x-mcp），并通过标准输入输出与之通信”。 因此，运行环境的网络/代理、Node.js、以及环境变量注入方式，会直接影响接入是否成功。

前提条件 ​

  • 已获取 Doc2X API Key（示例：sk-xxx） 获取地址：open.noedgeai.com
  • 已安装 Node.js，并可使用 npx
  • 网络可正常访问 Doc2X 服务（请直连国内，国外用户请自行配置代理）

通用 MCP 配置 ​

在支持 MCP（stdio）的客户端中添加如下配置：

json
{
  "command": "npx",
  "args": ["-y", "@noedgeai-org/doc2x-mcp@latest"],
  "env": {
    "DOC2X_API_KEY": "sk-xxx"
  }
}

环境变量说明 ​

变量必填默认值
DOC2X_API_KEY是-
DOC2X_BASE_URL否https://v2.doc2x.noedgeai.com
DOC2X_HTTP_TIMEOUT_MS否60000
DOC2X_POLL_INTERVAL_MS否2000
DOC2X_MAX_WAIT_MS否600000
DOC2X_PARSE_PDF_MAX_OUTPUT_CHARS否5000
DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES否10
DOC2X_DOWNLOAD_URL_ALLOWLIST否.amazonaws.com.cn,.aliyuncs.com,.noedgeai.com

说明：

  • DOC2X_API_KEY：Doc2X API Key（形如 sk-xxx）
  • DOC2X_HTTP_TIMEOUT_MS / DOC2X_POLL_INTERVAL_MS / DOC2X_MAX_WAIT_MS：单位毫秒
  • DOC2X_PARSE_PDF_MAX_OUTPUT_CHARS：限制 doc2x_parse_pdf_wait_text 返回文本最大字符数（0 表示不限制）
  • DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES：限制 doc2x_parse_pdf_wait_text 合并最大页数（0 表示不限制）
  • DOC2X_DOWNLOAD_URL_ALLOWLIST：限制 doc2x_download_url_to_file 允许下载的 host（逗号分隔；* 表示允许任意 host，不推荐）

常见问题 ​

  1. 提示找不到 npx

    • 请确认已安装 Node.js（建议 LTS 版本）
    • 重新打开终端或检查 PATH 环境变量

  2. 依赖安装缓慢或失败

    • 检查网络或代理配置
    • 可切换 npm 镜像源后重试

  3. API Key 不生效

    • 确认 MCP 启动时已注入 DOC2X_API_KEY
    • 检查客户端日志是否成功读取环境变量

  4. formula_level 为什么不生效

    • formula_level 只对 v3-2026 解析任务生效
    • 如果源解析任务使用的是默认 v2，即使改 formula_level，导出结果看起来也可能“没变化”
    • 需要在提交 PDF 解析任务时显式使用 model: "v3-2026"，再比较 formula_level=0/1/2 的差异

  5. 为什么三次导出结果一样

    • 对同一个 uid + to 连续导出时，导出对象可能被后一次覆盖
    • 做 formula_level=0/1/2 对比时，请在每次导出成功后立即下载对应结果
    • 不要等三次都导出完再统一下载，否则拿到的可能都是最后一次的结果

  6. 为什么大模型输入被截断了 / 返回文本不完整

    • doc2x_parse_pdf_wait_text 会把解析结果合并成一段文本返回；当文本过长，可能超过模型/会话的上下文上限，从而在输入侧被截断
    • 优先用 DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES / DOC2X_PARSE_PDF_MAX_OUTPUT_CHARS 限制合并页数与返回字符数（推荐默认：10 / 5000；仍会截断就继续调小，例如 5 / 3000）
    • 如需拿到完整内容，建议走“导出为 md/tex/docx 到本地文件”的流程，再基于导出文件做总结/翻译/抽取，而不是把全文直接塞进对话

  7. 下载的文件打开后是乱码

    • 先确认下载到的是不是压缩包（如 .zip）；部分导出结果需要先解压再查看
    • 可先执行 unzip your_file.zip -d output_dir，再打开解压后的文件
    • 若是 .md / .tex 文本文件，建议使用支持 UTF-8 的编辑器打开

  8. 不知道怎么写提示词 / 模型没有调用 Doc2X MCP

    请在提示词中 明确说明使用 doc2x-mcp（或 doc2x MCP），并清楚给出：

    • 本地文件的绝对路径，或者相对于当前工作目录的路径。
    • 是否需要导出
    • 导出格式（md / tex / docx）
    • （如需要）保存的目标路径或后续处理要求

    推荐提示词模板（请按你的实际文件名与路径替换，尽量使用绝对路径）：

    1. 解析 PDF 并导出为 Markdown / LaTeX / Word

      text
      使用 doc2x-mcp 解析 /abs/path/paper.pdf，并导出为 md|tex|docx（例如 md）。

    2. 解析 PDF → 导出 Markdown → 总结要点

      text
      先用 doc2x-mcp 解析 /abs/path/paper.pdf 并导出为 md；
然后基于导出的内容给我 10 条要点 + 1 段总结。

    3. 解析 PDF → 导出 Markdown → 翻译为中文（保留公式/代码）

      text
      用 doc2x-mcp 解析 /abs/path/paper.pdf 并导出为 md；
再把正文翻译成中文，但保留代码块和数学公式不翻译。

    4. 解析 PDF → 导出 Markdown → 生成目录

      text
      用 doc2x-mcp 解析 /abs/path/paper.pdf 并导出为 md；
然后给我一份按标题层级生成的目录。

    5. 解析 PDF → 导出 Markdown → 按一级标题分段输出

      text
      用 doc2x-mcp 解析 /abs/path/paper.pdf 并导出为 md；
如果内容较长，请按一级标题分段输出，并标注每段对应的标题。

客户端配置指南 ​

安装本仓库 Skill ​

这一节用于给 Codex CLI / Claude Code 安装 doc2x-mcp 仓库提供的本地 Skill：把“如何使用 doc2x-mcp tools（解析 → 导出 → 下载 / 排错）”固化成可复用的工作流提示，减少你在每次对话里重复解释的成本。

提示：一键安装是远程脚本执行（curl | sh / irm | iex）。建议在公司/生产环境先审阅脚本内容，再执行。另见：Claude Code Skills 文档。

一键安装 ​

macOS / Linux：

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

Windows PowerShell：

powershell
irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex

默认会同时安装到 Codex CLI + Claude Code。安装后检查以下目录是否存在（必要时重启对应客户端）：

  • Codex CLI：~/.codex/skills/public/doc2x-mcp（用 CODEX_HOME 覆盖）
  • Claude Code：~/.claude/skills/doc2x-mcp（用 CLAUDE_HOME 覆盖）

Skill 具体内容（SKILL.md，可直接打开查看）：

项目链接 ​