@frontmcp/skills 1.7.2 → 1.8.1

package/catalog/frontmcp-config/references/configure-throttle.md

@@ -45,7 +45,7 @@ Protect your FrontMCP server with rate limiting, concurrency control, execution
       partitionBy: 'global', // shared across all clients
     },
 
-    // Global concurrency limit
+    // Global concurrency limit (a tool called with this.callTool() runs inside its caller's slot)
     globalConcurrency: {
       maxConcurrent: 50,
       partitionBy: 'global',
@@ -68,8 +68,8 @@ Protect your FrontMCP server with rate limiting, concurrency control, execution
       allowList: ['10.0.0.0/8', '172.16.0.0/12'], // CIDR ranges
       denyList: ['192.168.1.100'],
       defaultAction: 'allow', // 'allow' | 'deny'
-      trustProxy: true, // trust X-Forwarded-For
-      trustedProxyDepth: 1, // proxy depth to trust
+      // NOTE: trustProxy / trustedProxyDepth are NOT read here -- use the
+      // FRONTMCP_TRUST_PROXY and FRONTMCP_TRUSTED_PROXY_DEPTH environment variables.
     },
   },
 })
@@ -112,6 +112,82 @@ class ExpensiveQueryTool extends ToolContext {
 }
 ```
 
+## `ipFilter` is enforced on every HTTP route
+
+`allowList`, `denyList` and `defaultAction` are checked by the `checkIpFilter` stage that starts
+every HTTP-facing flow, before the rate-limit check and before authentication:
+
+- the MCP endpoint (`<entryPath>`, `/sse`, `/message`) -- rejected with HTTP 403 and JSON-RPC
+  error `-32001`;
+- `/oauth/*`, `/.well-known/*`, `llm.txt` / `llm_full.txt`, the skills HTTP API, and custom
+  `http.routes` (before `auth: true` verification) -- rejected with HTTP 403 and
+  `{ "error": "forbidden", "message": "Client IP rejected by ipFilter" }`.
+
+Health and readiness probes (`/healthz`, `/readyz`, `/health`) and `/metrics` (bearer-token
+protected) are exempt. `IpBlockedError` / `IpNotAllowedError` are not thrown by the built-in
+filter.
+
+A request whose client IP cannot be established matches neither list and gets
+`defaultAction` -- with `'deny'` it is rejected. An IPv4-mapped peer (`::ffff:203.0.113.7`,
+how a dual-stack Node socket reports an IPv4 client) matches IPv4 rules.
+
+An `ipFilter` block works on its own -- you do not need to configure a `global` rate limit
+alongside it for the filter to run.
+
+### Where the client IP comes from
+
+| Runtime                                    | Client IP                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------ |
+| Node / Express / serverless handler        | Socket peer                                                        |
+| Behind a declared proxy                    | `X-Forwarded-For` (`FRONTMCP_TRUST_PROXY=true`, see below)         |
+| Cloudflare Workers (incl. Durable Objects) | `CF-Connecting-IP` -- trusted only when running on Workers         |
+| Deno                                       | `info.remoteAddr` -- use `Deno.serve(handler)`                     |
+| Bun                                        | `server.requestIP(request)` -- use `Bun.serve({ fetch: handler })` |
+
+## `partitionBy: 'ip'` needs a declared trusted proxy
+
+The client IP comes from the socket peer address. `X-Forwarded-For` and `X-Real-IP` are set
+by whoever sent the request, so they are ignored unless you declare a trusted proxy:
+
+```bash
+FRONTMCP_TRUST_PROXY=true          # honour forwarded headers -- ONLY behind a real proxy
+FRONTMCP_TRUSTED_PROXY_DEPTH=1     # how many proxies you run in front of the app
+```
+
+- Behind a load balancer **without** `FRONTMCP_TRUST_PROXY`, every request looks like it came
+  from the balancer and all clients share one bucket.
+- **With** it but no proxy actually in front, a caller forges the header and gets a fresh
+  bucket per request, so the limit never triggers.
+
+The client is read `FRONTMCP_TRUSTED_PROXY_DEPTH` hops back from the end of the chain: callers
+can prepend entries, but only your own proxies append to it. The value is validated as an IP
+address before use. A chain shorter than the configured depth was not built by your proxies,
+so the socket peer is used instead.
+
+> **`FRONTMCP_TRUST_PROXY` is only as good as your network boundary.** Trusting forwarded
+> headers means trusting whoever can set them, so two things must hold:
+>
+> - **Every ingress path traverses the configured proxy chain.** If a caller can reach the
+>   origin directly -- a public origin IP, a peered VPC, a second ingress that skips the
+>   balancer -- they choose the whole `X-Forwarded-For` chain, and counting hops from its end
+>   just lands on an address they picked.
+> - **The edge strips and rebuilds the forwarded headers.** The outermost proxy must discard
+>   any inbound `X-Forwarded-For` and `X-Real-IP` and write its own, so the only entries in
+>   the chain are ones your proxies appended.
+>
+> With depth `1` and no `X-Forwarded-For` at all, `X-Real-IP` is used -- the single-hop nginx
+> convention. It is never consulted alongside a chain, because a caller can send both.
+
+On Cloudflare Workers, Deno and Bun the web-fetch adapter supplies the platform's peer
+address (table above), so edge callers get their own buckets too.
+
+When no IP can be established the request falls back to the authenticated user
+(`user:<userId>`), and to a single `ip:unresolved` partition when there is no user either. It
+never keys on the session id: `mcp-session-id` is caller-supplied and a request without one is
+given a fresh UUID, so keying on it would mint a new budget per request. The shared bucket is
+contended by design -- bounded contention beats an unbounded budget -- and declaring your proxy
+is what takes callers out of it.
+
 ## Configuration Types
 
 ### RateLimitConfig
@@ -138,19 +214,20 @@ class ExpensiveQueryTool extends ToolContext {
 
 ### IpFilterConfig
 
-| Field               | Type                | Default   | Description                         |
-| ------------------- | ------------------- | --------- | ----------------------------------- |
-| `allowList`         | `string[]`          | —         | Allowed IPs or CIDR ranges          |
-| `denyList`          | `string[]`          | —         | Blocked IPs or CIDR ranges          |
-| `defaultAction`     | `'allow' \| 'deny'` | `'allow'` | Action when IP matches neither list |
-| `trustProxy`        | `boolean`           | `false`   | Trust X-Forwarded-For header        |
-| `trustedProxyDepth` | `number`            | `1`       | How many proxy hops to trust        |
+| Field               | Type                | Default   | Description                                                        |
+| ------------------- | ------------------- | --------- | ------------------------------------------------------------------ |
+| `allowList`         | `string[]`          | —         | Allowed IPs or CIDR ranges                                         |
+| `denyList`          | `string[]`          | —         | Blocked IPs or CIDR ranges                                         |
+| `defaultAction`     | `'allow' \| 'deny'` | `'allow'` | Action when IP matches neither list, or no client IP is known      |
+| `trustProxy`        | `boolean`           | `false`   | **Not read** (startup warning). Use `FRONTMCP_TRUST_PROXY`         |
+| `trustedProxyDepth` | `number`            | `1`       | **Not read** (startup warning). Use `FRONTMCP_TRUSTED_PROXY_DEPTH` |
 
 ## Partition Strategies
 
 - **`'global'`** — Single shared counter for all clients. Use for global capacity limits.
 - **`'ip'`** — Separate counter per client IP. Use for per-client rate limiting.
-- **`'session'`** — Separate counter per MCP session. Use for per-session fairness.
+- **`'session'`** — Separate counter per MCP session the server verified; a `mcp-session-id` it does not accept is ignored. Use for per-session fairness. A request without a verified session (every MCP 2026-07-28 request, stateless HTTP, or a rejected session id) falls back to the signed-in user; anonymous callers share one `anonymous` counter. A `throttle.global` partitioned by session, user or a function is checked right after authentication; one partitioned by `'ip'` or `'global'` is checked before it.
+- **`'userId'`** — Separate counter per signed-in user. Anonymous callers fall back to the session, as above.
 
 ## Distributed Rate Limiting
 
@@ -196,7 +273,7 @@ done
 
 ### Configuration
 
-- [ ] `throttle.enabled` is set to `true` in the `@FrontMcp` decorator
+- [ ] `throttle.enabled` is set to `true` in the `@FrontMcp` decorator for the server-level options (`global`, `globalConcurrency`, the `default*` settings, `ipFilter`). A tool's own `rateLimit`/`concurrency` apply without it; `throttle.enabled: false` turns every guard off
 - [ ] `global.maxRequests` and `global.windowMs` are set to reasonable production values
 - [ ] `defaultTimeout.executeMs` is configured to prevent runaway tool executions
 - [ ] IP filter `defaultAction` matches your security posture (`allow` for open, `deny` for restricted)
@@ -216,17 +293,17 @@ done
 
 - [ ] Sending requests beyond the rate limit returns HTTP 429
 - [ ] Blocked IPs receive HTTP 403
-- [ ] Tool executions that exceed `executeMs` are terminated and return a timeout error
+- [ ] Tool executions that exceed `executeMs` return an `EXECUTION_TIMEOUT` error and abort `this.signal` and the tool's pending `this.fetch()` requests; the tool passes `this.signal` to other cancellable work so it stops too
 
 ## Troubleshooting
 
-| Problem                                         | Cause                                                                    | Solution                                                                        |
-| ----------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
-| Rate limits not enforced across instances       | In-memory storage used with multiple server replicas                     | Configure `storage: { type: 'redis' }` in the throttle block to share counters  |
-| All requests rejected with 403                  | `ipFilter.defaultAction` set to `'deny'` without any `allowList` entries | Add the allowed IP ranges to `allowList` or change `defaultAction` to `'allow'` |
-| Tools timing out unexpectedly                   | `defaultTimeout.executeMs` too low for the tool's normal execution time  | Increase the global default or set a per-tool `timeout.executeMs` override      |
-| `X-Forwarded-For` header ignored                | `ipFilter.trustProxy` not enabled or `trustedProxyDepth` too low         | Set `trustProxy: true` and adjust `trustedProxyDepth` to match your proxy chain |
-| Rate limit resets not aligned with expectations | `windowMs` misunderstood as a sliding window when it is a fixed window   | The window is fixed; all counters reset at the end of each `windowMs` interval  |
+| Problem                                         | Cause                                                                                                                                                                                                     | Solution                                                                                                                                     |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Rate limits not enforced across instances       | In-memory storage used with multiple server replicas                                                                                                                                                      | Configure `storage: { type: 'redis' }` in the throttle block to share counters                                                               |
+| All requests rejected with 403                  | `ipFilter.defaultAction` set to `'deny'` without any `allowList` entries, or the runtime reports no client IP (a custom fetch wrapper that drops the second handler argument on Deno/Bun)                 | Add the allowed IP ranges to `allowList`, pass the platform's second argument through to the handler, or change `defaultAction` to `'allow'` |
+| Tools timing out unexpectedly                   | `defaultTimeout.executeMs` too low for the tool's normal execution time                                                                                                                                   | Increase the global default or set a per-tool `timeout.executeMs` override                                                                   |
+| `X-Forwarded-For` header ignored                | No trusted proxy declared. `ipFilter.trustProxy` / `trustedProxyDepth` are accepted by the schema but NOT read -- client-IP extraction happens in the SDK context layer, before guard config is reachable | Set the `FRONTMCP_TRUST_PROXY=true` and `FRONTMCP_TRUSTED_PROXY_DEPTH` environment variables instead                                         |
+| Rate limit resets not aligned with expectations | `windowMs` misunderstood as a sliding window when it is a fixed window                                                                                                                                    | The window is fixed; all counters reset at the end of each `windowMs` interval                                                               |
 
 ## Examples
 

package/catalog/frontmcp-deployment/SKILL.md

@@ -77,6 +77,7 @@ Beyond `frontmcp build`, the CLI provides commands for the full deployment lifec
 | ---------------------------- | ----------------------------------------------------------------------------------- |
 | `frontmcp build -t <target>` | Build for target: `node`, `vercel`, `lambda`, `cloudflare`, `cli`, `browser`, `sdk` |
 | `frontmcp build -t cli --js` | Build CLI as JS bundle (instead of native binary via SEA)                           |
+| `frontmcp build --no-clean`  | Keep existing output instead of clearing the target's output directory first        |
 | `frontmcp start <name>`      | Start a named MCP server with supervisor (process management)                       |
 | `frontmcp stop <name>`       | Stop managed server (`-f` for force kill)                                           |
 | `frontmcp restart <name>`    | Restart managed server                                                              |
@@ -145,12 +146,15 @@ Beyond `frontmcp build`, the CLI provides commands for the full deployment lifec
 
 ## Troubleshooting
 
-| Problem                            | Cause                                        | Solution                                                                        |
-| ---------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------- |
-| Cold start timeout on serverless   | Bundle too large or heavy initialization     | Lazy-load providers; reduce bundle with tree shaking; increase function timeout |
-| Session lost between requests      | Using memory storage on stateless serverless | Switch to platform-native storage (Vercel KV, DynamoDB, etc.)                   |
-| CORS errors on browser/web clients | HTTP CORS not configured                     | Add CORS config via `configure-http` skill                                      |
-| Build fails with missing module    | Node-only module in browser/edge build       | Use conditional imports or `@frontmcp/utils` cross-platform utilities           |
+| Problem                                                          | Cause                                                                                     | Solution                                                                                                                                                             |
+| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cold start timeout on serverless                                 | Bundle too large or heavy initialization                                                  | Lazy-load providers; reduce bundle with tree shaking; increase function timeout                                                                                      |
+| Session lost between requests                                    | Using memory storage on stateless serverless                                              | Switch to platform-native storage (Vercel KV, DynamoDB, etc.)                                                                                                        |
+| CORS errors on browser/web clients                               | HTTP CORS not configured                                                                  | Add CORS config via `configure-http` skill                                                                                                                           |
+| Build fails with missing module                                  | Node-only module in browser/edge build                                                    | Use conditional imports or `@frontmcp/utils` cross-platform utilities                                                                                                |
+| `TS2688: Cannot find type definition file for 'node'` under Yarn | An older CLI shelled out to `npx tsc`, which starts a process that never loads `.pnp.cjs` | Upgrade the CLI — the build now runs the project's own `typescript` with the current Node binary, or delegates to `yarn`/`pnpm`/`bun` when there is no local install |
+| `@frontmcp/sdk tried to access <pkg> (a peer dependency)`        | Yarn Plug'n'Play enforces peer dependencies that a hoisted `node_modules` tree tolerates  | Add `nodeLinker: node-modules` to `.yarnrc.yml` and reinstall (`frontmcp create` now scaffolds this for Yarn projects)                                               |
+| Deleted source file still present in `dist/`                     | An older CLI never cleared the output directory, or `--no-clean` was passed               | Rebuild without `--no-clean`; the build now clears the target's output directory first                                                                               |
 
 ## Examples
 

package/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-custom-domain.md

@@ -6,7 +6,7 @@ description: 'Scaffold a FrontMCP project targeting Cloudflare, configure a cust
 tags: [deployment, json-rpc, cloudflare, worker, custom, domain]
 features:
   - 'Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts'
-  - 'Adding a custom domain with `wrangler domains add` for production-ready URLs'
+  - 'Adding a custom domain with `wrangler deploy --domain` for production-ready URLs'
   - 'End-to-end verification of both the health check and MCP JSON-RPC endpoint'
 ---
 
@@ -74,12 +74,9 @@ NODE_ENV = "production"
 ```
 
 ```bash
-# Build and deploy
+# Build and deploy to a custom domain
 frontmcp build --target cloudflare
-wrangler deploy
-
-# Add a custom domain
-wrangler domains add mcp.example.com
+npx wrangler deploy --domain mcp.example.com
 
 # Verify health endpoint (FrontMCP serves /healthz by default)
 curl https://mcp.example.com/healthz
@@ -93,7 +90,7 @@ curl -X POST https://mcp.example.com/mcp \
 ## What This Demonstrates
 
 - Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts
-- Adding a custom domain with `wrangler domains add` for production-ready URLs
+- Adding a custom domain with `wrangler deploy --domain` for production-ready URLs
 - End-to-end verification of both the health check and MCP JSON-RPC endpoint
 
 ## Related

package/catalog/frontmcp-deployment/references/deploy-to-cloudflare-skills-only.md

@@ -75,6 +75,10 @@ export default createEdgeMcp({
 is the **Cron Trigger** entrypoint that pulls a fresh bundle and hot-swaps it.
 Managed mode requires the optional peer `@frontmcp/plugin-skilled-openapi`.
 
+The pull sends `authToken` as a bearer token and never follows a redirect, so
+`endpoint` must serve the bundle directly; a 3xx (or a status-0
+`opaqueredirect`) fails the pull.
+
 This path is bundled by **wrangler** (not `frontmcp build`), so you maintain
 `wrangler.toml` yourself — it needs a `[[kv_namespaces]] binding = "BUNDLE_CACHE"`
 and a `[triggers] crontabs = [...]` (the `managed.pollIntervalMs` option is

package/catalog/frontmcp-deployment/references/deploy-to-cloudflare.md

@@ -36,7 +36,7 @@ Cloudflare Workers support is **experimental**. The Express-to-Workers adapter h
 ## Prerequisites
 
 - A Cloudflare account (https://dash.cloudflare.com)
-- Wrangler CLI installed: `npm install -g wrangler`
+- Wrangler — `frontmcp create --target cloudflare` adds it as a devDependency, so `npm run deploy` / `npm run dev:worker` use the project-local version. Invoke it directly as `npx wrangler` rather than installing it globally, so the pinned version is the one that runs.
 - A built FrontMCP project
 
 ## Step 1: Create a Cloudflare-targeted Project
@@ -45,7 +45,7 @@ Cloudflare Workers support is **experimental**. The Express-to-Workers adapter h
 npx frontmcp create my-app --target cloudflare
 ```
 
-This generates the project with a `wrangler.toml` and a deploy script (`npm run deploy` runs `wrangler deploy`).
+This generates the project with a `wrangler.toml`, `wrangler` as a devDependency, and `deploy` / `dev:worker` scripts that build first and then run the project-local `wrangler`.
 
 ## Step 2: Build for Cloudflare
 
@@ -57,24 +57,27 @@ This produces:
 
 ```text
 dist/cloudflare/
-  index.js       # Cloudflare Workers entry (CommonJS) — wraps your @FrontMcp server
-  main.js        # Your compiled server module (CommonJS)
-wrangler.toml    # Wrangler configuration (overwritten on every build)
+  index.js       # Cloudflare Workers entry (ES Module / Module Worker) — wraps your @FrontMcp server
+  main.js        # Your compiled server module (ES Module)
+wrangler.toml    # Wrangler configuration (managed keys reconciled on every build)
 ```
 
-Cloudflare Workers use CommonJS (not ESM). The build command sets `--module commonjs` automatically.
+The adapter emits a **Module Worker** (`export default { fetch }`), so the build
+compiles with `--module esnext`. The legacy CommonJS `module.exports` shape is
+read by Cloudflare as a Service Worker, where `nodejs_compat` cannot externalize
+Node builtins and the deploy fails — do not force CommonJS for this target.
 
-> **Important:** The Cloudflare adapter sets `alwaysWriteConfig: true` and overwrites the entire `wrangler.toml` on every build with the template below. Hand-edited bindings (`[[kv_namespaces]]`, `[vars]`, `[[d1_databases]]`, etc.) WILL be erased the next time you run `frontmcp build --target cloudflare`. Configure `name`, `compatibility_date`, and extra `compatibility_flags` via your `frontmcp.config` file's `deployments[].wrangler` section, and keep bindings in a separate config file referenced from your toolchain (or re-add them after each build).
+> **Important:** The Cloudflare adapter sets `alwaysWriteConfig: true`, but it rewrites only the keys it manages. `main` is always overwritten (it has to track the build output); `name` and `compatibility_date` are written only when the file does not already declare them; `compatibility_flags` is merged. Hand-edited `[vars]`, `[[kv_namespaces]]`, `[[d1_databases]]`, `[triggers]` and comments survive every build. If `wrangler.toml` and `frontmcp.config` disagree on the worker name, the build keeps the file's value and warns instead of renaming your worker.
 
 ## Step 3: Configure wrangler.toml
 
-The build always writes this. `compatibility_flags = ["nodejs_compat"]` is **always** emitted — the worker entry is an ES Module that imports `@frontmcp/sdk`'s web-fetch handler, which still transitively pulls in Node builtins (no Express on the Worker), so without the flag the deployed Worker fails to load. The default `compatibility_date` is `2024-09-23` (the date that enables full `nodejs_compat`). `main` is `dist/cloudflare/index.js`.
+The build writes this when the file does not exist yet. `nodejs_compat` is **always** emitted — the worker entry is an ES Module that imports `@frontmcp/sdk`'s web-fetch handler, which still transitively pulls in Node builtins (no Express on the Worker), so without the flag the deployed Worker fails to load. `nodejs_compat_populate_process_env` is emitted too, so `[vars]` and secrets are readable as `process.env.*`; add `nodejs_compat_do_not_populate_process_env` to `wrangler.compatibilityFlags` to opt out. The default `compatibility_date` is `2024-09-23` (the date that enables full `nodejs_compat`). `main` is `dist/cloudflare/index.js`.
 
 ```toml
 name = "frontmcp-worker"
 main = "dist/cloudflare/index.js"
 compatibility_date = "2024-09-23"
-compatibility_flags = ["nodejs_compat"]
+compatibility_flags = ["nodejs_compat", "nodejs_compat_populate_process_env"]
 ```
 
 `name`, `compatibility_date`, and any extra `compatibilityFlags` come from `frontmcp.config.{ts,js}`'s `deployments` array (`nodejs_compat` is merged in automatically). Example:
@@ -96,7 +99,7 @@ export default {
 };
 ```
 
-To add KV storage or other bindings, append them AFTER each build (or use a wrapper script that runs the build then concatenates a `wrangler.bindings.toml` you maintain separately):
+To add KV storage or other bindings, add them to `wrangler.toml` directly — they are preserved across builds:
 
 ```toml
 name = "my-worker"
@@ -115,7 +118,7 @@ NODE_ENV = "production"
 Create the KV namespace via the dashboard or CLI:
 
 ```bash
-wrangler kv:namespace create FRONTMCP_KV
+npx wrangler kv:namespace create FRONTMCP_KV
 ```
 
 Copy the returned `id` into your `wrangler.toml`.
@@ -144,22 +147,59 @@ export default MyServer;
 
 For session storage, use Upstash Redis (HTTP) via `redis: { provider: 'vercel-kv' }` or wire Cloudflare KV directly inside your tools — the SDK does not include a built-in Cloudflare KV provider, and ioredis-style `redis: { ... }` configs are rejected by the Cloudflare adapter at build time (no Node TCP on Workers).
 
+### Secrets, vars and `process.env`
+
+Worker bindings arrive as an argument to `fetch`, not as environment variables. The generated entry copies every **string** binding into `process.env` on the first request (existing values are never overwritten), so ordinary `process.env.MY_API_KEY` reads behave the same on Workers as under `frontmcp dev`. Non-string bindings (KV, D1, R2, Durable Objects) stay on `env`, which the entry forwards to the handler along with `ctx`.
+
+A value read at module-eval time — inside the `@FrontMcp({...})` argument itself — is still `undefined`, because the copy happens on the first request. Read configuration inside `execute()` / `read()`, or rely on `nodejs_compat_populate_process_env` (emitted by default), which populates `process.env` before your module evaluates.
+
+To keep bindings out of `process.env` entirely, add `nodejs_compat_do_not_populate_process_env` to `wrangler.compatibilityFlags`. Cloudflare's flag only suppresses population at module evaluation, so the build also drops the first-request bridge from the generated entry — otherwise it would put back exactly the values you excluded. Every binding is then read from the `env` argument only.
+
+### Required secrets
+
+`NODE_ENV = "production"` in `[vars]` makes this a production deployment, where FrontMCP refuses its development fallbacks:
+
+| Secret               | Required when                                                        | Failure without it                                                                                               |
+| -------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `MCP_SESSION_SECRET` | always in production — `session:verify` encrypts session IDs with it | `500 {"error":"server_misconfigured","code":"SESSION_SECRET_REQUIRED"}`                                          |
+| `JWT_SECRET`         | `auth.mode` is `local` or `remote` (these mint tokens)               | the server refuses to start; requests answer `500 {"error":"server_misconfigured","code":"JWT_SECRET_REQUIRED"}` |
+
+```bash
+npx wrangler secret put MCP_SESSION_SECRET   # openssl rand -hex 32
+
+# Only when auth.mode is `local` or `remote`; `public` and `transparent`
+# never mint local JWTs and do not read this.
+npx wrangler secret put JWT_SECRET           # openssl rand -hex 32
+```
+
+Because `[vars]` reach `process.env`, `npx wrangler dev` sees the same `NODE_ENV=production` the deployment does, so a missing secret fails locally rather than only after a successful deploy.
+
+### Background tasks
+
+Background tasks need a store that outlives a single request and is shared between isolates, which an edge runtime cannot provide in-process. FrontMCP disables them automatically when no distributed store is configured, and the worker serves normally without them — no `tasks: { enabled: false }` opt-out is needed. `tasks: { enabled: true }` without `tasks.redis` fails the build rather than the deployed worker.
+
 ## Step 5: Deploy
 
 ```bash
 # Preview deployment
-wrangler dev
+npx wrangler dev
 
 # Production deployment
-wrangler deploy
+npx wrangler deploy
 ```
 
 ### Custom Domain
 
-Configure a custom domain in the Cloudflare dashboard under **Workers & Pages > your worker > Settings > Domains & Routes**, or via wrangler:
+Configure a custom domain in the Cloudflare dashboard under **Workers & Pages > your worker > Settings > Domains & Routes**, declare it in `wrangler.toml`, or pass it to the deploy:
 
 ```bash
-wrangler domains add mcp.example.com
+npx wrangler deploy --domain mcp.example.com
+```
+
+The `wrangler.toml` form is equivalent and survives across deploys:
+
+```toml
+routes = [{ pattern = "mcp.example.com", custom_domain = true }]
 ```
 
 ## Step 6: Verify
@@ -176,19 +216,21 @@ curl -X POST https://frontmcp-worker.your-subdomain.workers.dev/mcp \
 
 ## Endpoint path, CORS & SSE — config-driven
 
+Two settings name this concept. `transport.http.path` in `frontmcp.config.*` configures the **CLI** (`frontmcp dev`, the inspector, the generated `clients[].url`); `@FrontMcp({ http: { entryPath } })` configures the **server**, and that is what the deployed worker reads. The cloudflare build reconciles them — `transport.http.path` becomes the server's default, an explicit decorator `entryPath` still wins, and the build warns on a mismatch and prints the resolved path (`Server will serve MCP at /mcp`).
+
 The worker's transport is driven by the standard `http` + `transport` config (the same fields the Express host reads), so behaviour is identical on both adapters. The worker serves MCP at **exactly one path** — `http.entryPath` (the worker root `/` when unset) — not a guessed `/` + `/mcp` set. Cloudflare never strips the path before it reaches the worker:
 
-| Clients use | `http.entryPath` | `wrangler.toml` route | Worker serves |
-| --- | --- | --- | --- |
-| `https://mcp.example.com` (subdomain) | omit (`/`) | `routes = [{ pattern = "mcp.example.com", custom_domain = true }]` | `/` |
-| `https://example.com/mcp` (path) | `'/mcp'` | `routes = [{ pattern = "example.com/mcp*", zone_name = "example.com" }]` | `/mcp` |
+| Clients use                           | `http.entryPath` | `wrangler.toml` route                                                    | Worker serves |
+| ------------------------------------- | ---------------- | ------------------------------------------------------------------------ | ------------- |
+| `https://mcp.example.com` (subdomain) | omit (`/`)       | `routes = [{ pattern = "mcp.example.com", custom_domain = true }]`       | `/`           |
+| `https://example.com/mcp` (path)      | `'/mcp'`         | `routes = [{ pattern = "example.com/mcp*", zone_name = "example.com" }]` | `/mcp`        |
 
 ```ts
 createEdgeMcp({
   /* …info, apps… */
   http: {
-    entryPath: '/mcp',       // the ONE path MCP is served at (omit → root '/')
-    cors: { origin: true },  // browser MCP clients (e.g. Inspector "Direct" mode); { origin, credentials, maxAge }
+    entryPath: '/mcp', // the ONE path MCP is served at (omit → root '/')
+    cors: { origin: true }, // browser MCP clients (e.g. Inspector "Direct" mode); { origin, credentials, maxAge }
   },
   // transport: 'legacy'/'modern' → SSE streaming on POST; 'stateless-api' → buffered JSON.
 });
