mcp-cloudflare

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare MCP Skill

Interact with Cloudflare services via MCP: Workers, KV, R2, D1, Hyperdrive, Observability, Builds, Audit, Container Sandbox.

通过MCP与Cloudflare服务交互：Workers、KV、R2、D1、Hyperdrive、可观测性、构建、审计、容器沙箱。

File-based Pipeline (Pass Paths Only)

基于文件的流水线（仅传递路径）

When integrating troubleshooting/changes into multi-step workflows, persist all evidence and artifacts to disk, passing only paths between agents/sub-agents.

Recommended directory structure (within project):

runs/<workflow>/active/<run_id>/

Input:
```
01-input/goal.md
```
(symptoms/objectives),
```
01-input/context.json
```
(account/worker/resource/time_range, etc.)

Evidence:

02-analysis/observability.md

02-analysis/audit.md

02-analysis/screenshots/

Plan:
```
03-plans/change-plan.md
```
(write operation plan; must write here and await confirmation first)
Output:
```
05-final/report.md
```
(conclusion + evidence chain + tool call summary + next steps)
Logs:
```
logs/events.jsonl
```
(summary of each tool call)

在将故障排查/变更集成到多步骤工作流时，需将所有证据和工件持久化到磁盘，代理/子代理之间仅传递路径。

推荐的目录结构（项目内）：

runs/<workflow>/active/<run_id>/

输入：
```
01-input/goal.md
```
（症状/目标）、
```
01-input/context.json
```
（账户/Worker/资源/时间范围等）

证据：

02-analysis/observability.md

、

02-analysis/audit.md

、

02-analysis/screenshots/

计划：
```
03-plans/change-plan.md
```
（写入操作计划；必须先在此处编写并等待确认）
输出：
```
05-final/report.md
```
（结论 + 证据链 + 工具调用摘要 + 后续步骤）
日志：
```
logs/events.jsonl
```
（每个工具调用的摘要）

Permission Tiers (Core Principles)

权限层级（核心原则）

Tier	Purpose	Tool Scope	Risk Control
Diagnose	Read-only/query/troubleshoot	Observability, Builds, Browser, Audit	Default entry point, no write operations
Change	Create/modify/delete resources	Workers Bindings (KV/R2/D1)	Requires user confirmation, post-execution verification
Super Admin	Highest privileges	All + Container Sandbox	Only in isolated environments/test accounts

层级	用途	工具范围	风险控制
诊断	只读/查询/故障排查	可观测性、构建、浏览器、审计	默认入口，无写入操作
变更	创建/修改/删除资源	Workers绑定（KV/R2/D1）	需要用户确认，执行后验证
超级管理员	最高权限	所有工具 + 容器沙箱	仅用于隔离环境/测试账户

Tool Reference

工具参考

Diagnose Tier (Read-only)

诊断层级（只读）

Observability

Tool	Purpose
`query_worker_observability`	Query logs/metrics (events, CPU, error rate)
`observability_keys`	Discover available fields
`observability_values`	Explore field values

Builds

Tool	Purpose
`workers_builds_list_builds`	List build history
`workers_builds_get_build`	Get build details
`workers_builds_get_build_logs`	Get build logs

Browser Rendering (Page Capture)

Tool	Purpose
`get_url_html_content`	Fetch page HTML
`get_url_markdown`	Convert to Markdown
`get_url_screenshot`	Take page screenshot

Audit Logs

Tool	Purpose
`auditlogs_by_account_id`	Pull change history by time range

可观测性

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

构建

工具	用途
`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`	按时间范围拉取变更历史

Change Tier (Write Operations)

变更层级（写入操作）

Account

Tool	Purpose
`accounts_list`	List accounts
`set_active_account`	Set active account

Builds (Settings)

Tool	Purpose
`workers_builds_set_active_worker`	⚠️ Set active worker (requires confirmation)

Tool	Purpose
`kv_namespaces_list`	List namespaces
`kv_namespace_get`	Get details
`kv_namespace_create`	Create (⚠️ requires confirmation)
`kv_namespace_update`	Update (⚠️ requires confirmation)
`kv_namespace_delete`	Delete (⚠️ requires confirmation)

Tool	Purpose
`r2_buckets_list`	List buckets
`r2_bucket_get`	Get details
`r2_bucket_create`	Create (⚠️ requires confirmation)
`r2_bucket_delete`	Delete (⚠️ requires confirmation)

Tool	Purpose
`d1_databases_list`	List databases
`d1_database_get`	Get details
`d1_database_query`	Execute SQL
`d1_database_create`	Create (⚠️ requires confirmation)
`d1_database_delete`	Delete (⚠️ requires confirmation)

