diff --git a/.agents/services/hosting/cloudflare-platform.md b/.agents/services/hosting/cloudflare-platform.md index a0bc2da4b..a28759bee 100644 --- a/.agents/services/hosting/cloudflare-platform.md +++ b/.agents/services/hosting/cloudflare-platform.md @@ -1,5 +1,5 @@ --- -description: "Cloudflare platform development guidance — patterns, gotchas, decision trees, SDK usage for Workers, Pages, KV, D1, R2, AI, Durable Objects, and 60+ products. Use when building or developing ON the Cloudflare platform. For managing/configuring CF resources via API, use the Cloudflare Code Mode MCP (cloudflare-mcp.md)." +description: "Cloudflare platform development guidance — patterns, gotchas, decision trees, SDK usage for Workers, Pages, KV, D1, R2, AI, Durable Objects, and 60+ products. Use when building or developing ON the Cloudflare platform. For managing Cloudflare resources (DNS, WAF, DDoS, R2 buckets, Workers deployments), use the Cloudflare Code Mode MCP server instead." mode: subagent imported_from: external --- @@ -24,6 +24,19 @@ imported_from: external +## Routing: Operations vs Development + +| Task | Tool | +|------|------| +| Manage DNS records, zones | Code Mode MCP | +| Configure WAF, DDoS, firewall rules | Code Mode MCP | +| Manage R2 buckets, Workers deployments | Code Mode MCP | +| Zero Trust, Access, Tunnel management | Code Mode MCP | +| Build a Worker (SDK, bindings, types) | This skill | +| Configure wrangler.toml, local dev | This skill | +| Debug Workers runtime issues | This skill | +| Understand product architecture, patterns | This skill | + Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references. ## How to Use This Skill @@ -140,7 +153,7 @@ Need media? Need IaC? ├─ Pulumi → pulumi/ ├─ Terraform → terraform/ -└─ Direct API → api/ +└─ Direct API → use Code Mode MCP (tools/mcp/cloudflare-code-mode.md) ``` ## Product Index @@ -243,7 +256,7 @@ Need IaC? |---------|------------| | Pulumi | `./references/pulumi/README.md` | | Terraform | `./references/terraform/README.md` | -| API | `./references/api/README.md` | +| API (Code Mode MCP) | `.agents/tools/mcp/cloudflare-code-mode.md` | ### Other Services diff --git a/.agents/services/hosting/cloudflare.md b/.agents/services/hosting/cloudflare.md index 5ad47dfbf..3aeff0f5e 100644 --- a/.agents/services/hosting/cloudflare.md +++ b/.agents/services/hosting/cloudflare.md @@ -13,6 +13,18 @@ tools: # Cloudflare API Setup for AI-Assisted Development +## Intent-Based Routing + +| Intent | Resource | +|--------|----------| +| **Manage/configure/update** Cloudflare resources (DNS, WAF, DDoS, R2, Workers, zones, rules, etc.) | `.agents/tools/mcp/cloudflare-code-mode.md` — Code Mode MCP (2,500+ endpoints, live OpenAPI) | +| **Build/develop** on the Cloudflare platform (Workers, Pages, D1, KV, Durable Objects, AI, etc.) | `cloudflare-platform.md` — patterns, gotchas, decision trees, SDK usage | +| **Auth/token setup** for API access | This file (below) | + +> **Operations** (DNS records, WAF rules, zone settings, R2 buckets, Worker deployments): use Code Mode MCP via `.agents/tools/mcp/cloudflare-code-mode.md`. +> +> **Development** (building Workers, integrating D1, using KV bindings, AI gateway patterns): use `cloudflare-platform.md`. + ## Quick Reference @@ -26,14 +38,7 @@ tools: - **API test**: `curl -X GET "https://api.cloudflare.com/client/v4/zones" -H "Authorization: Bearer TOKEN"` - **Security**: IP filtering, expiration dates, minimal permissions - **Rotation**: Every 6-12 months or after team changes - -## Intent-Based Routing - -| Intent | Tool | -|--------|------| -| Manage, configure, or update CF resources (DNS, zones, deployments, KV data, D1 queries) | Cloudflare Code Mode MCP → `tools/api/cloudflare-mcp.md` | -| Build or develop on the CF platform (Workers, Pages, D1 schema, R2, AI, Durable Objects) | Platform skill docs → `services/hosting/cloudflare-platform.md` | -| Set up API token auth for DNS/CDN management | This file (`cloudflare.md`) | +- **Code Mode MCP**: `.agents/tools/mcp/cloudflare-code-mode.md` (operations via 2,500+ endpoints) diff --git a/.agents/tools/mcp/cloudflare-code-mode.md b/.agents/tools/mcp/cloudflare-code-mode.md new file mode 100644 index 000000000..b8a7144bd --- /dev/null +++ b/.agents/tools/mcp/cloudflare-code-mode.md @@ -0,0 +1,194 @@ +--- +description: "Cloudflare Code Mode MCP server — full Cloudflare API coverage (2,500+ endpoints) via 2 tools (search + execute) in ~1,000 tokens. Use for all Cloudflare operations: DNS, WAF, DDoS, R2 management, Workers management, Zero Trust, etc." +mode: subagent +tools: + bash: true + webfetch: true +mcp_servers: + - cloudflare-api +--- + +# Cloudflare Code Mode MCP + +## What It Is + +The Cloudflare Code Mode MCP server provides access to the **entire Cloudflare API** (2,500+ endpoints) via just **two tools** consuming ~1,000 tokens — a 99.9% reduction vs a native MCP server (which would require 1.17M tokens). + +**MCP server URL**: `https://mcp.cloudflare.com/mcp` + +**Config template**: `configs/mcp-templates/cloudflare-api.json` + +## When to Use This (vs cloudflare-platform skill) + +| Intent | Use | +|--------|-----| +| Manage DNS records, zones, WAF rules | Code Mode MCP (`search` + `execute`) | +| Configure DDoS protection, firewall rules | Code Mode MCP | +| Manage R2 buckets, Workers deployments | Code Mode MCP | +| Zero Trust, Access policies | Code Mode MCP | +| Build a Worker (SDK, bindings, patterns) | `cloudflare-platform` skill | +| Configure wrangler.toml, local dev | `cloudflare-platform` skill | +| Debug Workers runtime issues | `cloudflare-platform` skill | +| Understand Cloudflare product architecture | `cloudflare-platform` skill | + +## Setup + +### Interactive (OAuth 2.1) + +Add to your MCP client config: + +```json +{ + "mcpServers": { + "cloudflare-api": { + "url": "https://mcp.cloudflare.com/mcp" + } + } +} +``` + +On first connection, you are redirected to Cloudflare to authorize and select permissions. The token is downscoped to only the capabilities you grant. + +### CI/CD (API Token) + +Create a Cloudflare API token with required permissions, then pass as bearer token: + +```bash +# Authorization header +Authorization: Bearer +``` + +See `services/hosting/cloudflare.md` for token creation guidance. + +## Tools + +### `search(code)` + +Searches the Cloudflare OpenAPI spec. The `spec` object contains the full spec with all `$refs` pre-resolved. Write JavaScript to filter endpoints. + +```javascript +// Find WAF and ruleset endpoints for a zone +async () => { + const results = []; + for (const [path, methods] of Object.entries(spec.paths)) { + if (path.includes('/zones/') && + (path.includes('firewall/waf') || path.includes('rulesets'))) { + for (const [method, op] of Object.entries(methods)) { + results.push({ method: method.toUpperCase(), path, summary: op.summary }); + } + } + } + return results; +} +``` + +```javascript +// Inspect a specific endpoint's schema +async () => { + const op = spec.paths['/zones/{zone_id}/rulesets']?.get; + const items = op?.responses?.['200']?.content?.['application/json']?.schema; + const props = items?.allOf?.[1]?.properties?.result?.items?.allOf?.[1]?.properties; + return { phases: props?.phase?.enum }; +} +``` + +### `execute(code)` + +Executes JavaScript against the Cloudflare API. The sandbox provides a `cloudflare.request()` client for authenticated API calls. Runs in a V8 isolate (no filesystem, no env var leakage, external fetches disabled by default). + +```javascript +// List rulesets on a zone +async () => { + const response = await cloudflare.request({ + method: "GET", + path: `/zones/${zoneId}/rulesets` + }); + return response.result.map(rs => ({ name: rs.name, phase: rs.phase, kind: rs.kind })); +} +``` + +```javascript +// Chain multiple API calls in one execution +async () => { + const ddos = await cloudflare.request({ + method: "GET", + path: `/zones/${zoneId}/rulesets/phases/ddos_l7/entrypoint` + }); + const waf = await cloudflare.request({ + method: "GET", + path: `/zones/${zoneId}/rulesets/phases/http_request_firewall_managed/entrypoint` + }); + return { ddos: ddos.result, waf: waf.result }; +} +``` + +## How Code Mode Works + +1. **`search()`** — agent writes JS against the OpenAPI spec object to discover endpoints. The full spec never enters the model context; only the filtered results do. +2. **`execute()`** — agent writes JS that calls `cloudflare.request()`. Multiple API calls can be chained in a single execution. Results are returned directly. +3. Both tools run in a **Dynamic Worker isolate** (sandboxed V8, no file system, no env var leakage). +4. **OAuth 2.1** downscopes the token to user-approved permissions only. + +## Common Operations + +### DNS Management + +```javascript +// search: find DNS record endpoints +async () => { + return Object.entries(spec.paths) + .filter(([path]) => path.includes('/dns_records')) + .map(([path, methods]) => ({ + path, + methods: Object.keys(methods) + })); +} + +// execute: list DNS records +async () => { + const res = await cloudflare.request({ + method: "GET", + path: `/zones/${zoneId}/dns_records` + }); + return res.result; +} +``` + +### WAF / Firewall Rules + +```javascript +// execute: enable managed WAF ruleset +async () => { + return await cloudflare.request({ + method: "PUT", + path: `/zones/${zoneId}/rulesets/phases/http_request_firewall_managed/entrypoint`, + body: { + rules: [{ + action: "execute", + expression: "true", + action_parameters: { id: "efb7b8c949ac4650a09736fc376e9aee" } + }] + } + }); +} +``` + +### R2 Bucket Management + +```javascript +// execute: list R2 buckets +async () => { + const res = await cloudflare.request({ + method: "GET", + path: `/accounts/${accountId}/r2/buckets` + }); + return res.result; +} +``` + +## References + +- Blog post: https://blog.cloudflare.com/code-mode-mcp/ +- GitHub: https://github.com/cloudflare/mcp +- Cloudflare API docs: https://developers.cloudflare.com/api/ +- Code Mode SDK (open source): https://github.com/cloudflare/agents/tree/main/packages/codemode