MCP 接入与工具

把 Agent 连接到 Vdoc，让它查询已发布的 OpenAPI 和 Markdown 文档，或提交草稿等待人工审核。首次接入可以直接跟随连接 Agent，再读取第一份文档。

@vdoc/mcp 是 stdio 适配器，把 tools/list 和 tools/call 转发到后端 /api/v1/open/mcp；文档存储和业务逻辑由 Backend 负责。

使用前准备

Vdoc backend 已部署，/api/v1/open/health 成功。
Admin 中已经创建 MCP Token。
目标 Agent runtime 支持 MCP stdio server 配置。
不要把原始 MCP Token、JWT、DB password、storage secret 或 Authorization header 值写进仓库、截图、日志、README 或 issue。

Agent 运行的机器还需安装 Node.js 20 或更新版本、npm 和 Git。尚未启动 Vdoc 时，先按 Docker Compose 部署步骤完成初始化和管理员设置。第一次查询需要一份已发布文档；demo 数据和工程发布检查可以后续再做。

安装方式

当前 @vdoc/mcp 尚未发布到 npm registry。请直接从官方 GitHub 仓库运行或安装：

npx --yes github:ChnMig/Vdoc-mcp#e148633a6e56ec233dcbb9be6e0108eabec93b61
# 或全局安装 GitHub 版本
npm install -g git+https://github.com/ChnMig/Vdoc-mcp.git#e148633a6e56ec233dcbb9be6e0108eabec93b61

一次性使用时，推荐在 Agent MCP config 中通过固定 commit 的 npx 调用，不要把 token 放在 args。上面的 40 位 commit 必须和已审核发布包 workspace.lock.json 的 Vdoc-mcp 项一致；不要删掉 fragment 或改成可移动 branch。

VDOC_MCP_TOKEN 是 shell 或 Agent 配置中的环境变量，不是 package CLI argument。不要把原始 token 放进 npx、npm 或 adapter 的 args。手工排查前运行 set +x 关闭 xtrace，并确保凭据不进入 shell history、日志或截图。

本地开发或 package smoke：

cd Vdoc-mcp
npm ci
npm test
# 先通过私密 shell 环境或 Agent secret env 设置 VDOC_MCP_TOKEN。
VDOC_BASE_URL="http://127.0.0.1:8080" npm start

stdout 保留给 MCP protocol，普通诊断看 stderr。

环境变量

Variable	是否必填	说明
`VDOC_BASE_URL`	当未设置 `VDOC_MCP_URL` 时必填	Vdoc backend origin，adapter 会追加 `/api/v1/open/mcp`。
`VDOC_MCP_URL`	当未设置 `VDOC_BASE_URL` 时必填	完整 Vdoc MCP endpoint URL，设置后覆盖 `VDOC_BASE_URL`。
`VDOC_MCP_TOKEN`	必填	Admin 中创建的 MCP Token，只放在 Agent config 或 secret storage。
`VDOC_MCP_TIMEOUT_MS`	可选	HTTP timeout，单位毫秒，默认 `180000`，范围 `1`–`180000`；agent 宿主的调用超时也需允许此时长。

完整 Compose 本机部署时，VDOC_BASE_URL 通常是 http://127.0.0.1:8080。远程部署时，改成 Agent 所在机器能访问的 backend 域名。

Agent 配置示例

json

{
  "mcpServers": {
    "vdoc": {
      "command": "npx",
      "args": [
        "--yes",
        "github:ChnMig/Vdoc-mcp#e148633a6e56ec233dcbb9be6e0108eabec93b61"
      ],
      "env": {
        "VDOC_BASE_URL": "https://your-vdoc.example.test",
        "VDOC_MCP_TOKEN": "REPLACE_WITH_LOCAL_VDOC_MCP_TOKEN"
      }
    }
  }
}

如果你已经知道完整 MCP endpoint，可以改用：

json

{
  "env": {
    "VDOC_MCP_URL": "https://your-vdoc.example.test/api/v1/open/mcp",
    "VDOC_MCP_TOKEN": "REPLACE_WITH_LOCAL_VDOC_MCP_TOKEN",
    "VDOC_MCP_TIMEOUT_MS": "180000"
  }
}

可用工具范围

后端是 tool definitions 的事实来源。Adapter 每次运行时调用 Vdoc tools/list，所以 schemas 会跟已部署后端保持一致。

v0.2 read tools 覆盖：

projects
documents
API versions
Markdown versions
endpoint detail
API diffs
Markdown docs
change summaries

list_documents 会按 token scope 过滤结果：只有 api:read 时仅返回 OpenAPI，只有 doc:read 时仅返回 Markdown，同时具备两者时返回两类文档。API read tools 也会校验目标是 OpenAPI，Markdown read tools 会校验目标是 Markdown，不能用一种 read scope 绕过另一种。

v0.2 draft tools 覆盖 OpenAPI 和 Markdown Draft 的创建、更新、查看和提交。规范工具清单如下（必须与后端 tools/list 一致）：

list_projects
list_documents
list_document_branches
list_api_endpoints
list_api_versions
list_doc_versions
get_latest_schema
get_endpoint_detail
compare_api_versions
get_change_summary
create_api_version_draft
update_api_version_draft
submit_api_version_draft
get_api_version_draft
get_latest_doc
compare_doc_versions
create_doc_draft
update_doc_draft
submit_doc_draft
get_doc_draft
get_schema_version
get_doc_version

当前源码新增 list_document_branches，可查询分支 ID、名称、默认及保护状态，尚未发布版本的分支也能查询；list_api_endpoints 查询指定版本的接口 ID，可用 method 和精确 OpenAPI path 筛选。先取得这些 ID，再查询详情或创建首份草稿。分支查询要求对应文档类型的 read scope。旧发布包可能尚无这两个工具，请检查实际工具列表，并配套升级 Backend 与 Skill。

当前后端的 get_endpoint_detail 在 normalized_operation.securitySchemes 中返回接口实际使用的鉴权方案定义；同名方案的 Header、位置或类型变化会出现在版本差异中。OpenAPI 3.1 的 Schema $ref 同级约束会保留，Operation 参数按 name + in 覆盖 Path 参数。升级后读取历史接口或比较时会从原始文档更新旧解析结果，原版本和接口 ID 保持不变。旧部署应先升级 Backend。

实际工具列表以当前 backend tools/list 返回为准。v0.2 不暴露 direct publish tools。

Agent 行为规则

回答 endpoint fields、response properties、enum values、auth schemes 或 Markdown 原文前，先查 Vdoc。
优先使用 stable ID 和 relative_path，不要依赖显示名称。
把 published Version 视为不可变事实。
不要说 Draft 已发布，除非 Admin 审核后已经生成 Version。
tool call 失败时，遮盖 secret 后报告 envelope code、status、message 和 trace_id。
不要把原始 MCP Token、JWT、DB password、storage secret 或 Authorization header 值写进仓库、截图、日志、README 或 issue。

如何验证

Agent MCP server vdoc 能启动。
tools/list 成功返回 Vdoc tool schemas。
至少一个 read-only tool call 成功。
token 没有出现在 process args、日志、文档或截图中。
Agent 在依赖接口或文档事实的回答中说明事实来自 Vdoc 查询结果。

v0.2：明确分支和历史版本

get_latest_doc、get_latest_schema 必须传入 branch_id，不会跨分支自动选择。先用 list_document_branches 解析分支名称。
读取指定历史版本全文：Markdown 使用 get_doc_version，OpenAPI 使用 get_schema_version，参数均为 project_id、document_id、version_id。返回 version 与 content，请核对并引用实际版本。
get_api_version_draft 保留原有元数据并增加 content.content 原始正文，revision 与正文来自同一快照，可用于后续 expected_revision 更新。
未声明的参数会返回 INVALID_ARGUMENT。旧客户端调用最新内容工具时需补上分支，不能传 version_id 期待读取历史内容。

首次接入可使用 Codex／Cursor 配置步骤。

MCP 接入与工具 ​

使用前准备 ​

安装方式 ​

环境变量 ​

Agent 配置示例 ​

可用工具范围 ​

Agent 行为规则 ​

如何验证 ​

v0.2：明确分支和历史版本 ​