enuno/mcp-cloudflare

Cloudflare MCP Skill

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

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)

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 |

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 |

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) |

KV | 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) |

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

D1 | 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 |

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).

Security Rules (Must Follow)

Read Operations

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

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

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

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

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

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 [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

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 |

Scenario Examples

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