Cloudflare Docs MCP

Cloudflare Docs MCP（注：MCP在此处可能代表某个特定的模块、组件或概念，但根据上下文无法确定具体含义，因此直接保留原样）

Cloudflare Docs MCP worker 是一个代理研究平台，用于协调工具的使用， 向量搜索，以及持久对象的长生命周期会话，以回答开发者关于 Cloudflare。该工作程序同时提供了REST和WebSocket接口，以便第一方和 第三方客户端可以与同一个代理运行时进行协作。

架构概述

• ChatSessionActor（聊天会话行为者/聊天会话参与者） – 有状态的持久对象，用于存储对话历史记录，

协调澄清、规划、工具执行和综合工作，并发布（结果/指令等，具体根据上下文确定） WebSocket 更新。

• 可行性代理行为者 – 排队处理长时间运行的可行性研究任务并记录

D1方面的进展。

• 代码摄入行为体（或代码摄入器） – 接受代码或文档以进行处理，并将其分发出去

进入队列以进行异步处理。

• 数据层 – D1存储经过筛选的知识、可行性作业记录以及分析结果

人工制品。Vectorize 在规划过程中维护所引用的语义索引。

• 队列与沙盒 – Cloudflare Queues 协调后台处理，并且

沙箱持久对象在工具计划请求时安全地执行代码。

一个OpenAPI 3.1规范是直接生成的 src/index.ts相同的条目 同时，该点还注册了一个 WebSocket 升级处理器以 /api/chat/ws 用于交互式 会议/会话。

API概述

所有经过身份验证的路由都需要 Authorization 工人检查的内部标题 authMiddleware.

聊天终端示例

curl -X POST https:///api/chat \
  -H "Authorization: Bearer " \
  -H "content-type: application/json" \
  -d '{
        "query": "How do I deploy a Hono API to Cloudflare Workers?",
        "sessionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
      }'

成功的回应遵循由……所规定的结构 ChatResponseSchema：

{
  "sessionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "response": "Deploy the Hono app by running `npx wrangler deploy` after configuring wrangler.toml.",
  "plan": {
    "steps": [
      "Check curated knowledge base for Hono guidance.",
      "Search GitHub for Workers examples."
    ],
    "toolCalls": [
      { "tool": "cloudflare_docs", "args": { "query": "Hono deployment" } }
    ]
  },
  "tool_results": [
    {
      "tool": "cloudflare_docs",
      "result": { "hits": 3 }
    }
  ],
  "clarification": { "needed": false }
}

如果代理需要更多信息，响应中将包含一个澄清对象：

{
  "sessionId": "...",
  "response": "Could you clarify which Cloudflare product you plan to deploy to?",
  "clarification": {
    "needed": true,
    "question": "Which Cloudflare product are you targeting?"
  }
}

WebSocket 会话

要开始一个流式会话，请发送一个WebSocket升级请求：

curl -i -N -H "Authorization: Bearer " \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  https:///api/chat/ws

握手响应包括 x-session-id发送以下形式的JSON消息： {"query": "..."} 通过套接字。代理流式传输结构化更新，例如 status， plan_created， tool_start， tool_end，和 final_response （直到）事件发生 会议结束。

可行性工作

curl -X POST https:///api/feasibility \
  -H "Authorization: Bearer " \
  -H "content-type: application/json" \
  -d '{ "prompt": "Assess migrating our Express API to Cloudflare Workers" }'

工作者返回带有 UUID 支持的作业标识符：

{
  "jobId": "cfdc2172-8c15-4ff5-9e1f-9e5b309d75ba",
  "status": "QUEUED",
  "message": "Feasibility research job has been queued."
}

使用 /api/feasibility/status/:id 轮询以获取更新， /api/jobs 探索工作机会 历史，以及 /api/jobs/:id/packet 下载最终报告及附件 作业完成后进行仓库分析。

知识摄入

curl -X POST https:///api/ingest \
  -H "Authorization: Bearer " \
  -H "content-type: application/json" \
  -d '{
        "url": "https://github.com/cloudflare/workers-sdk/blob/main/examples/hono-app.ts",
        "metadata": { "language": "TypeScript", "framework": "Hono" }
      }'

该请求已被放入队列以进行异步处理，响应中包含一个跟踪标识 标识符：

{
  "documentId": "61a94f6e-6d77-4e58-9151-04a6cc0fc4ad",
  "status": "queued",
  "message": "Ingestion request received."
}

本地运行

npm install
npm run dev

wrangler dev 本地持久对象、队列和沙箱绑定的条款规定，以便 代理工作流程可以实现端到端的演练。

数据库迁移

# Apply migrations using a local D1 instance
npm run migrate:local

# Apply migrations to the remote production database
npm run migrate:remote

测试与代码规范检查

npm run check
npm test

环境与绑定

诸如……之类的秘密 WORKER_API_KEY， GITHUB_TOKEN， CLOUDFLARE_ACCOUNT_ID，和 CLOUDFLARE_API_TOKEN 被配置为 wrangler secret put。

故障排除

OpenAPI规范可访问地址为 /openapi.json 并导入到客户端 SDK生成器或文档工具。