@@ -203,7 +245,7 @@ createEdgeMcp({
 - **Bundle size**: Workers have a 1 MB compressed / 10 MB uncompressed limit (paid plan: 10 MB / 30 MB). Review dependencies and remove unused packages to reduce bundle size.
 - **CPU time**: 10 ms CPU time on free plan, 30 seconds on paid. Long-running operations must be optimized or use Durable Objects.
 - **No native modules**: `better-sqlite3` and other native Node.js modules are not available. Use KV, D1, or Upstash Redis for storage.
-- **Streaming**: Streamable HTTP works, including SSE responses (`POST` with `Accept: text/event-stream`) and the server→client SSE `GET` stream. The worker uses the SDK's `WebStandardStreamableHTTPServerTransport` — which **is** the standard Streamable HTTP transport (the Node `StreamableHTTPServerTransport` is a thin `req`/`res` wrapper over it, so there's one engine). **Server→client notifications** on the standalone `GET` stream require **stateful sessions** — set `sessions: {}` and bind the `SessionDurableObject` (Durable Object) per `Mcp-Session-Id`. Without it the worker is stateless and the `GET` stream can't deliver pushed notifications.
+- **Streaming**: Streamable HTTP works, including SSE responses (`POST` with `Accept: text/event-stream`) and the server→client SSE `GET` stream. The worker uses the SDK's `WebStandardStreamableHTTPServerTransport` — which **is** the standard Streamable HTTP transport (the Node `StreamableHTTPServerTransport` is a thin `req`/`res` wrapper over it, so there's one engine). **Server→client notifications** on the standalone `GET` stream require **stateful sessions** — set `sessions: {}` and bind the `SessionDurableObject` (Durable Object) per `Mcp-Session-Id`. Without it the worker is stateless and the `GET` stream can't deliver pushed notifications. A stateless worker also returns no `Mcp-Session-Id` to a session-based (2025-06-18) client; each of its requests is served on its own.
 
 ### Stateful sessions (Durable Object)
 
