MCP 接入指南

DocPurify MCP Server 能让 Claude Desktop、Cursor、Codex 等 MCP Host 直接调用文档处理能力。你只需创建一把 MCP Key，把下面配置贴进客户端，就能开始使用。

注意
现在 MCP 已支持通过 upload_document_file 直接上传本地文件。只有在你已经有 DocPurify file_id 时，才需要使用 submit_document_for_processing。

MCP Host
  -> DocPurify MCP stdio server
  -> DocPurify 服务
  -> 文档处理任务与结果

1. 5 分钟快速接入

你需要准备两项信息：

在 MCP Host 中加入下面的 Server 配置，通常只需要替换 DOCPURIFY_MCP_KEY。

{
  "mcpServers": {
    "docpurify": {
      "command": "npx",
      "args": ["-y", "@docpurify/mcp-server"],
      "env": {
        "DOCPURIFY_MCP_KEY": "dp_your_mcp_key"
      }
    }
  }
}

保存配置后重启 MCP Host。客户端完成 initialize 后，会通过 tools/list 发现 DocPurify 提供的工具。

2. 当前支持的能力

DocPurify 目前只开放了 Tools，Resources 和 Prompts 暂未开放。

典型使用场景：

• 让 AI 查看工作区状态、积分和最近任务。
• 让 MCP Host 直接上传本地文件并开始处理。
• 根据已上传文件的 file_id 提交处理任务。
• 轮询任务状态，直到 result_ready = true。
• 任务完成后读取 Markdown 结果和下载链接。
• 取消仍在排队或处理中的任务。

3. 协议与传输

DocPurify MCP Server 使用标准 MCP stdio 传输。MCP Host 启动本地进程后，通过 stdin/stdout 交换 JSON-RPC 消息。

安全提醒
stdio 模式下，请勿将 Key 写入 prompt 或 tool description，只通过 MCP Host 的 env 配置传入。

4. 创建和保存 API Key

API Key 在 DocPurify 网页控制台的 MCP 页面 管理：

1. 登录 DocPurify。
2. 从主导航进入 MCP 页面。
3. 创建 API Key。
4. 立即保存生成的 Key。离开页面后，系统不会再展示完整 Key。
5. 把 Key 写入 MCP Host 配置中的 DOCPURIFY_MCP_KEY。

当前规则：

• 一个账号同一时间只保留一个有效 MCP API Key。
• 刷新 Key 会立刻签发新 Key，旧 Key 同时作废。
• 撤销 Key 后，所有使用该 Key 的 MCP 调用都会失败。
• 网页登录态仅用于管理 Key，不能代替 MCP 请求认证。

5. 客户端配置示例

Claude Desktop、Cursor、Codex 等客户端配置文件路径不同，但核心字段都是 command、args、env。

