Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
67c7cb6
feat(mcp-apps): add shared MCP Apps foundation
geoquant Nov 18, 2026
96e80c5
feat(workers-usage-alert): add Workers usage alert preview MCP App
geoquant Nov 18, 2026
2b95d5f
feat(workers-usage-alert): rebuild the App as the radio-card mockup
geoquant Nov 19, 2026
eac3c2c
feat(workers-usage-alert): chart 89 days and preview an hourly 7-day …
geoquant Nov 19, 2026
9888bf2
feat(workers-usage-alert): move the axis right, per the latest mockup
geoquant Nov 19, 2026
bbe74cf
fix(workers-usage-alert): tell hosts without Apps not to mention a chart
geoquant Nov 19, 2026
3eacd52
feat(workers-usage-alert): create the alert from the button, no secon…
geoquant Nov 19, 2026
908734d
feat(mcp-apps): write with the generated tools, app-only in Code Mode
geoquant Nov 19, 2026
164e583
feat(workers-usage-alert): suggest a tenth above the busiest week
geoquant Nov 19, 2026
80b5779
feat(workers-usage-alert): tell the model how to reply in the result
geoquant Nov 19, 2026
3a3aa99
feat(workers-usage-alert): align the App with the latest mockup
geoquant Nov 19, 2026
6f92162
feat(workers-usage-alert): Undo and Save alert on the alert the card …
geoquant Nov 20, 2026
d6fd446
feat(threshold-alert): share the threshold alert App, add workers_bil…
geoquant Nov 20, 2026
d3e8cdb
fix(workers-usage-alert): route shut-off requests away and surge ques…
geoquant Nov 20, 2026
00cc263
docs(threshold-alert): drop planning notes and internal references
geoquant Nov 20, 2026
647f323
docs: remove the MCP App docs
geoquant Nov 20, 2026
1abe65b
fix(workers-usage-alert): render the card's facts as parts, not HTML …
geoquant Nov 20, 2026
67a15ad
fix(threshold-alert): address council review round 1
geoquant Nov 20, 2026
d35da15
fix(threshold-alert): address council review round 2
geoquant Nov 20, 2026
07d9fb4
fix(threshold-alert): address council review round 3
geoquant Nov 20, 2026
22b8a59
fix(workers-usage-alert): keep an unconfirmed create's warning while …
geoquant Nov 20, 2026
a94ff20
feat(mcp-apps): serve Apps only to clients that declare them
geoquant Nov 20, 2026
df001a3
fix(mcp-apps): address review of the Apps capability gate
geoquant Nov 20, 2026
cd8bf21
fix(workers-usage-alert): remove the Account line from the card
geoquant Nov 20, 2026
9955a49
refactor(workers-usage-alert): drop accountName; one Phase union for …
geoquant Nov 20, 2026
f8afe3e
perf(mcp-apps): read in parallel, keep the series out of the model's …
geoquant Nov 20, 2026
e9a020d
perf(mcp-apps): ship only the CSS and JavaScript the view renders
geoquant Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ jobs:
- name: Install dependencies
run: npm ci

- name: Check MCP App HTML is fresh
run: npm run app:check

- name: Check formatting
run: npm run format:check

Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@ node_modules
dist/
*.log
.worktrees/
.mcp-apps-build/
3 changes: 2 additions & 1 deletion .oxfmtrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
"semi": false,
"trailingComma": "none",
"ignorePatterns": [
"src/generated/**"
"src/generated/**",
"src/*/app-html.generated.ts"
]
}
26 changes: 25 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ cloudflare-mcp/
│ ├── mcp-handler.ts # Stateless MCP HTTP handler & deployment guards
│ ├── server.ts # MCP server setup & tool registration
│ ├── events/ # Stateless MCP Events mapping to ANS policies and Vega automations
│ ├── mcp-apps/ # Shared MCP Apps: defineMcpApp, read-only apiReader, registry, app-shell
│ ├── threshold-alert/ # Shared threshold alert Apps: presets, model, collector, policy writes
│ ├── executor.ts # Code executor (Worker Loader API)
│ ├── spec-processor.ts # OpenAPI spec $ref resolution & splitting merged paths
│ ├── spec-release.ts # The pinned spec release and its artifact names
Expand Down Expand Up @@ -67,6 +69,7 @@ cloudflare-mcp/
├── scripts/
│ ├── cloudflare-account.ts # The account scripts run cf against
│ ├── seed-r2.ts # Seed skills to R2 (cf r2 objects put)
│ ├── build-mcp-apps.ts # Build every src/<app>/app into app-html.generated.ts
│ ├── generate-tools.ts # Regenerate src/generated/forge-mcp with forge
│ ├── schema-mismatch-report.ts # Response schema mismatches by product, for teams
│ └── bench-response-validation.ts # Cost of response schema checks on the generated schemas
Expand Down Expand Up @@ -103,6 +106,7 @@ Node 22+ required.
| `npm run deploy` | Deploy to staging |
| `npm run deploy:prod` | Deploy to production by hand (merging to `main` already deploys) |
| `npm run deploy:forge-tools` / `deploy:forge-tools:prod` | Deploy the forge tools service to staging / production |
| `npm run app:build` | Build every MCP App's HTML (`-- <app>` for one) |
| `npm run generate:tools` | Regenerate `src/generated/forge-mcp` with the pinned `@cloudflare/forge` |
| `npm run types` | Generate worker type definitions |
| `npm run typecheck` | TypeScript type checking (no emit) |
Expand Down Expand Up @@ -163,6 +167,26 @@ The core innovation: instead of 2,500 MCP tools (~244K tokens), two tools handle
- `src/events/callback.ts` opens the sealed destination secret ANS presents, checks the KV subscription record and synchronously signs the MCP callback, with no Cloudflare API call. ANS owns retries.
- `npm run test:events` runs local workerd coverage with simulated external HTTP endpoints. See `docs/mcp-events.md` for live tests and lifecycle constraints.