@@ -220,8 +262,9 @@ class_name = "FrontMcpSession"
 [[migrations]]
 tag = "v1"
 new_classes = ["FrontMcpSession"]
-[vars]
-MCP_SESSION_SECRET = "..."   # required on production isolates; bridged into process.env
+# MCP_SESSION_SECRET is required on production isolates. Set it as a SECRET, not
+# a var — `[vars]` is committed plaintext:
+#   npx wrangler secret put MCP_SESSION_SECRET   # openssl rand -hex 32
 ```
 
 One DO per session holds a persistent transport so the `GET` notification stream stays open and `tools/call` notifications reach it. It runs the **same `http:request` flow** (auth/session:verify/router/audit/metrics + hooks) as the stateless path — so transparent auth returns `401` + `WWW-Authenticate` on the worker too.
@@ -236,24 +279,24 @@ One DO per session holds a persistent transport so the `GET` notification stream
 
 ## Troubleshooting
 
-| Problem                       | Cause                                          | Solution                                                                  |
-| ----------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------- |
-| Worker exceeds size limit     | Too many bundled dependencies                  | Review dependencies and remove unused packages to reduce bundle size      |
+| Problem                       | Cause                                          | Solution                                                                                                                                       |
+| ----------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Worker exceeds size limit     | Too many bundled dependencies                  | Review dependencies and remove unused packages to reduce bundle size                                                                           |
 | Module format errors          | Worker bundled as a Service Worker             | FrontMCP Cloudflare builds emit an **ES Module Worker** (`export default { fetch }`); `nodejs_compat` requires it. Don't force `type`/CommonJS |
-| KV binding errors             | Namespace not created or binding name mismatch | Run `wrangler kv:namespace create` and copy the `id` into `wrangler.toml` |
-| Timeout errors                | CPU time exceeds plan limit                    | Upgrade plan or offload heavy computation to Durable Objects              |
-| CORS failures on MCP endpoint | Missing CORS headers in Worker response        | `@frontmcp/edge`: pass `cors: { origin: true }` to `createEdgeMcp({...})` (transport-level CORS) |
+| KV binding errors             | Namespace not created or binding name mismatch | Run `npx wrangler kv:namespace create` and copy the `id` into `wrangler.toml`                                                                  |
+| Timeout errors                | CPU time exceeds plan limit                    | Upgrade plan or offload heavy computation to Durable Objects                                                                                   |
+| CORS failures on MCP endpoint | Missing CORS headers in Worker response        | `@frontmcp/edge`: pass `cors: { origin: true }` to `createEdgeMcp({...})` (transport-level CORS)                                               |
 
 ## Common Patterns
 
-| Pattern            | Correct                                                                    | Incorrect                         | Why                                                                                                                                      |
-| ------------------ | -------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Pattern            | Correct                                                                            | Incorrect                         | Why                                                                                                                                                     |
+| ------------------ | ---------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Module format      | ES Module Worker (`main = "dist/cloudflare/index.js"`, `export default { fetch }`) | Service Worker / forced CommonJS  | FrontMCP Cloudflare builds emit an ES Module Worker at this exact path; the build overwrites `wrangler.toml`. `nodejs_compat` requires the Module shape |
-| Transport key      | `transport: { protocol: 'modern' }` (or `{ sse: true, streamable: true }`) | `transport: { type: 'sse' }`      | The schema field is `protocol`; valid presets are `'legacy' \| 'modern' \| 'stateless-api' \| 'full'`, or pass a `ProtocolConfig` object |
-| Storage binding    | `[[kv_namespaces]]` with matching `binding`                                | Hardcoded KV namespace ID in code | Bindings are injected at runtime by Workers                                                                                              |
-| Compatibility date | Set via `frontmcp.config.deployments[].wrangler.compatibilityDate`         | Hand-editing `wrangler.toml`      | The build overwrites `wrangler.toml`; config-driven values survive                                                                       |
-| Build command      | `frontmcp build --target cloudflare`                                       | `frontmcp build` (no target)      | Default target is Node.js, not Workers                                                                                                   |
-| Secrets            | `wrangler secret put MY_SECRET`                                            | Storing secrets in `[vars]`       | `[vars]` are visible in plaintext in the dashboard                                                                                       |
+| Transport key      | `transport: { protocol: 'modern' }` (or `{ sse: true, streamable: true }`)         | `transport: { type: 'sse' }`      | The schema field is `protocol`; valid presets are `'legacy' \| 'modern' \| 'stateless-api' \| 'full'`, or pass a `ProtocolConfig` object                |
+| Storage binding    | `[[kv_namespaces]]` with matching `binding`                                        | Hardcoded KV namespace ID in code | Bindings are injected at runtime by Workers                                                                                                             |
+| Compatibility date | Set via `frontmcp.config.deployments[].wrangler.compatibilityDate`                 | Hand-editing `wrangler.toml`      | The build overwrites `wrangler.toml`; config-driven values survive                                                                                      |
+| Build command      | `frontmcp build --target cloudflare`                                               | `frontmcp build` (no target)      | Default target is Node.js, not Workers                                                                                                                  |
+| Secrets            | `wrangler secret put MY_SECRET`                                                    | Storing secrets in `[vars]`       | `[vars]` are visible in plaintext in the dashboard                                                                                                      |
 
 ## Verification Checklist
 
@@ -270,8 +313,8 @@ One DO per session holds a persistent transport so the `GET` notification stream
 
 **Deployment**
 
-- [ ] `wrangler dev` serves the MCP endpoint locally
-- [ ] `wrangler deploy` succeeds without errors
+- [ ] `npx wrangler dev` serves the MCP endpoint locally
+- [ ] `npx wrangler deploy` succeeds without errors
 - [ ] Health endpoint responds with 200
 
 **Runtime**

package/catalog/frontmcp-development/examples/create-plugin-hooks/caching-with-around.md

@@ -30,21 +30,22 @@ export class CachePlugin {
 
   @Around('execute', { priority: 90 })
   async cacheResults(ctx, next) {
-    const key = `${ctx.toolName}:${JSON.stringify(ctx.input)}`;
+    const { name, arguments: toolArguments } = ctx.state.required.input;
+    const key = `${name}:${JSON.stringify(toolArguments)}`;
+    const toolContext = ctx.state.required.toolContext;
     const cached = this.cache.get(key);
 
     if (cached && cached.expiry > Date.now()) {
-      return cached.data;
+      toolContext.output = cached.data;
+      return; // not calling next() skips the execute stage
     }
 
-    const result = await next();
+    await next(); // resolves with no value; the result is on toolContext.output
 
     this.cache.set(key, {
-      data: result,
+      data: toolContext.output,
       expiry: Date.now() + 60_000,
     });
-
-    return result;
   }
 }
 ```

