Doc2X MCP 使用指南

个人工作台账户的手动 Token 和远程 OAuth 授权见主产品账户 MCP 授权。

Doc2X MCP 将开放平台 PDF/图片解析、状态查询与本地保存封装成工具。MCP 客户端通过 stdio 启动本地进程；文件路径必须在运行该进程的电脑上可读，不能只把文件名写进对话就视为上传完成。

本教程按公开 npm 包 @noedgeai-org/doc2x-mcp@0.1.5 核对。中英文示例使用相同固定版本；升级时先阅读官方版本与工具说明，不要假设旧版本有新工具。

前提条件

Node.js 18 或以上，可执行 npx；依赖解析还应满足实际安装包要求。
在开放平台获取 API Key 并确认解析额度。YOUR_DOC2X_API_KEY 是占位符，不是桌面客户端登录 Token。
准备可读取的绝对文件路径与可写的新输出目录。PDF/图片上限与额度遵循API 合同，不套用网页/CLI导出范围。
客户端需要能启动 stdio 进程并访问网络；根据自己的网络配置代理，不要求所有海外环境必须绕行代理。

通用 MCP 配置

json

{
  "command": "npx",
  "args": ["-y", "@noedgeai-org/doc2x-mcp@0.1.5"],
  "env": {"DOC2X_API_KEY": "YOUR_DOC2X_API_KEY"}
}

保存到所用客户端的 MCP 配置中，不在聊天里粘贴真实 Key。客户端管理的配置文件可能保存明文环境变量，注意文件权限与共享范围。先确认服务器可用、工具列表出现，再授权业务任务；启动成功不等于已经解析文件。

从 PDF 到本地文件

PDF API 与 MCP 底层请求：先等解析成功，再导出并保存

放大查看流程图

以下是工具参数示意，不是终端命令。路径换成真实本地路径，TASK_UID 换成提交返回的 uid。

调用 doc2x_parse_pdf_submit，记录返回的任务 ID。
json
```
{"pdf_path":"/absolute/path/paper.pdf","model":"v3-2026"}
```
调用 doc2x_parse_pdf_status，传 {"uid":"TASK_UID"}。只有 status=success 才继续；processing 等待，failed 看 detail。该工具返回状态摘要，不把它当作完整正文。
调用 doc2x_convert_export_wait，显式选择格式与公式方式。它可发起并等待一次导出；不要同时反复调用 submit。
json
```
{"uid":"TASK_UID","to":"md","formula_mode":"normal","filename":"paper"}
```

成功后使用返回的 URL 调用 doc2x_download_url_to_file。

json

{"url":"https://download.example.invalid/export.zip","output_path":"/absolute/path/output/export.zip"}

检查实际保存路径和格式。MD/TEX 可能是 ZIP，保留图片资源与相对路径；DOCX 用办公软件检查。不要把工具调用成功当成公式编辑、排版或内容正确的证明。

建议提示词：

text

使用 doc2x-mcp 解析 /absolute/path/paper.pdf，模型 v3-2026。
保存返回 uid，查询至成功后导出 md（formula_mode=normal），下载到 /absolute/path/output/。
返回实际保存的文件路径；超时先报告现有 uid 和阶段，不重新提交解析。

摘要、翻译与生成目录通常是客户端模型读取结果后的后续处理，不是此 MCP 已提供独立文档翻译 API；模型服务可能另行计费。

全部工具与适用步骤

工具	输入与结果
`doc2x_parse_pdf_submit`	`pdf_path`，可选 `model`；创建解析任务并返回 `uid`。
`doc2x_parse_pdf_status`	`uid`；状态、进度和失败说明。
`doc2x_parse_pdf_wait_text`	优先传已有 `uid`；等待并返回合并文本，受页数/字数截断限制。只有 `pdf_path` 时可能新建任务。
`doc2x_materialize_pdf_layout_json`	`output_path` 加 `uid` 或 `pdf_path`；保存原始 `result` JSON。需要 layout 时使用 `v3-2026`；从路径新建时默认该模型。
`doc2x_convert_export_submit`	`uid`、`to`、`formula_mode`；开始导出，不作为轮询接口。
`doc2x_convert_export_result`	`uid`；查询最近一次导出状态/URL。
`doc2x_convert_export_wait`	`uid`、`to`、`formula_mode`；等待导出，支持有界等待参数。
`doc2x_download_url_to_file`	`url`、`output_path`；下载允许域名的资源到本地。
`doc2x_materialize_convert_zip`	`convert_zip_base64`、`output_dir`；保存/尝试解包图片资源；缺少系统解包工具时可能只写 ZIP。
`doc2x_parse_image_layout_sync`	`image_path`；同步返回原始解析 JSON，可含 `convert_zip`。
`doc2x_parse_image_layout_submit`	`image_path`；异步提交图片并返回 `uid`。
`doc2x_parse_image_layout_status`	`uid`；图片任务状态与完成结果。
`doc2x_parse_image_layout_wait_text`	优先传已有 `uid`；等待并返回首个页面 Markdown。
`doc2x_debug_config`	空参数 `{}`；诊断配置来源，输出可能含 Key 前缀/长度，分享前仍需脱敏。

