t1289: Integrate Cloudflare Code Mode MCP + trim superseded API reference docs

.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
 
 <!-- AI-CONTEXT-END -->
 
+## 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
 

.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`.
+
 <!-- AI-CONTEXT-START -->
 
 ## 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)
 
 <!-- AI-CONTEXT-END -->
 

.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 <your-cloudflare-api-token>
+```
+
+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