package/catalog/frontmcp-development/examples/official-plugins/production-multi-plugin-setup.md

@@ -24,7 +24,7 @@ Demonstrates a production-ready server configuration combining CodeCall, Remembe
 
 ```typescript
 // src/server.ts
-import { ApprovalPlugin } from '@frontmcp/plugin-approval';
+import { ApprovalPlugin, ApprovalScope } from '@frontmcp/plugin-approval';
 import CachePlugin from '@frontmcp/plugin-cache';
 import CodeCallPlugin from '@frontmcp/plugin-codecall';
 import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
@@ -100,7 +100,7 @@ import { Tool, ToolContext, z } from '@frontmcp/sdk';
   },
   approval: {
     required: true,
-    defaultScope: 'session',
+    defaultScope: ApprovalScope.SESSION,
     category: 'write',
     riskLevel: 'high',
     approvalMessage: 'Allow data deletion for this session?',

package/catalog/frontmcp-development/references/create-job.md

@@ -268,7 +268,7 @@ Control who can interact with jobs using the `permissions` field. **`permissions
 
 **Requires 1.7.2 or later.** Before 1.7.2 (GHSA-58v2-gpcc-jmqv) the `permissions` array was validated and stored but never evaluated — every job was reachable by every caller who could reach `execute_job`. On older versions do not rely on this field for access control.
 