### Threshold alert Apps

`src/threshold-alert/` is what every "history of one number + a line + who to tell" App shares: `defineThresholdAlertApp()` (the read-only collector: history, `available_alerts`, existing policies), the model per cadence (rolling 7 days or calendar month), the presets (each an `alert_type`, its policy body, how it recognises an existing policy, its copy) and the generated `alerting_policies_*` writes. One tool per preset, sharing the view; `workers_billing_alert` is the `billing_usage_alert` preset.

### Workers usage alert App

`src/workers-usage-alert/` is the `workers_usage_alert` MCP App, registered in `MCP_APPS`. It charts 89 days of Workers requests and previews an hourly `custom_analytics` monitor on a rolling 7 days. The tool only reads; the App's Create alert button creates the policy with the generated `alerting_policies_create` through `callServerTool`, which Code Mode lists, for the App only, to an MCP Apps host (`appTools`).

### MCP Apps

`src/mcp-apps/` holds what every MCP App shares: `defineMcpApp()` (a tool plus its static `ui://` HTML resource, served in both tool modes, and `appTools`, the generated tools its view writes with, which Code Mode lists app-only), `apiReader()` (bounded, read-only Cloudflare API and GraphQL reads with the direct tools' refusal explanations and step-up), `MCP_APPS` in `registry.ts` (the one list an App is added to) and `app-shell/` (the browser-side host connection and Kumo base CSS). Each App lives in `src/<app>/`, with its React/Kumo view in `src/<app>/app/`, built into `app-html.generated.ts` by `npm run app:build`; never hand-edit those. `npm run check` verifies they are fresh and type-checks the view with `tsconfig.app.json`. Keep raw customer prompts, account output and host screenshots outside this public repository.

Apps are served only to a client that declares them (`src/mcp-apps/capability.ts`): a 2026-07-28 request whose `_meta` envelope lists `text/html;profile=mcp-app` under `extensions["io.modelcontextprotocol/ui"].mimeTypes`, as the Apps spec asks ("Servers SHOULD check client capabilities before registering UI-enabled tools"). `mcp-handler.ts` parses the body once more to decide (`RequestContext.mcpApps`) and hands it to `isLegacyRequest`. The MIME type is compared ignoring whitespace and case. A 2025-era request sends capabilities only in `initialize`, which this stateless server never sees again, so it always counts as not declaring them, and a 2025-era host that renders Apps loses them (accepted); in production (November 2026) 98% of `tools/list` requests, and nearly all of Claude's and ChatGPT's, were 2026-07-28. For any other client:

- Each App's tool is listed as a plain tool, with no `_meta.ui` or `ui/resourceUri` (`withoutAppView`). Its JSON text result is the spec's text-only fallback.
- Code Mode doesn't register the `appTools`, so they are neither listed nor callable (about 25 KB: Code Mode's `tools/list` goes from ~46 KB to ~21 KB). The direct tools list every generated tool anyway.
- `resources/list` leaves out the `ui://` pages; `resources/read` still serves them, since they are static.

The server declares `io.modelcontextprotocol/ui` in its capabilities to every client. A 1% sample of 2026-07-28 `tools/list` and `tools/call` requests logs `mcp_apps <method>: declared=<bool> client="<clientInfo.name>"` (plus `tool=` for calls), to check that the hosts that render Apps declare them on both, including the view's own write calls.

### Worker Loader API

