mcp-cloudflare

Cloudflare MCP 技能

通过 MCP 与 Cloudflare 服务交互：Workers、KV、R2、D1、Hyperdrive、Observability、Builds、Audit、Container Sandbox。

基于文件的工作流（仅传递路径）

将故障排查或变更整合到多步骤工作流时，将所有证据和产物保存到磁盘，并且只在 Agent/子 Agent 之间传递路径。

建议的目录结构（位于项目内）：runs/<workflow>/active/<run_id>/

• 输入：01-input/goal.md（症状/目标）、01-input/context.json（account/worker/resource/time_range 等）
• 证据：02-analysis/observability.md、02-analysis/audit.md、02-analysis/screenshots/
• 计划：03-plans/change-plan.md（编写写入操作计划；必须写入此处并先等待确认）
• 输出：05-final/report.md（结论 + 证据链 + 工具调用摘要 + 后续步骤）
• 日志：logs/events.jsonl（每次工具调用的摘要）

权限级别（核心原则）

级别	用途	工具范围	风险控制
诊断	只读/查询/故障排查	Observability、Builds、Browser、Audit	默认入口，不执行写入操作
变更	创建/修改/删除资源	Workers Bindings（KV/R2/D1）	需要用户确认，并在执行后验证
超级管理员	最高权限	全部工具 + Container Sandbox	仅限隔离环境/测试账号

工具参考

诊断级别（只读）

Observability

工具	用途
query_worker_observability	查询日志/指标（事件、CPU、错误率）
observability_keys	查找可用字段
observability_values	探索字段值

Builds

工具	用途
workers_builds_list_builds	列出构建历史
workers_builds_get_build	获取构建详情
workers_builds_get_build_logs	获取构建日志

浏览器渲染（页面抓取）

工具	用途
get_url_html_content	获取页面 HTML
get_url_markdown	转换为 Markdown
get_url_screenshot	截取页面截图

审计日志

工具	用途
auditlogs_by_account_id	按时间范围提取变更历史

变更级别（写入操作）

账号

工具	用途
accounts_list	列出账号
set_active_account	设置当前账号

Builds（设置）

工具	用途
workers_builds_set_active_worker	⚠️ 设置当前 Worker（需要确认）

KV

工具	用途
kv_namespaces_list	列出命名空间
kv_namespace_get	获取详情
kv_namespace_create	创建（⚠️ 需要确认）
kv_namespace_update	更新（⚠️ 需要确认）
kv_namespace_delete	删除（⚠️ 需要确认）

R2

工具	用途
r2_buckets_list	列出存储桶
r2_bucket_get	获取详情
r2_bucket_create	创建（⚠️ 需要确认）
r2_bucket_delete	删除（⚠️ 需要确认）

D1

工具	用途
d1_databases_list	列出数据库
d1_database_get	获取详情
d1_database_query	执行 SQL
d1_database_create	创建（⚠️ 需要确认）
d1_database_delete	删除（⚠️ 需要确认）

Hyperdrive

工具	用途
hyperdrive_configs_list	列出配置
hyperdrive_config_get	获取详情
hyperdrive_config_create	创建（⚠️ 需要确认）
hyperdrive_config_edit	编辑（⚠️ 需要确认）
hyperdrive_config_delete	删除（⚠️ 需要确认）

Workers

工具	用途
workers_list	列出 Worker
workers_get_worker	获取 Worker 详情
workers_get_worker_code	获取源代码

超级管理员层级（容器沙箱）

工具	用途
container_initialize	初始化容器（生命周期约 10 min）
container_exec	执行命令
container_file_write	写入文件
container_file_read	读取文件
container_files_list	列出文件
container_file_delete	删除文件

容器说明：无持久化状态，生命周期较短，仅用于临时任务（运行测试／复现问题／解析数据）。

安全规则（必须遵守）

读取操作

1. 先定义范围：账户／worker／资源 ID
2. 未设置账户？先运行 accounts_list
3. 结论必须有证据链：日志／截图／审计记录

写入操作（三步流程）

1. Plan: Read current state first (list/get)
2. Confirm: Output precise change (name/ID/impact scope), await user confirmation
3. Execute: create/delete/update
4. Verify: audit logs + observability confirm no new errors

禁止的操作

• ❌ 未经确认执行创建／删除／更新操作
• ❌ 删除生产资源（除非用户明确说“删除生产环境中的 xxx”）
• ❌ 在非隔离环境中使用超级管理员权限
• ❌ 将容器沙箱用作持久化环境

操作工作流

故障排查流程（典型）

1. Clarify symptoms → worker name/time range/error type
2. query_worker_observability to pull logs/metrics
3. If build-related → workers_builds_get_build_logs
4. If page-related → get_url_screenshot to reproduce
5. Trace changes → auditlogs_by_account_id
6. Summarize: root cause + evidence + fix recommendations

资源管理流程

1. accounts_list → set_active_account
2. List resources (kv_namespaces_list / r2_buckets_list / d1_databases_list)
3. Plan changes → present to user
4. Execute after confirmation
5. Verify: audit logs + observability shows no errors

输出格式

• 语言：英文
• 结构：结论 → 关键数据／证据 → 工具调用摘要 → 后续步骤
• 写入操作：必须明确列出要执行的操作及其影响范围

输出示例：

✅ Investigation complete: worker `api-gateway` experienced 5xx spike between 18:00-18:30

Root cause: New code deployed threw TypeError when processing /v2/users
Evidence:
- Logs: 18:02 first occurrence of "Cannot read property 'id' of undefined"
- Audit: 18:00 user [email protected] deployed new version
- Metrics: error_rate jumped from 0.1% to 12%

Recommendation: Roll back to previous version, or fix /v2/users handler

错误处理

情况	操作
未设置账户	先运行 accounts_list → set_active_account
资源不存在	确认 ID／名称是否正确，并列出可用资源
权限不足	说明所需权限，并建议检查 API token 的范围
可观测性查询过长	拆分为较短的时间范围，并提出更具体的问题

场景示例

请参阅 scenarios.md，了解 20 个真实开发场景。