qcc-document-mcp

v0.1.3

Published

a month ago

Local stdio MCP server package for QCC capabilities, including IDP document parsing.

0High
0Medium
0Low

sunhh

mcp_document

企查查文档解析 MCP 服务 —— 帮助 AI Agent 读取本地文件或 HTTP(S) 文档 URL，并返回结构稳定的解析任务状态与 Markdown 结果

GitLab 项目名为 mcp_document；发布到 npm 的包名及 npx 可执行命令仍为 qcc-document-mcp。

项目简介

qcc-document-mcp 是面向 AI Agent 的本地 stdio MCP 服务，用于接入企查查 document 文档解析能力。配置到支持 MCP 的客户端后，Agent 可以提交一个本地文件路径或一个 HTTP(S) 文档 URL，创建解析任务，并在任务完成后读取 Markdown 格式的解析结果。

核心能力：

本地文件解析：支持提交本地文档路径，适合让 Agent 处理用户电脑上的 PDF、Word 等文件。
URL 文档解析：支持提交 http:// 或 https:// 文档 URL。
异步任务查询：默认先返回 task_id，再用 get_parse_result 查询状态和结果。
同步等待模式：wait: true 时会尝试等待解析完成，完成后可直接返回 details[].result_md。
Agent 友好输出：固定返回 task_id、status、message 等字段，便于 Agent 判断下一步动作。

隐私与数据上传说明

使用 file_path 解析本地文件时，本服务会读取该路径对应的本地文件，并将文件内容上传到企查查文档解析网关以创建解析任务。请仅提交你有权处理且允许上传到该服务的文件；不要提交包含密码、密钥、商业机密、个人敏感信息或受合规限制的数据。

使用 file_url 解析远程文档时，本服务会将该 URL 提交给企查查文档解析网关。请避免在 URL query 中包含访问令牌、签名参数或其他敏感信息。

为什么选择 qcc-document-mcp？

为 AI Agent 原生设计

MCP 工具参数自描述，Agent 可通过工具 schema 理解输入要求。
解析结果以稳定 JSON envelope 返回，processing、success、failed 状态清晰。
成功结果使用 Markdown 字段 details[].result_md，便于 Agent 继续总结、抽取或比对内容。

适合处理用户本地文档

Agent 只需传入本地文件路径，不需要用户手动上传文件内容。
相对路径会按 MCP 服务运行目录解析；不确定时建议使用绝对路径。
本地文件会通过企查查网关上传并创建解析任务，用户侧不用关心上传链路细节。

安全可控

访问凭证通过环境变量配置，不需要写入代码或对话内容。
服务会规范化 Authorization 值：可传入完整 Bearer <token>，也可只传入 token。
工具输入不暴露 file_name、file_type、file_size、上传 URL、计费字段或回调配置。

快速开始

1. 环境准备

| 依赖 | 要求 | | :--- | :--- | | Node.js | >= 18.14.1 | | npm / npx | 随 Node.js 安装 | | 企查查授权凭证 | 设置为 QCC_DOCUMENT_AUTHORIZATION |

2. 配置到 MCP 客户端

推荐使用 npx -y qcc-document-mcp，无需全局安装。

{
  "mcpServers": {
    "qcc-document-mcp": {
      "command": "npx",
      "args": ["-y", "qcc-document-mcp"],
      "env": {
        "QCC_DOCUMENT_AUTHORIZATION": "Bearer YOUR_API_KEY"
      }
    }
  }
}

如需指定网关地址或超时时间，可追加环境变量：

{
  "mcpServers": {
    "qcc-document-mcp": {
      "command": "npx",
      "args": ["-y", "qcc-document-mcp"],
      "env": {
        "QCC_DOCUMENT_AUTHORIZATION": "Bearer YOUR_API_KEY",
        "QCC_DOCUMENT_URL": "https://agent.qcc.com/mcp/",
        "QCC_DOCUMENT_TIMEOUT_SECONDS": "300"
      }
    }
  }
}

3. 在 Agent 中使用

配置完成后，可以直接让 Agent 调用工具，例如：

请使用 qcc-document-mcp 解析 C:\Users\me\Documents\sample.pdf，并总结主要内容。

或：

请解析这个文档 URL：https://files.example.com/sample.pdf

如果返回 status: "processing"，继续让 Agent 用返回的 task_id 查询：

请查询 task_id 为 <task_id> 的文档解析结果。

工具说明

`parse_document`

提交一个本地文件路径或一个 HTTP(S) 文档 URL，创建文档解析任务。

输入示例：本地文件异步提交

{
  "file_path": "C:\\Users\\me\\Documents\\sample.pdf"
}

输入示例：本地文件同步等待

{
  "file_path": "C:\\Users\\me\\Documents\\sample.pdf",
  "wait": true
}