Code execution uses Cloudflare's Worker Loader API to dynamically create isolated worker instances. The API token is passed via props (never enters user code isolate). A `globalOutbound` service restricts network access.
Expand Down Expand Up @@ -273,7 +297,7 @@ What the server does:
- **Holds** (`holdOf`): every response becomes at most one hold, the time requests under the same limit should wait. Below a reserve of 5% of the quota it is the time the bucket takes to refill to the reserve, at most 5 seconds, so a run settles at the refill rate without emptying the bucket. On a 429 it is the wait Cloudflare gives.
- **Scope** (`holdScope`): a response names its limit, not the other endpoints under it, and nothing is guessed. `default` holds every request, also when a 429 names it as exhausted next to another limit. Any other limit holds the operation that reported it, on the same account or zone, found in the spec. A limit that covers more costs one 429 per further operation.
- **`execute`**: `GlobalOutbound` passes the hold in `X-Cloudflare-MCP-Rate-Limit`, and the sandbox's `fetch` wrapper applies it for the rest of the run. It waits out a hold of 5 seconds or less and answers a request under a longer one itself with a 429 the error calls "not sent". A run waits 30 seconds in total, counting a hold that requests sent together wait out at the same time once; after that a held request is not sent either, so the call returns an error that says how far it got before the TypeScript SDK's 60-second request timeout cuts it off with nothing. A "not sent" answer involves no I/O, so code that retries a held request in a loop would spin until the Worker runs out of CPU or memory (two `exceededMemory` outcomes in the first hour of #391, which was rolled back). Each answer therefore yields to the event loop, and after 1,000 of them the run is stopped with an error. A stopped run sends and answers nothing more, whatever its code is still doing. A hold only stops requests not yet sent, so the wrapper lets at most 20 requests of a run wait for Cloudflare's answer at once (`MOST_IN_FLIGHT`): a batch sent under an exhausted limit has at most 20 refused, and a hundred healthy requests go out in five rounds. Workers' own limit of six open connections does not do this, since each request is its own `GlobalOutbound` invocation: code that sent 125 R2 requests with `Promise.all` had every one refused before the first 429 came back (`limited=125 not_sent=0`, about 4,400 refusals in six minutes from one client). Each run a limit touched logs `execute rate limits: limited=<429s> not_sent=<saved> waited_ms=<paced>`.
- **Retries**: the sandbox's `fetch` wrapper sends a request Cloudflare answered with a 429 again, up to three times, once the hold that 429 set is over. A 429 with no wait (D1, KV, URL Scanner) is held for a backoff of 1, 2 and 4 seconds. `GlobalOutbound` retries no 429 itself (`retryRateLimited: false`): a wait there held back none of the run's other requests and was not counted in its budget, so a loop over a product limit slept up to 7 seconds per request until the client gave up. When the hold is longer than 5 seconds or the budget is spent, the code gets the 429. The direct tools make one request and still retry in `fetchWithRetry` (`src/utils/fetch-retry.ts`): after the server's wait when it is 5 seconds or less, with backoff when the server gives none, and not at all when it asks for longer.
- **Retries**: the sandbox's `fetch` wrapper sends a request Cloudflare answered with a 429 again, up to three times, once the hold that 429 set is over. A 429 with no wait (D1, KV, URL Scanner) is held for a backoff of 1, 2 and 4 seconds. `GlobalOutbound` retries no 429 itself (`retryRateLimited: false`): a wait there held back none of the run's other requests and was not counted in its budget, so a loop over a product limit slept up to 7 seconds per request until the client gave up. When the hold is longer than 5 seconds or the budget is spent, the code gets the 429. The direct tools make one request and still retry in `fetchWithRetry` (`src/utils/fetch-retry.ts`): after the server's wait when it is 5 seconds or less, with backoff when the server gives none, and not at all when it asks for longer. A POST or PATCH that fails on the network is not sent again (`retryNetworkErrors: false`): it may have reached Cloudflare, and a second create would make a second resource.
- **Hints** (`rateLimitHint`): every 429 tool error, in Code Mode and the direct tools, says how long Cloudflare asks to wait. The wait is in headers the agent never sees.
- **Identity probes** (`src/auth/api-token-mode.ts`): a direct credential whose probe Cloudflare refuses is held in `OAUTH_KV` (`api-token-rate-limited:v1:<token hash>`, only the refusal and the time the hold ends), and requests with it are answered from the hold without asking Cloudflare. A rate-limited credential is held for the `Retry-After` it got and answered `429 temporarily_unavailable` with what is left of the wait. A credential Cloudflare doesn't recognise is held for a minute and answered `401 invalid_token`; `429 10502` counts as that, since it is Cloudflare's answer to a token that keeps failing. Answering it as a rate limit told clients to try again later, and each try was two more failures. Each held request logs `api_token_identity_probe held:`.
- **Not done**: nothing about API calls is remembered between tool calls, so a direct tool call is never paced and an agent that ignores the hint gets one 429 per call. Remembering would need KV or a Durable Object per credential to copy a counter the API already keeps; one isolate serves every user, so it can't live in the isolate.
Expand Down
Loading