From 27cc303d1c4fc59720e5b8185a4bf80052f04b90 Mon Sep 17 00:00:00 2001 From: Sakibul Islam Date: Sun, 23 Aug 2026 11:22:22 +0100 Subject: [PATCH 1/6] docs: list Semgrep workflow Per cloudflare/mcp#111 --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index e38c1be..02ede01 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,6 +47,7 @@ cloudflare-mcp/ │ └── seed-r2.ts # Seed OpenAPI spec to R2 bucket ├── .github/workflows/ │ ├── ci.yml # PR validation +│ ├── semgrep.yml # Security scanning │ └── bonk.yml # AI code review ├── wrangler.jsonc # Workers config (dev/staging/prod) ├── .oxfmtrc.json # oxfmt formatter config From 3378ecae5d769f0f7cbf06a24799fd5ec6cdc893 Mon Sep 17 00:00:00 2001 From: Sakibul Islam Date: Sun, 23 Aug 2026 11:22:35 +0100 Subject: [PATCH 2/6] docs: document docs search tool Per cloudflare/mcp#148 --- AGENTS.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 02ede01..9d3678b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## Project overview -`cloudflare-mcp` is a token-efficient Model Context Protocol (MCP) server that exposes the entire Cloudflare API (~2,500 endpoints) using Cloudflare's **Code Mode** pattern. Instead of registering thousands of MCP tools, it uses just two tools (`search` and `execute`) that let agents write JavaScript to query the OpenAPI spec and call APIs — fitting all 2,500 endpoints into ~1,000 tokens. +`cloudflare-mcp` is a token-efficient Model Context Protocol (MCP) server that exposes the entire Cloudflare API (~2,500 endpoints) using Cloudflare's **Code Mode** pattern. Instead of registering thousands of MCP tools, it uses just three tools (`docs`, `search`, and `execute`) that let agents search Cloudflare documentation, query the OpenAPI spec, and call APIs — fitting all 2,500 endpoints into ~1,000 tokens. **Production URL:** `mcp.cloudflare.com` @@ -102,12 +102,13 @@ Node 22+ required. ## Architecture -### Two-tool Code Mode pattern +### Three-tool Code Mode pattern -The core innovation: instead of 2,500 MCP tools (~244K tokens), two tools handle everything: +The core innovation: instead of 2,500 MCP tools (~244K tokens), three tools handle everything: -1. **`search` tool** — Agents write JavaScript to query the pre-resolved OpenAPI spec (all `$ref`s inlined). Runs in an isolated worker with no network access. -2. **`execute` tool** — Agents write JavaScript using `cloudflare.request()` to call discovered endpoints. Runs in an isolated worker with outbound restricted to Cloudflare API URLs only. +1. **`docs` tool** — Searches Cloudflare documentation using AI Search. +2. **`search` tool** — Agents write JavaScript to query the pre-resolved OpenAPI spec (all `$ref`s inlined). Runs in an isolated worker with no network access. +3. **`execute` tool** — Agents write JavaScript using `cloudflare.request()` to call discovered endpoints. Runs in an isolated worker with outbound restricted to Cloudflare API URLs only. ### MCP HTTP serving From 62e6a566379409b7ab2dc41f4792be292d12d5f8 Mon Sep 17 00:00:00 2001 From: Sakibul Islam Date: Sun, 23 Aug 2026 11:22:49 +0100 Subject: [PATCH 3/6] docs: update Worker test paths Per cloudflare/mcp#155 --- AGENTS.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9d3678b..be67b50 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,8 +41,9 @@ cloudflare-mcp/ │ ├── executor.test.ts │ ├── spec-processor.test.ts │ ├── truncate.test.ts -│ └── e2e/ # End-to-end tests (real worker via exports.default.fetch) -│ └── tool-call.test.ts +│ ├── setup/msw.ts # Outbound fetch mocks +│ ├── worker.test.ts # Code Mode Worker integration +│ └── non-codemode-worker.test.ts # Non-Code-Mode Worker integration ├── scripts/ │ └── seed-r2.ts # Seed OpenAPI spec to R2 bucket ├── .github/workflows/ @@ -184,13 +185,13 @@ npm run test:watch # Watch mode - Response truncation - Metrics event mapping & path normalization -**End-to-end (`tests/e2e/`):** +**Worker integration (`tests/worker.test.ts`):** Drives the real worker via `exports.default.fetch()` (from `cloudflare:workers`), the pattern from the [Cloudflare vitest recipes](https://developers.cloudflare.com/workers/testing/vitest-integration/recipes/). A full JSON-RPC `tools/call` for `execute` runs real code inside a Worker Loader isolate and is forwarded through the real `GlobalOutbound` proxy. The **only** mock is outbound `fetch()`, declared with **MSW** (`server.use(http.get(...))`) — see -`tests/e2e/msw-server.ts` and `tests/e2e/msw-setup.ts`. MSW intercepts both the +`tests/setup/msw.ts`. MSW intercepts both the auth-guard `/user`+`/accounts` probes and the GlobalOutbound-forwarded API call. Everything else — auth, MCP transport, tool dispatch, Worker Loader — is the real code path. From f2e7a65d18b31ddc9dc154cf5425de779f415f15 Mon Sep 17 00:00:00 2001 From: Sakibul Islam Date: Sun, 23 Aug 2026 11:23:07 +0100 Subject: [PATCH 4/6] docs: update Code Mode tool modules Per cloudflare/mcp#158 --- AGENTS.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index be67b50..d6bb2ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,11 @@ cloudflare-mcp/ │ ├── index.ts # Worker entry point & OAuth routing │ ├── mcp-handler.ts # Stateless MCP HTTP handler & deployment guards │ ├── server.ts # MCP server setup & tool registration -│ ├── executor.ts # Code executor (Worker Loader API) +│ ├── tools/ +│ │ ├── docs-search.ts # Cloudflare documentation search +│ │ ├── search.ts # Code Mode OpenAPI search +│ │ ├── execute.ts # Code Mode API execution +│ │ └── non-codemode.ts # Non-Code-Mode tool dispatch │ ├── spec-processor.ts # OpenAPI spec fetching & $ref resolution │ ├── truncate.ts # Response truncation (~6K token limit) │ ├── metrics.ts # Analytics Engine metrics (auth_user/tool_call) From b61e9c3b193a8115e84db77b0512c51135cc4969 Mon Sep 17 00:00:00 2001 From: Sakibul Islam Date: Sun, 23 Aug 2026 11:23:11 +0100 Subject: [PATCH 5/6] docs: remove obsolete cookie encryption note Per cloudflare/mcp#188 --- AGENTS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d6bb2ca..08c8319 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -169,7 +169,6 @@ Tool usage is tracked via the `MCP_METRICS` Analytics Engine binding into the sh - `globalOutbound` service restricts execute tool to Cloudflare API URLs only - Search tool runs with no network access - OAuth uses PKCE (RFC 7636) for secure authorization -- Cookie encryption for OAuth sessions (`MCP_COOKIE_ENCRYPTION_KEY`) - The `/mcp` route validates Host and present browser Origin headers against deployment-static allowlists before authentication ## Testing From 27a4a779ab21931b2b5e0c506ff42f139514294e Mon Sep 17 00:00:00 2001 From: Sakibul Islam Date: Sun, 23 Aug 2026 11:26:50 +0100 Subject: [PATCH 6/6] docs: update Cloudflare API endpoint count --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 08c8319..29c7e0c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## Project overview -`cloudflare-mcp` is a token-efficient Model Context Protocol (MCP) server that exposes the entire Cloudflare API (~2,500 endpoints) using Cloudflare's **Code Mode** pattern. Instead of registering thousands of MCP tools, it uses just three tools (`docs`, `search`, and `execute`) that let agents search Cloudflare documentation, query the OpenAPI spec, and call APIs — fitting all 2,500 endpoints into ~1,000 tokens. +`cloudflare-mcp` is a token-efficient Model Context Protocol (MCP) server that exposes the entire Cloudflare API (~3,300 endpoints) using Cloudflare's **Code Mode** pattern. Instead of registering thousands of MCP tools, it uses just three tools (`docs`, `search`, and `execute`) that let agents search Cloudflare documentation, query the OpenAPI spec, and call APIs — fitting all ~3,300 endpoints into ~1,000 tokens. **Production URL:** `mcp.cloudflare.com` @@ -109,7 +109,7 @@ Node 22+ required. ### Three-tool Code Mode pattern -The core innovation: instead of 2,500 MCP tools (~244K tokens), three tools handle everything: +The core innovation: instead of ~3,300 MCP tools (~244K tokens), three tools handle everything: 1. **`docs` tool** — Searches Cloudflare documentation using AI Search. 2. **`search` tool** — Agents write JavaScript to query the pre-resolved OpenAPI spec (all `$ref`s inlined). Runs in an isolated worker with no network access.