Hyperdrive

Tool	Purpose
`hyperdrive_configs_list`	List configs
`hyperdrive_config_get`	Get details
`hyperdrive_config_create`	Create (⚠️ requires confirmation)
`hyperdrive_config_edit`	Edit (⚠️ requires confirmation)
`hyperdrive_config_delete`	Delete (⚠️ requires confirmation)

Workers

Tool	Purpose
`workers_list`	List workers
`workers_get_worker`	Get worker details
`workers_get_worker_code`	Get source code

账户

工具	用途
`accounts_list`	列出账户
`set_active_account`	设置活跃账户

构建（设置）

工具	用途
`workers_builds_set_active_worker`	⚠️ 设置活跃Worker（需要确认）

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

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

工具	用途
`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`	列出Workers
`workers_get_worker`	获取Worker详情
`workers_get_worker_code`	获取源代码

Super Admin Tier (Container Sandbox)

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

Tool	Purpose
`container_initialize`	Initialize container (~10 min lifecycle)
`container_exec`	Execute command
`container_file_write`	Write file
`container_file_read`	Read file
`container_files_list`	List files
`container_file_delete`	Delete file

Container Notes: No persistent state, short lifespan, only for temporary tasks (running tests/reproducing issues/parsing data).

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

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

Security Rules (Must Follow)

安全规则（必须遵守）

Read Operations

读取操作

Define scope first: account / worker / resource ID
No account? Run
accounts_list
first
Conclusions must have evidence chain: logs/screenshots/audit records

先定义范围：账户 / Worker / 资源ID
无账户？先运行
accounts_list
结论必须有证据链：日志/截图/审计记录

Write Operations (Three-step Flow)

写入操作（三步流程）

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

1. 计划：先读取当前状态（list/get）
2. 确认：输出精确的变更内容（名称/ID/影响范围），等待用户确认
3. 执行：创建/删除/更新
4. 验证：通过审计日志 + 可观测性确认无新错误

Prohibited Actions

禁止操作

❌ Execute create/delete/update without confirmation
❌ Delete production resources (unless user explicitly says "delete production xxx")
❌ Use Super Admin privileges in non-isolated environments
❌ Use container sandbox as persistent environment

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

Operation Workflows

操作工作流

Troubleshooting Flow (Typical)

故障排查流程（典型）

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. 明确症状 → Worker名称/时间范围/错误类型
2. 调用`query_worker_observability`拉取日志/指标
3. 若与构建相关 → 调用`workers_builds_get_build_logs`
4. 若与页面相关 → 调用`get_url_screenshot`复现问题
5. 追踪变更 → 调用`auditlogs_by_account_id`
6. 总结：根因 + 证据 + 修复建议

Resource Management Flow

资源管理流程

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

1. 调用`accounts_list` → 设置活跃账户`set_active_account`
2. 列出资源（`kv_namespaces_list` / `r2_buckets_list` / `d1_databases_list`）
3. 制定变更计划 → 提交给用户
4. 确认后执行
5. 验证：审计日志 + 可观测性显示无错误

Output Format

输出格式

Language: English
Structure: Conclusion → Key data/evidence → Tool call summary → Next steps
Write operations: Must clearly list operations to be executed and impact scope

Example output:

✅ 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 dev@example.com deployed new version
- Metrics: error_rate jumped from 0.1% to 12%

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

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

示例输出：

✅ 调查完成：Worker `api-gateway`在18:00-18:30期间出现5xx错误激增

根因：部署的新代码在处理/v2/users时抛出TypeError
证据：
- 日志：18:02首次出现“Cannot read property 'id' of undefined”
- 审计：18:00用户dev@example.com部署了新版本
- 指标：错误率从0.1%跃升至12%

建议：回滚到上一版本，或修复/v2/users处理逻辑

Error Handling

错误处理

Situation	Action
Account not set	Run `accounts_list` → `set_active_account` first
Resource doesn't exist	Verify ID/name is correct, list available resources
Insufficient permissions	Explain required permissions, suggest checking API token scope
Observability query too long	Split into smaller time ranges, ask more specific questions

场景	操作
未设置账户	先运行 `accounts_list` → `set_active_account`
资源不存在	验证ID/名称是否正确，列出可用资源
权限不足	说明所需权限，建议检查API令牌范围
可观测性查询耗时过长	拆分为更小的时间范围，询问更具体的问题

Scenario Examples

场景示例

See scenarios.md for 20 real-world development scenarios.

查看scenarios.md获取20个真实开发场景。