{
  "mcpServers": {
    "docpurify": {
      "command": "npx",
      "args": ["-y", "@docpurify/mcp-server"],
      "env": {
        "DOCPURIFY_MCP_KEY": "dp_your_mcp_key",
        "DOCPURIFY_MCP_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

配置建议：

• DOCPURIFY_MCP_TIMEOUT_SECONDS 可选，默认 30 秒。
• 如果客户端所在机器没有 Node.js，请先安装 Node.js 18 或更高版本。
• 配置完成后完全重启客户端，确保 MCP Server 重新加载环境变量。
• 如果客户端支持“Reload MCP servers”，也可以直接刷新服务器列表。

6. 推荐调用顺序

第一次联调建议按这个顺序来：

1. 在 Web 控制台创建或确认当前有效的 Key。
2. 启动 MCP Host，确认能发现 docpurify Server。
3. 调用 get_workspace_overview，确认账号上下文、积分状态和最近任务。
4. 如果你有本地文件路径，调用 upload_document_file。
5. 只有在高级流程里已经存在有效 file_id 时，才使用 submit_document_for_processing。
6. 使用 get_document_job 轮询进度。
7. 只有当 result_ready = true 时，才调用 get_document_result。
8. 如需停止任务，先查询当前状态，再调用 cancel_document_job。
9. 如需清理数据，只对终态任务调用 delete_document_job。

7. Tools 参考

7.1 Tool 参数表

get_workspace_overview

Description: 获取工作区摘要，包括积分、存储、近期任务、提醒和推荐动作。

upload_document_file

Description: 面向终端用户的默认入口。上传本地文件并立即开始处理。

高级/内部字段虽然支持，但普通用户通常不需要：content_page_count、toc_page_count、toc_has_annotations、image_count、text_validation、image_validation、output_format。

submit_document_for_processing

Description: 面向已经持有有效 file_id 的高级流程。

对普通用户，不建议优先理解或使用这个 tool。

list_document_jobs

Description: 列出当前账号近期任务，可按状态筛选。

get_document_job

Description: 读取单个任务详情，包括状态、进度、当前阶段、失败原因和下一步建议。

get_document_result

Description: 读取已完成任务的 Markdown、产物和下载链接。

cancel_document_job

Description: 取消未终态任务。

delete_document_job

Description: 删除终态任务并回收相关存储资源。

参数含义：

• file_path
  MCP Host 所在机器上的本地文件路径。MCP Server 会读取这个文件并帮你上传。

• file_id
  DocPurify 已上传文件的 ID。它用于 submit_document_for_processing。

• document_job_id
  与处理任务关联。上传或提交后请立即保存返回的 document_job_id，后续查询、取结果、取消和删除都会用到它。

• processing_options
  用于传递处理选项。没有特殊需求时可以省略，服务端会使用默认配置。

• status_filter
  用于筛选任务状态。建议先用 list_document_jobs 或 get_document_job 看看实际状态值，再决定过滤条件。

7.2 processing_options 参数示例

最简本地上传：

{
  "file_path": "/absolute/path/to/demo.pdf",
  "processing_options": {
    "selected_options": ["base_processing"]
  }
}

全量 AI 增强处理：

{
  "file_path": "/absolute/path/to/demo.pdf",
  "processing_options": {
    "selected_options": [
      "base_processing",
      "toc_validation",
      "image_validation",
      "content_validation"
    ],
    "language": "zh",
    "toc_pages": "2-3",
    "content_pages": "4-20",
    "toc_has_annotations": true
  }
}

已有 file_id 且显式传页数：

{
  "file_id": "file_123",
  "processing_options": {
    "selected_options": [
      "base_processing",
      "content_validation"
    ],
    "language": "en",
    "content_page_count": 18,
    "toc_page_count": 2
  }
}

纯文本或 Markdown 文件：

{
  "file_path": "/absolute/path/to/notes.md",
  "processing_options": {
    "selected_options": ["content_validation"],
    "language": "auto"
  }
}

说明：

• 优先把 selected_options 当作主要功能开关。
• text_validation、image_validation 属于兼容布尔参数，但长期更推荐直接写 selected_options。
• 对 txt 和 md，建议显式包含 content_validation。

7.3 返回结构

MCP 工具调用统一返回 text content，内容是 DocPurify 服务端响应的 JSON 字符串。

成功响应：

{
  "success": true,
  "message": "ok",
  "data": {}
}

业务失败会以 isError: true 返回给 MCP Host，正文中通常包含可处理的错误码：

{
  "detail": {
    "code": "DOCUMENT_JOB_NOT_FOUND",
    "message": "document_job_id 不存在"
  }
}

8. 调用示例

给 AI 的自然语言指令可以非常简短：

请先查看我的 DocPurify 工作区状态。

如果希望 MCP Host 直接上传本地文件：

请用 DocPurify 上传本地文件 /absolute/path/to/demo.pdf，然后持续查询任务，直到 Markdown 结果准备完成。

如果有已上传文件：

请把 file_id 为 file_123 的文档提交处理，然后每 30 秒查询一次进度，完成后读取 Markdown 结果。

查询结果：

请查看 document_job_id 为 job_123 的处理状态。如果已经完成，读取结果并总结主要内容。

9. 关键字段

get_workspace_overview 常用返回字段：

• can_start_new_job
• active_jobs
• recent_jobs
• credit_balance
• storage_summary
• alerts
• recommended_next_actions

get_document_job 常用返回字段：

• status
• progress
• current_stage
• failure_reason
• user_facing_explanation
• suggested_actions
• retryable
• result_ready

get_document_result 常用返回字段：

• primary_markdown
• artifacts
• download_urls
• ttl_seconds
• missing_artifacts

10. 安全与治理

DocPurify MCP 调用会绑定到 API Key 对应的用户账号。服务端会检查资源归属，避免一个 Key 访问其他账号的文件或任务。

安全建议：

• 不要把 API Key 写进 prompt、tool description、截图或共享文档。
• 不要把下载链接当作永久地址长期缓存。
• 为不同环境使用不同账号或测试租户，避免生产数据混入调试流程。
• 当设备停用、脚本下线或怀疑泄露时，立即撤销或刷新 Key。

11. 限制、分页与兼容性

当前限制：

• 远程 Streamable HTTP MCP 端点暂未开放。
• Resources 和 Prompts 暂未开放。
• MCP 不能直接上传本地原始文件。
• 同一账号不能长期维护多把有效 MCP Key。

分页与过滤：

• list_document_jobs 默认 limit = 10。
• limit 最大值为 100。
• 当前列表接口不返回游标；如需翻页，请关注后续版本的分页字段更新。

幂等性：

• get_workspace_overview、list_document_jobs、get_document_job、get_document_result 是读操作。
• upload_document_file、submit_document_for_processing、cancel_document_job、delete_document_job 会改变任务状态。重试前应先调用 get_document_job 确认当前状态。
• 当前版本不提供外部幂等键。

版本兼容：

• 新增工具或新增返回字段视为向后兼容。
• 删除工具、重命名字段、改变必填参数会提前在文档中说明。
• 客户端应忽略未知返回字段，避免因新增字段导致解析失败。

12. 错误处理与排查

如需绕过 MCP Host 进行连通性排查，可以用下面的命令直接验证 Key 和账号上下文：

curl -X POST "https://api.docpurify.com/mcp/tools/get_workspace_overview" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOCPURIFY_MCP_KEY" \
  -d '{}'

13. 给 AI / Agent 的建议策略

建议把下面规则写入 Agent 的工具调用策略：

• 会话开始时先调用 get_workspace_overview。
• 用户给出本地路径时，优先使用 upload_document_file。
• 用户已经有 DocPurify file_id 时，再使用 submit_document_for_processing。
• 写操作前先检查当前状态，避免重复提交、重复取消或误删。
• 拿到 document_job_id 后优先轮询 get_document_job。
• 只有 result_ready = true 时才调用 get_document_result。
• 如果存在 failure_reason，直接展示给用户，不要自行猜测失败原因。
• 删除任务前确认其状态为 completed、failed 或 cancelled。

14. FAQ

我的客户端看不到工具，怎么办？

先确认客户端已加载 docpurify MCP Server。再检查 command、args、Node.js 版本和环境变量。能看到 Server 但看不到工具时，查看客户端的 MCP 日志。

可以把本地文件路径传给 submit_document_for_processing 吗？

不可以。本地路径请使用 upload_document_file；submit_document_for_processing 需要的是已有的 DocPurify file_id。

下载链接可以长期保存吗？

不建议。结果下载链接有有效期，请读取 ttl_seconds，过期后重新调用 get_document_result 获取新链接。

什么时候需要刷新 API Key？

当 Key 泄露、设备停用、集成迁移或团队成员离开时，建议刷新或撤销 Key。