-Semantics: no rules for an action means allow (the documented default); once any rule targets an action, **all** rules for that action must pass, and `roles`/`scopes` within a single rule are **any-of**. Enforcement happens in `JobExecutionManager`, so background runs and workflow steps are covered, and `list_jobs` hides entries the caller could not run. A denial is indistinguishable from "not found" so restricted job names cannot be enumerated.
+Semantics: no rules for an action means allow (the documented default); once any rule targets an action, **all** rules for that action must pass, and `roles`/`scopes` within a single rule are **any-of**. A directly executed job is checked in `JobExecutionManager` (the `execute_job` tool, triggers, background runs); a job reached as a workflow step is checked against its own rules in `WorkflowStepExecutor`, so authorizing the workflow does not launder the jobs it references. `list_jobs` hides entries the caller could not run, and a denial is indistinguishable from "not found" so restricted job names cannot be enumerated.
 
 ### Permission Rule Shape
 
@@ -333,7 +333,7 @@ class DataExportJob extends JobContext {
 
 ### Combining Permission Strategies
 
-Within a single rule, `roles`, `scopes`, and `custom` are additive -- all specified conditions must be met. Add additional entries to grant other actions (or alternative role/scope sets):
+Within a single rule, `roles`, `scopes`, and `custom` are additive -- all specified conditions must be met, while the list inside `roles` (or `scopes`) is any-of. Add one entry per action. Adding a SECOND entry for the same action makes the check stricter, not looser -- both rules must pass -- so express alternatives as a longer `roles`/`scopes` list within one rule, never as an extra entry:
 
 ```typescript
 permissions: [