v3 JSON 与图片流程

保存 v3 JSON：doc2x_materialize_pdf_layout_json 使用 {"uid":"TASK_UID","output_path":"/absolute/path/output/layout.json"}。已有任务若非 v3，不能靠导出参数把旧结果变成完整 layout；先确认实际模型与字段，再决定是否需要新任务。详见 v3 结果结构。

图片使用 image_path，同步或异步二选一；异步保存 uid 后查状态。完成后如有 convert_zip，用资源落盘工具保存；首屏文本不等于完整资源包。图片条件参见图片 API。

环境变量说明

变量	默认值/作用
`DOC2X_API_KEY`	必填，开放平台 Key。
`DOC2X_BASE_URL`	`https://v2.doc2x.noedgeai.com`
`DOC2X_HTTP_TIMEOUT_MS`	`60000`，单次 HTTP 请求超时。
`DOC2X_POLL_INTERVAL_MS`	`2000`，轮询间隔。
`DOC2X_MAX_WAIT_MS`	`600000`，wait 工具等待上限；超时不是取消。
`DOC2X_PARSE_PDF_MAX_OUTPUT_CHARS`	`5000`，PDF文本返回字数限制；`0`不限制。
`DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES`	`10`，PDF文本合并页数限制；`0`不限制。
`DOC2X_DOWNLOAD_URL_ALLOWLIST`	`.amazonaws.com.cn,.aliyuncs.com,.noedgeai.com`；不要为下载失败直接放宽到 `*`。

公式与文件边界

导出 to 为 md/tex/docx，不从网页菜单推导 XLSX、保版 Word、MathType 等工具参数。
formula_mode 必填，normal/dollar；formula_level=0/1/2 只对 v3 源任务生效。比较多个版本时每次成功后立即下载，避免同一任务后一次导出覆盖前一结果。
doc2x_parse_pdf_wait_text 默认只返回最多 10 页、5000 字符。需要全文时导出文件；不要把截断内容称为完整文档。API结果临时保留约24小时，尽快本地保存。
不同客户端、进程重启或缓存失效时，重新传路径可能再次创建任务。续查应优先使用已保存的 uid。

客户端配置指南

可选：安装工作流 Skill

MCP Server 提供工具；Skill 提供工作流说明，二者不是同一个安装步骤。官方仓库提供 Skill 与安装说明。先阅读脚本及目标目录，再按自己客户端安装；只安装 Skill 不会自动完成 API 鉴权或授权业务调用。

常见问题

现象	排查
找不到 `npx`/服务器离线	检查 Node、PATH、客户端进程环境和依赖下载；stdio 正常等待输入不一定是卡死。
Key 无效	在服务器进程环境注入正确开放平台 Key；不要把真实 Key 或完整诊断日志发到公开问题单。
文件不存在/输出不可写	路径属于 MCP 运行主机，不一定属于浏览器电脑；检查绝对路径与目录权限。
已提交后超时	保存 uid，继续查状态；不要重新提交来“刷新”。
额度或并发错误	等现有任务完成并核对开放平台额度，不提高本地等待值来绕过服务限额。
文件看似乱码	检查实际格式与 ZIP 内容、解压路径、UTF-8 编码；不要只改扩展名。
下载域名拒绝	核对 URL 确实来自任务响应和官方托管域，先排查配置/过期，不默认允许任意域。

官方源码与问题反馈 · PDF API

Doc2X 客户端

一键转存指南