输入示例：URL 文档

{
  "file_url": "https://files.example.com/sample.pdf"
}

参数说明：

| 参数 | 类型 | 必填 | 说明 | | :--- | :--- | :---: | :--- | | file_path | string | 二选一 | 本地文件路径，可使用绝对路径或相对路径。文件内容会上传到企查查文档解析网关；不要传 URL、目录、通配符、base64、文件流或文件内容。 | | file_url | string | 二选一 | 文档 URL，必须以 http:// 或 https:// 开头。不要传本地文件路径、base64、文件流或文件内容。 | | wait | boolean | 否 | 是否尝试等待解析完成。默认 false。 |

使用规则：

file_path 和 file_url 必须且只能提供一个。
本地文件路径建议优先使用绝对路径，避免 MCP 客户端运行目录差异导致找不到文件。
file_url 只做 HTTP(S) URL 语法校验；文件类型、大小、ZIP、页数等业务校验以企查查网关和 document 服务结果为准。
wait 省略或为 false 时通常返回任务受理状态；wait: true 时如果已完成，可能直接返回 Markdown 结果。
当前版本暂不支持 start_page_id、end_page_id 指定页码范围；这两个字段已在工具 schema 中隐藏，传入会被入口校验拒绝。
工具不支持 file_name、file_type、file_size、callback_url、check_params、full_json、title_tree 等参数。

`get_parse_result`

使用 parse_document 返回的 task_id 查询任务状态和解析结果。

输入示例：

{
  "task_id": "qcc-task-id"
}

参数说明：

| 参数 | 类型 | 必填 | 说明 | | :--- | :--- | :---: | :--- | | task_id | string | 是 | parse_document 返回的任务 ID。请原样传入，不要截断或改写。 |

返回结果

两个工具都会返回结构稳定的 JSON 文本，常见状态如下：

异步提交示例：

{
  "task_id": "qcc-task-id",
  "status": "processing",
  "message": "任务已提交，解析处理中，请调用 get_parse_result 工具获取状态和结果。",
  "next_action": "get_parse_result"
}

成功结果中通常包含 Markdown 解析内容：

{
  "task_id": "qcc-task-id",
  "status": "success",
  "message": "解析成功",
  "details": [
    {
      "result_md": "# 文档标题\n\n解析后的 Markdown 内容..."
    }
  ]
}

失败结果示例：

{
  "task_id": null,
  "status": "failed",
  "message": "请求参数非法，请提供 file_path 或 file_url。",
  "error": {
    "code": 100208,
    "description": "请求参数非法",
    "explanation": "请提供 file_path 或 file_url。"
  }
}

配置说明

运行时配置通过 MCP 客户端的环境变量传入。

| 环境变量 | 必填 | 默认值 | 说明 | | :--- | :---: | :--- | :--- | | QCC_DOCUMENT_AUTHORIZATION | 是 | 无 | 企查查网关访问凭证。可填写 Bearer <token>，也可只填写 token。 | | QCC_DOCUMENT_URL | 否 | https://agent.qcc.com/mcp/ | 企查查 MCP / document 网关地址。通常无需修改。 | | QCC_DOCUMENT_TIMEOUT_SECONDS | 否 | 300 | 请求超时时间，单位为秒，必须为正整数。 |

安全提示：

不要把真实 Authorization 写入公开仓库、README、截图或对话记录。
建议将凭证放在 MCP 客户端的环境变量、密钥配置或本机私有配置中。
仅提交你有权处理并允许上传到企查查文档解析网关的文件或 URL。
排查问题时只记录任务状态、错误码、文件类型、数量、结果长度等摘要信息，不要复制完整文档正文、完整 URL query、上传 URL 或签名参数。

常见问题

提示 `QCC_DOCUMENT_AUTHORIZATION is required`

说明 MCP 客户端没有把 QCC_DOCUMENT_AUTHORIZATION 传给服务。请检查 MCP 配置中的 env 字段，保存后重启客户端。

返回 `processing` 后没有正文

这是正常的异步任务状态。请使用返回的 task_id 调用 get_parse_result，直到状态变为 success 或 failed。

本地文件路径找不到

相对路径会按 MCP 服务运行目录解析，不一定是当前对话或文件所在目录。建议传入绝对路径。

URL 文档提交失败

请确认 URL 以 http:// 或 https:// 开头，并且服务端可访问该 URL。文件类型、大小、ZIP、页数等校验以企查查网关和 document 服务返回为准。

什么时候使用 `wait: true`

文档较小、希望一次调用直接拿到结果时可以使用 wait: true。如果任务仍未完成，仍会返回 processing，继续用 get_parse_result 查询即可。

许可证

本项目基于 Apache License 2.0 发布，详见 LICENSE。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme