文档MCP接口

文档 MCP。客户端用 Streamable HTTP 连上后，可以列已发布目录、平台、教程和接口详情。不会代发上游请求。

不校验 MCP KEY。关闭时返回 HTTP 403，正文 {"error":"MCP is not enabled"}。启用时放行。

地址

环境	方法	路径
线上	POST	`https://efwef.xyz/api/docs/mcp`

Content-Type: application/json。请求体上限 1 MiB。同一客户端 IP 每分钟最多 60 次，超出返回 HTTP 429，正文 {"error":"too many requests"}。

GET 返回 HTTP 405，正文 {"error":"MCP endpoint accepts POST only"}。本服务没有 SSE。

配置里不用填写 MCP KEY：

{
  "mcpServers": {
    "docs-mcp": {
      "url": "https://efwef.xyz/api/docs/mcp"
    }
  }
}

单条 JSON-RPC 2.0，无状态。服务名 docs-mcp。

握手：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}

成功时 HTTP 200，result.serverInfo.name 为 docs-mcp。客户端没带 protocolVersion 时回退 2025-06-18；带了则原样回显。

method	说明
`initialize`	握手，返回能力与说明
`notifications/initialized`、`initialized`	通知。没有 `id` 时 HTTP 202，无正文
`ping`	`result` 为空对象
`tools/list`	返回下面五个工具
`tools/call`	`params.name` + `params.arguments`

未知 method 且带 id 时 HTTP 200，error.code 为 -32601。jsonrpc 不是 2.0 时 error.code 为 -32600。

工具结果在 result.content[0].text，内容是 JSON 字符串或一句错误说明。业务错误（找不到、参数不对）HTTP 仍是 200，result.isError 为 true。成功时不带 isError。

语言参数 locale 只接受 zh-CN（默认）和 en-US，其它值按 zh-CN。列表的 limit 默认 20，最大 50；offset 小于 0 时按 0。

目录节点。

参数：locale、limit、offset。均可省略。

items[] 字段：id、parentId、type、title、slug、sortOrder、published。另有 total、count、offset、has_more。

已发布 API 平台。

参数：locale、limit、offset。

items[] 字段：platform、title、isDetailed、yamlBytes。另有 total、count、offset、has_more。

按 slug 取一篇已发布教程。

参数：slug（必填）、locale。

成功字段：title、slug、markdown、truncated、publishedAt。正文超过 20 KiB 时截断，truncated 为 true。

草稿、目录里不可达、或当前 Host 不可见时，isError=true，文本含 tutorial not found。

某个已发布平台下的 HTTP 操作。

参数：platform（必填，如 v1）、locale、limit、offset。

成功字段：platform、title，以及 items[]：id、method、path、summary、tag、deprecated。另有 total、count、offset、has_more。id 就是下一步的 opId。

平台未发布时 isError=true，文本含 platform not found。

一条已发布操作的参数、请求体、响应和示例。不执行该接口。

参数：platform、opId（都必填）、locale。

成功正文是 OperationView，主要字段：id、method、path、summary、description、deprecated、tag、servers、baseUrl、parameters、requestBody、responses。

找不到时 isError=true，文本含 operation not found。

不要编造未出现在列表里的 path 或 operationId。