@frontmcp/skills 1.8.6 → 1.9.0

package/catalog/frontmcp-config/references/configure-deployment-targets.md

@@ -122,14 +122,44 @@ frontmcp build --target vercel
 | `sdk`         | Direct           | Configurable          | Library embedding       |
 | `mcpb`        | stdio            | SQLite, memory        | `.mcpb` MCP bundles     |
 
+### How the settings reach the server
+
+`frontmcp build` writes each target's `server` block (and `env`) into the artifact as environment
+defaults the server reads at start-up — only where the variable is not already set (an operator's env var
+wins), and an explicit `@FrontMcp()` value wins over both:
+
+| Setting                         | Variable                                                        | Applies to                                          |
+| ------------------------------- | --------------------------------------------------------------- | --------------------------------------------------- |
+| `server.http.port`              | `PORT`                                                          | `node`, `distributed` (serverless: ignored, warns)  |
+| `server.http.socketPath`        | `FRONTMCP_DAEMON_SOCKET`                                        | `node`, `distributed`                               |
+| `server.http.entryPath`         | `FRONTMCP_HTTP_ENTRY_PATH` (wins over `transport.http.path`)    | every server target                                 |
+| `server.http.cors`              | `FRONTMCP_CORS_ORIGINS` (JSON list), `_CREDENTIALS`, `_MAX_AGE` | every server target                                 |
+| `server.cookies`                | `FRONTMCP_AFFINITY_COOKIE`, `_DOMAIN`, `_SAMESITE`              | `distributed` (sets the LB affinity cookie)         |
+| `server.csp` / `server.headers` | `FRONTMCP_CSP_*`, `FRONTMCP_HSTS`, …                            | every server target                                 |
+| `deployments[].env`             | each key as is                                                  | every target except the `browser` / `sdk` libraries |
+
+`node` / `cli` / `mcpb` bundles set them in a preamble when run as the program; `vercel` / `lambda` /
+`cloudflare` / `distributed` in the generated setup module. Every artifact also sets
+`globalThis.FRONTMCP_BUILD_TARGET` for `availableWhen: { target }` (first one to run wins).
+
 ### Server HTTP Options
 
-| Field          | Type     | Default | Description                  |
-| -------------- | -------- | ------- | ---------------------------- |
-| `port`         | number   | 3000    | Listen port                  |
-| `socketPath`   | string   | ---     | Unix socket (overrides port) |
-| `entryPath`    | string   | `/`     | Base path                    |
-| `cors.origins` | string[] | ---     | CORS allowed origins         |
+| Field          | Type     | Default | Description                                                                       |
+| -------------- | -------- | ------- | --------------------------------------------------------------------------------- |
+| `port`         | number   | 3000    | Listen port (node / distributed)                                                  |
+| `socketPath`   | string   | ---     | Unix socket (overrides port; node / distributed)                                  |
+| `entryPath`    | string   | `/`     | Base path; wins over `transport.http.path` for this deployment                    |
+| `cors.origins` | string[] | ---     | CORS allowed origins (`['*']` = any); none = no CORS headers (the server default) |
+
+`bodyLimit` / `urlencodedLimit` are not `frontmcp.config` fields — set them in `@FrontMcp({ http })`.
+
+### Cookie Options (distributed LB affinity cookie)
+
+| Field      | Default           | Description        |
+| ---------- | ----------------- | ------------------ |
+| `affinity` | `__frontmcp_node` | Cookie name        |
+| `domain`   | ---               | `Domain` attribute |
+| `sameSite` | `'Strict'`        | `SameSite`         |
 
 ### CSP Options
 
@@ -157,6 +187,8 @@ frontmcp build --target vercel
 | `takeoverGracePeriodMs` | number | 5000      | Grace period before takeover |
 | `redisKeyPrefix`        | string | `mcp:ha:` | Redis key prefix             |
 
+The build writes these to `FRONTMCP_HA_HEARTBEAT_INTERVAL_MS`, `FRONTMCP_HA_HEARTBEAT_TTL_MS`, `FRONTMCP_HA_TAKEOVER_GRACE_MS` and `FRONTMCP_HA_KEY_PREFIX` in the generated setup file (only where the platform has not set them), which every pod reads at startup.
+
 ### Project-Defined CLI Commands (`cli.commands`)
 
 Register project-specific verbs that ship alongside the built-in
@@ -217,6 +249,8 @@ Per-invocation precedence (issue #400):
 3. Upward walk from `cwd` to the nearest ancestor containing a `frontmcp.config.*` (caps at 10 levels — monorepo nested apps work without `cd <repo-root>`).
 4. Fallback: `package.json` (derives name, default node target).
 
+When the upward walk finds the file in a **parent** folder, `frontmcp build` and `frontmcp dev` run from that folder (the project root): `entry`, `deployments[].outDir`, `tsconfig.json`, `package.json` and `.env` resolve there, so building from `src/` writes `dist/` next to the config. Paths passed as flags (`--entry`, `--out-dir`, `--icon`, `--merge-from`, `--log-file`) still resolve from the folder the command ran in. An explicit `--config` / `FRONTMCP_CONFIG` does not change the working folder.
+
 Within a directory:
 
 1. `frontmcp.config.ts`
@@ -230,25 +264,43 @@ Within a directory:
 For every CLI option that's also expressible in the config:
 
 ```
-explicit CLI flag  >  FRONTMCP_<NAME> env var  >  frontmcp.config field  >  built-in default
+explicit CLI flag  >  frontmcp.config field  >  built-in default
 ```
 
+There are no per-field `FRONTMCP_<NAME>` environment overrides. The only environment variable the CLI reads for configuration is `FRONTMCP_CONFIG`, which selects the config file (an explicit `--config <path>` flag wins over it).
+
 ## Per-command consumption (issue #400)
 
 The config is consumed by every `frontmcp` command, not just `build`:
 
-| Command                           | Config fields consumed                                                                              |
-| --------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `build`                           | `name`, `version`, `entry`, `deployments`, `build`, `nodeVersion`                                   |
-| `dev`                             | `entry`, `transport.http.port`, `env.shared` ⊕ `env.dev`                                            |
-| `test`                            | `test.timeoutMs` / `test.runInBand` / `test.coverage` / `test.testMatch`, `env.shared` ⊕ `env.test` |
-| `inspector`                       | `transport.default`, `transport.http.port`, `transport.stdio`                                       |
-| `pm start` / `socket` / `service` | `name`, `entry`, `transport.http.port`, `transport.http.socketPath`, `env.shared` ⊕ `env.ship`      |
-| `skills install` / `export`       | `skills.provider`, `skills.bundle`, `skills.install`, `skills.exportTarget`                         |
-| `eject-mcp-config <client>`       | `clients.<client>`, `name`, `transport`, `env.ship`                                                 |
+| Command                           | Config fields consumed                                                                                              |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `build`                           | `name`, `version`, `entry`, `deployments` (incl. `server`, `env`), `build`, `nodeVersion`, `transport.http.path`    |
+| `dev`                             | `entry`, `transport.http.port`, `env.shared` ⊕ `env.dev`, first deployment's `server.csp` / `headers` / `http.cors` |
+| `test`                            | `test.timeoutMs` / `test.runInBand` / `test.coverage` / `test.testMatch`, `env.shared` ⊕ `env.test`                 |
+| `inspector`                       | `transport.default`, `transport.http.port`, `transport.stdio`                                                       |
+| `pm start` / `socket` / `service` | `env.shared` ⊕ `env.ship` (config found from the entry's folder upwards; the real env wins)                         |
+| `skills install` / `export`       | `skills.provider`, `skills.install` (else `skills.bundle`; `'none'` = nothing), `skills.exportTarget` — flags win   |
+| `eject-mcp-config <client>`       | `clients.<client>`, `name`, `transport`, `env.shared` ⊕ `env.ship` (stdio `env`, under the client's own `env`)      |
 
 See `transport`, `env`, `clients`, `test`, `skills` field reference in [docs/frontmcp/deployment/frontmcp-config](https://docs.agentfront.dev/frontmcp/deployment/frontmcp-config).
 
+## `transport.http.path` for every build target
+
+`transport.http.path` is the mount path of the MCP endpoint for **every** build target, not only `frontmcp dev`:
+
+| Target                            | How the path reaches the server                                                                                                                                                                                |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `node` (and its SEA binary)       | the runner script exports `FRONTMCP_HTTP_ENTRY_PATH`, and the bundle sets the same default itself when run directly (`node dist/node/<name>.bundle.js`, the generated Dockerfile's `CMD`); a real env var wins |
+| `vercel`, `lambda`, `distributed` | the generated setup file assigns `process.env.FRONTMCP_HTTP_ENTRY_PATH` before the server loads                                                                                                                |
+| `cloudflare`                      | the generated worker setup assigns it the same way                                                                                                                                                             |
+
+A `@FrontMcp({ http: { entryPath } })` value still wins over the config. When the two differ, `frontmcp build` warns.
+
+## `eject-mcp-config --out` merges
+
+`--out` merges into an existing client config instead of replacing it: the parent folder is created when missing, other top-level keys and other `mcpServers` entries are kept, and only this server's entry is replaced. A file that is not valid JSON (or not a JSON object) is refused and left untouched. `--dry-run` prints the merged result and writes nothing.
+
 ## JSON Schema for IDE Support
 
 For JSON configs, add `$schema` for autocomplete:

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

@@ -137,7 +137,8 @@ until you name the public host, and the bound NIC address then joins the list al
 **Deployments behind a proxy need one line of config.** A routable bind (`0.0.0.0`, `::`, a specific
 NIC) is reached under a hostname the process cannot know, so a derived list is not enforced there —
 FrontMCP logs a warning and leaves host checking off rather than 403-ing a proxied deployment on a
-patch upgrade. Name the public host to turn it on:
+patch upgrade (the production security audit reports it as `DNS_REBINDING_NOT_ENFORCED`, and only says
+`DNS_REBINDING_PROTECTED` once a list is actually checked). Name the public host to turn it on:
 
 ```typescript
 http: {
@@ -163,7 +164,9 @@ there and needs no configuration. A rebound browser cannot reach a unix socket a
 **explicit** `allowedHosts` / `allowedOrigins` still applies to a socket server, and because the
 client's `Host` is a placeholder it will reject every request — leave it unset.
 
-To turn it off entirely: `dnsRebindingProtection: { enabled: false }`.
+To turn it off entirely: `dnsRebindingProtection: { enabled: false }`. It wins over any `allowedHosts` /
+`allowedOrigins` (and `FRONTMCP_ALLOWED_HOSTS`): no header is checked while it is set, so remove it to
+turn protection back on.
 
 A request with **no** `Origin` header is allowed through — non-browser clients never send one, and a
 rebound page always does. Rejecting the absent case breaks every CLI client and adds nothing.
@@ -260,10 +263,12 @@ http: {
 }
 ```
 
-| Option            | Type               | Default                   | Notes                                                                  |
-| ----------------- | ------------------ | ------------------------- | ---------------------------------------------------------------------- |
-| `bodyLimit`       | `number \| string` | `'4mb'`                   | Bytes (number) or body-parser string (`'4mb'`, `'500kb'`, `'2gb'`, …). |
-| `urlencodedLimit` | `number \| string` | falls back to `bodyLimit` | Independent override for `application/x-www-form-urlencoded` bodies.   |
+| Option            | Type               | Default                   | Notes                                                                                    |
+| ----------------- | ------------------ | ------------------------- | ---------------------------------------------------------------------------------------- |
+| `bodyLimit`       | `number \| string` | `'4mb'`                   | Bytes (number) or body-parser string (`'4mb'`, `'500kb'`, `'2gb'`, …).                   |
+| `urlencodedLimit` | `number \| string` | falls back to `bodyLimit` | Independent override for `application/x-www-form-urlencoded` bodies (Express host only). |
+
+The fetch handler used on Cloudflare Workers, Vercel Edge and Deno enforces `bodyLimit` too: it answers 413 for an oversized `Content-Length` without reading the body and stops reading a chunked body at the limit.
 
 Requests exceeding the configured limit receive a structured JSON-RPC 413
 response — never an Express HTML error page:

package/catalog/frontmcp-config/references/configure-security-headers.md

@@ -5,7 +5,7 @@ description: Configure CSP, HSTS, X-Frame-Options, and X-Content-Type-Options vi
 
 # Configure Security Headers
 
-Set Content Security Policy (CSP), HSTS, and other security headers on every HTTP response. Configure them in `frontmcp.config` per deployment target — the build adapter injects them as environment variables that the built-in middleware reads at runtime.
+Set Content Security Policy (CSP), HSTS, and other security headers on every HTTP response. Configure them in `frontmcp.config` per deployment target — `frontmcp dev` and the `cloudflare`, `vercel`, `lambda` and `distributed` builds pass them to the server as `FRONTMCP_*` environment variables (set only when the platform has not already defined them). The `node` target has no setup file: set the variables where the server runs or use `@FrontMcp({ http: { securityHeaders } })`. `X-Content-Type-Options: nosniff` and `X-Frame-Options: DENY` are on by default and `X-Powered-By` is never sent; the Express host and the Workers/Vercel Edge fetch handler share one resolver.
 
 ## When to Use This Skill
 
@@ -109,7 +109,9 @@ curl -I http://localhost:3000/healthz
 | `frameOptions`       | `string \| false`       | `DENY`    | `X-Frame-Options`           |
 | `custom`             | `Record<string,string>` | ---       | Any custom headers          |
 
-Set any of the first three fields to `false` to explicitly disable that header.
+Set any of the first three fields to `false` to omit that header (env var value: `off`).
+
+The same settings work on the decorator: `@FrontMcp({ http: { securityHeaders: { hsts, contentTypeOptions, frameOptions, csp, custom } } })`. Precedence: decorator, then `FRONTMCP_*` variables, then defaults.
 
 ### Value-Less CSP Directives
 
@@ -137,17 +139,20 @@ csp: {
 
 ### Environment Variables
 
-The build adapter converts config to these env vars (can also be overridden at runtime):
-
-| Variable                        | Config Path                          |
-| ------------------------------- | ------------------------------------ |
-| `FRONTMCP_CSP_ENABLED`          | `server.csp.enabled`                 |
-| `FRONTMCP_CSP_DIRECTIVES`       | `server.csp.directives` (serialized) |
-| `FRONTMCP_CSP_REPORT_URI`       | `server.csp.reportUri`               |
-| `FRONTMCP_CSP_REPORT_ONLY`      | `server.csp.reportOnly`              |
-| `FRONTMCP_HSTS`                 | `server.headers.hsts`                |
-| `FRONTMCP_CONTENT_TYPE_OPTIONS` | `server.headers.contentTypeOptions`  |
-| `FRONTMCP_FRAME_OPTIONS`        | `server.headers.frameOptions`        |
+The CLI converts config to these env vars for `dev` and the serverless/distributed builds (you can also set them yourself at runtime):
+
+| Variable                        | Config Path                           |
+| ------------------------------- | ------------------------------------- |
+| `FRONTMCP_CSP_ENABLED`          | `server.csp.enabled`                  |
+| `FRONTMCP_CSP_DIRECTIVES`       | `server.csp.directives` (serialized)  |
+| `FRONTMCP_CSP_REPORT_URI`       | `server.csp.reportUri`                |
+| `FRONTMCP_CSP_REPORT_ONLY`      | `server.csp.reportOnly`               |
+| `FRONTMCP_HSTS`                 | `server.headers.hsts`                 |
+| `FRONTMCP_CONTENT_TYPE_OPTIONS` | `server.headers.contentTypeOptions`   |
+| `FRONTMCP_FRAME_OPTIONS`        | `server.headers.frameOptions`         |
+| `FRONTMCP_HEADERS_CUSTOM`       | `server.headers.custom` (JSON object) |
+
+`off`, `false` or `none` in `FRONTMCP_HSTS`, `FRONTMCP_CONTENT_TYPE_OPTIONS` or `FRONTMCP_FRAME_OPTIONS` omits that header.
 
 ## Common Patterns
 

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

@@ -21,9 +21,9 @@ interface GuardConfig {
       | { url: string };
     vercelKv?: { url?: string; token?: string };
     upstash?: { url?: string; token?: string };
-    // What to do when the backend is unreachable at startup:
-    // 'error' (default in production) -- startup fails with GuardStorageUnavailableError (rate limits fail closed)
-    // 'memory' (default otherwise)   -- start with per-instance counters
+    // What to do when the backend is unreachable, at startup or while running:
+    // 'error' (default in production) -- startup fails, and a limited call is refused, with GuardStorageUnavailableError (rate limits fail closed)
+    // 'memory' (default otherwise)   -- use per-instance counters (and go back to the backend once it answers)
     fallback?: 'error' | 'memory';
   };
 
@@ -69,7 +69,7 @@ interface IpFilterConfig {
 
 ## Storage Failure and Key Format
 
-- **Fails closed.** When `storage` cannot be reached at startup, the server does not start: startup rejects with `GuardStorageUnavailableError` (code `GUARD_STORAGE_UNAVAILABLE`), whose message names `throttle.storage`. That is the default in production. Set `storage.fallback: 'memory'` to start with per-instance counters instead. (The top-level `redis` and `transport.persistence` differ: they fall back to memory with an error log.)
+- **Fails closed.** When `storage` cannot be reached at startup, the server does not start: startup rejects with `GuardStorageUnavailableError` (code `GUARD_STORAGE_UNAVAILABLE`), whose message names `throttle.storage`. That is the default in production. If the backend goes away while the server runs, a limited call is refused with the same error, not `Internal FrontMCP error`: the `global` check answers HTTP 503 (`Retry-After: 1`, JSON-RPC `data.code: 'GUARD_STORAGE_UNAVAILABLE'`); a per-tool limit inside `tools/call` answers an `isError` result (HTTP 200, as MCP returns tool-level failures) with `_meta.code: 'GUARD_STORAGE_UNAVAILABLE'`. The client reads a generic "temporarily unavailable" message; the store address stays in the server log. Set `storage.fallback: 'memory'` to use per-instance counters instead; a mid-run outage then logs one warning and the backend is retried every 30 seconds. (The top-level `redis` and `transport.persistence` differ: they fall back to memory with an error log.)
 - **Keys.** `<keyPrefix><entity>:<partition>:<kind>:...`, e.g. `mcp:guard:export_tickets:global:rl:1790722980000`. Before 1.8.6 the default prefix wrote `mcp:guard::export_tickets:...`; old and new instances do not read each other's counters, so limits briefly split during a rolling deploy. A custom `keyPrefix` without a trailing `:` keeps its keys.
 
 ## Partition Strategies

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 (a tool called with this.callTool() runs inside its caller's slot)
+    // Global concurrency limit (a tool called with this.callTool(), or by an agent during its run, runs inside its caller's slot)
     globalConcurrency: {
       maxConcurrent: 50,
       partitionBy: 'global',
@@ -112,6 +112,8 @@ class ExpensiveQueryTool extends ToolContext {
 }
 ```
 
+A tool's own `rateLimit` and `concurrency` are enforced without a `throttle` option, as are those of an agent, of the tools declared inside an `@Agent` and of its nested agents. `throttle.enabled: false` turns every guard off, including these.
+
 ## `ipFilter` is enforced on every HTTP route
 
 `allowList`, `denyList` and `defaultAction` are checked by the `checkIpFilter` stage that starts
@@ -246,7 +248,7 @@ throttle: {
 
 `storage` is a `StorageConfig` from `@frontmcp/utils` -- `type` picks the backend, and its options go under the matching key (`redis: { config }` or `redis: { url }`, `vercelKv: { url, token }`, `upstash: { url, token }`). It is NOT the top-level `redis` shape: `{ provider: 'redis', host, port }` has no `type`, so it is auto-detected from `REDIS_URL` / `REDIS_HOST` and otherwise runs in memory.
 
-**Rate limits fail closed.** If the store is unreachable at startup, the server does not start: startup rejects with `GuardStorageUnavailableError` (`throttle.storage (redis) is unavailable: ...`), the default in production. To start with per-instance counters instead, opt in:
+**Rate limits fail closed.** If the store is unreachable at startup, the server does not start: startup rejects with `GuardStorageUnavailableError` (`throttle.storage (redis) is unavailable: ...`), the default in production. If the store goes away while the server is running, a limited call is refused with the same error rather than `Internal FrontMCP error` (HTTP 503 from the `global` check; an `isError` result with `_meta.code: 'GUARD_STORAGE_UNAVAILABLE'` from a per-tool limit inside `tools/call`). To use per-instance counters instead (at startup and during a mid-run outage, going back to the store once it answers), opt in:
 
 ```typescript
 storage: {

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

@@ -35,7 +35,6 @@ Configure how clients connect to your FrontMCP server — SSE, Streamable HTTP,
   info: { name: 'my-server', version: '1.0.0' },
   apps: [MyApp],
   transport: {
-    sessionMode: 'stateful', // 'stateful' | 'stateless'
     protocol: 'legacy', // preset or custom ProtocolConfig
     persistence: {
       // false to disable
@@ -157,7 +156,7 @@ curl -X POST http://localhost:3000/ -H 'Content-Type: application/json' -d '{"js
 | Pattern              | Correct                                                                          | Incorrect                                                  | Why                                                                                |
 | -------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | Choosing a preset    | `protocol: 'modern'`                                                             | `protocol: { sse: true, streamable: true, legacy: false }` | Use a preset when it matches your needs; custom config is for overrides only       |
-| Serverless transport | `protocol: 'stateless-api'` with `sessionMode: 'stateless'`                      | `protocol: 'legacy'` on Lambda                             | Legacy preset creates sessions that serverless cannot maintain between invocations |
+| Serverless transport | `protocol: 'stateless-api'`                                                      | `protocol: 'legacy'` on Lambda                             | Legacy preset creates sessions that serverless cannot maintain between invocations |
 | Distributed sessions | `distributedMode: true` with Redis `persistence` configured                      | `distributedMode: true` without Redis                      | Distributed mode requires Redis; omitting it causes a startup error                |
 | Event store provider | `provider: 'redis'` for multi-instance, `provider: 'memory'` for single instance | `provider: 'memory'` behind a load balancer                | In-memory event store is not shared across instances, breaking SSE resumability    |
 | Session TTL          | Set `defaultTtlMs` to match your expected session duration                       | Omitting `defaultTtlMs` when using Redis persistence       | Missing TTL can cause sessions to accumulate indefinitely in Redis                 |
@@ -167,12 +166,12 @@ curl -X POST http://localhost:3000/ -H 'Content-Type: application/json' -d '{"js
 ### Transport Protocol
 
 - [ ] Correct preset is chosen for the deployment target (see Target-Specific Recommendations table)
-- [ ] Custom protocol flags, if used, do not conflict with the selected `sessionMode`
+- [ ] Custom protocol flags, if used, match whether the server should keep sessions (`stateless: true` serves without them)
 - [ ] Legacy SSE is disabled when all clients support modern MCP protocol
 
 ### Session and Persistence
 
-- [ ] `sessionMode` is `'stateless'` for serverless deployments
+- [ ] `protocol` is `'stateless-api'` for serverless deployments (sessions follow `protocol`; `sessionMode` has no effect and logs a startup warning when set to anything but `'stateful'`)
 - [ ] `distributedMode` is enabled and Redis is configured for multi-instance deployments
 - [ ] `defaultTtlMs` is set to a reasonable value when persistence is enabled
 
@@ -196,7 +195,7 @@ curl -X POST http://localhost:3000/ -H 'Content-Type: application/json' -d '{"js
 | Server rejects SSE connections         | SSE is disabled in the protocol config or preset                           | Switch to `'legacy'`, `'modern'`, or `'full'` preset, or set `sse: true` in custom config  |
 | `distributedMode` startup error        | Redis persistence is not configured                                        | Add a `persistence.redis` block with valid connection details                              |
 | Clients lose state after reconnect     | Event store is disabled or using in-memory provider behind a load balancer | Enable event store with `provider: 'redis'` for distributed deployments                    |
-| Serverless function times out on SSE   | Using a stateful preset on a serverless target                             | Switch to `'stateless-api'` preset and set `sessionMode: 'stateless'`                      |
+| Serverless function times out on SSE   | Using a stateful preset on a serverless target                             | Switch to the `'stateless-api'` preset                                                     |
 | Session not found after server restart | In-memory sessions do not survive restarts                                 | Enable Redis persistence with `distributedMode: true`                                      |
 | Streamable HTTP returns 404            | Streamable HTTP is not enabled in the current preset                       | Use `'modern'`, `'legacy'`, or `'full'` preset, or set `streamable: true` in custom config |
 

package/catalog/frontmcp-deployment/SKILL.md

@@ -73,25 +73,25 @@ Entry point for deploying and building FrontMCP servers. This skill helps you ch
 
 Beyond `frontmcp build`, the CLI provides commands for the full deployment lifecycle:
 
-| Command                      | Description                                                                         |
-| ---------------------------- | ----------------------------------------------------------------------------------- |
-| `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                                                              |
-| `frontmcp status [name]`     | Show process status (detail if name given, table if omitted)                        |
-| `frontmcp list`              | List all managed processes                                                          |
-| `frontmcp logs <name>`       | Tail log output (`-F` follow, `-n` lines)                                           |
-| `frontmcp socket <entry>`    | Start Unix socket daemon for local MCP server                                       |
-| `frontmcp service <action>`  | Install/uninstall systemd (Linux) or launchd (macOS) service                        |
-| `frontmcp install <source>`  | Install MCP app from npm, local path, or git                                        |
-| `frontmcp uninstall <name>`  | Remove installed MCP app                                                            |
-| `frontmcp configure <name>`  | Re-run setup questionnaire for installed app                                        |
-| `frontmcp doctor`            | Check Node.js/npm versions and tsconfig requirements                                |
-| `frontmcp inspector`         | Launch MCP Inspector for debugging                                                  |
-| `frontmcp init`              | Create or fix tsconfig.json for FrontMCP                                            |
+| Command                      | Description                                                                                                                                                                                                                                                                                                                                 |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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                                                                                                                                                                                                                                                                                                                      |
+| `frontmcp status [name]`     | Show process status (detail if name given, table if omitted)                                                                                                                                                                                                                                                                                |
+| `frontmcp list`              | List all managed processes                                                                                                                                                                                                                                                                                                                  |
+| `frontmcp logs <name>`       | Tail log output (`-F` follow, `-n` lines)                                                                                                                                                                                                                                                                                                   |
+| `frontmcp socket <entry>`    | Start Unix socket daemon for local MCP server                                                                                                                                                                                                                                                                                               |
+| `frontmcp service <action>`  | Install/uninstall systemd (Linux) or launchd (macOS) service                                                                                                                                                                                                                                                                                |
+| `frontmcp install <source>`  | Install MCP app from npm, local path, git, or a project's `dist/` / `dist/node` (`dist/node` wins over other targets; installs the external runtime packages plus `vectoriadb`/`tslib` and optional SDK peers the project declares, those in `optionalDependencies` as optional; `frontmcp start <name>` then runs it from its install dir) |
+| `frontmcp uninstall <name>`  | Remove installed MCP app                                                                                                                                                                                                                                                                                                                    |
+| `frontmcp configure <name>`  | Re-run setup questionnaire for installed app                                                                                                                                                                                                                                                                                                |
+| `frontmcp doctor`            | Check Node.js/npm versions and tsconfig requirements                                                                                                                                                                                                                                                                                        |
+| `frontmcp inspector`         | Launch MCP Inspector for debugging                                                                                                                                                                                                                                                                                                          |
+| `frontmcp init`              | Create or fix tsconfig.json for FrontMCP (edits in place, keeps comments; never overwrites a file it cannot parse or that declares a required option twice)                                                                                                                                                                                 |
 
 ## Target Comparison
 

package/catalog/frontmcp-deployment/examples/build-for-browser/react-provider-setup.md

@@ -23,7 +23,7 @@ Connect a React application to a FrontMCP server using `@frontmcp/react`. `Front
 
 ```typescript
 // src/server.ts — create a DirectMcpServer (in-memory) for the React app to consume.
-import { create, tool, z } from '@frontmcp/sdk';
+import { create, tool, z } from '@frontmcp/react'; // `z` is re-exported; `@frontmcp/sdk` works too
 
 export const server = await create({
   info: { name: 'browser-app', version: '1.0.0' },
@@ -70,10 +70,12 @@ function ToolUI() {
 // useCallTool requires the tool name as a hook arg, so each row owns its own
 // hook instance. The mutate fn takes just the arguments object — not `{ name, arguments }`.
 function ToolButton({ tool }: { tool: { name: string; description?: string } }) {
-  const [callTool] = useCallTool<{ name: string }>(tool.name);
+  const [callTool, { data }] = useCallTool<{ name: string }>(tool.name);
+  // `data` is the full CallToolResult; failures arrive as `data.isError`, not in `error`.
+  const text = data?.content?.[0]?.type === 'text' ? data.content[0].text : null;
   return (
     <button onClick={() => callTool({ name: 'World' })}>
-      {tool.name}: {tool.description}
+      {tool.name}: {tool.description} {data?.isError ? '(failed)' : text}
     </button>
   );
 }

package/catalog/frontmcp-deployment/examples/deploy-to-node/docker-compose-with-redis.md

@@ -79,7 +79,7 @@ RUN yarn install --frozen-lockfile --production && yarn cache clean
 EXPOSE 3000
 HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
   CMD wget -qO- http://localhost:3000/healthz || exit 1
-CMD ["node", "dist/main.js"]
+CMD ["node", "dist/node/my-server.bundle.js"]
 ```
 
 ```bash

package/catalog/frontmcp-deployment/examples/deploy-to-node/pm2-with-nginx.md

@@ -24,7 +24,7 @@ frontmcp build --target node
 npm install -g pm2
 
 # Start with cluster mode (one instance per CPU core)
-pm2 start dist/main.js --name frontmcp-server -i max
+pm2 start dist/node/my-server.bundle.js --name frontmcp-server -i max
 
 # Save the process list for auto-restart on reboot
 pm2 save

package/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-kv.md

@@ -82,3 +82,5 @@ curl https://your-project.vercel.app/healthz
 ## Related
 
 - See `deploy-to-vercel` for KV provisioning, environment variables, and cold start optimization
+
+> **Tasks and elicitation on Vercel KV:** Vercel KV has no pub/sub, so background tasks and elicitation cannot use it. The server still starts — tasks are skipped with a `[tasks]` startup warning unless `tasks: { enabled: true }` is set (which keeps `TaskStoreNotSupportedError`), and elicitation throws `ElicitationNotSupportedError` only when its store actually resolves to Vercel KV. Give tasks their own backend with `tasks: { redis }` or `tasks: { sqlite }` (an explicit backend ignores the ambient `KV_REST_API_URL`).

package/catalog/frontmcp-deployment/references/build-for-browser.md

@@ -117,8 +117,44 @@ function ToolUI() {
 }
 ```
 
+Things that trip people up with `@frontmcp/react`:
+
+- A plain Vite app (7 or 8, build and dev server) bundles `@frontmcp/sdk` + `@frontmcp/react` from npm with no Node polyfills, no `process` define and no `express` alias: the bundler resolves the SDK's `browser` export condition to its browser build, for an `import` and for a CommonJS `require()` alike. Don't add `vite-plugin-node-polyfills` for FrontMCP.
+- With Vite 7 (Rollup), don't `await create()` at the top level of the entry module — call it from a function or `.then()`. Rollup can put modules the SDK imports lazily in a chunk that imports the entry back, and the top-level `await` then waits on itself.
+- Hook options may be written inline. `useStoreResource` / `useReduxResource` / `useValtioResource` and `useApiClient` register again only when the store name, the server, the set of selector / action names (not their order), or what an API operation declares changes; functions are read from the latest render.
+- `useApiClient` sends the arguments an operation declares `in: 'query'` as the query string and `in: 'header'` as headers. `parseOpenApiSpec` fills `operation.parameters`; a hand-written operation lists them itself (`parameters: [{ name: 'limit', in: 'query' }]`), or its non-path, non-`body` arguments are not sent. Arrays and objects follow the parameter's OpenAPI `style` / `explode` (which `parseOpenApiSpec` keeps): a query array repeats the key and a query object sends each property as its own parameter by default (`spaceDelimited`, `pipeDelimited` and `deepObject` are honored); a header array or object is comma-separated.
+- `ToolForm` shows an optional enum without a default as unset (an empty choice), and leaves it out of the arguments until the user picks a value.
+
+- `useCallTool`'s `data` is the whole MCP `CallToolResult` (`content`, `structuredContent`, `isError`), not the tool's return value. Render `data.structuredContent ?? data.content`, never `String(data)`. A tool-side failure resolves with `data.isError === true`; `error` is only set when the call throws (for example when the client is not connected).
+- `z` is re-exported from `@frontmcp/react`, but `zod` remains a required peer dependency of `@frontmcp/lazy-zod` and must be installed in the consuming project.
+- `create({ resources })` takes `@Resource` classes or `resource(...)(handler)` / `resourceTemplate(...)(handler)` values. A plain `{ uri, name, read }` object is rejected with "Expected a class or a resource function".
+- The subpath entries (`@frontmcp/react/state`, `/api`, `/ai`, `/router`) share the root entry's provider and server registry, so `useStoreResource`, `useApiClient`, `useAITools` and `useTools` register against the same `FrontMcpProvider`.
+- `createRouterEntries()` from `@frontmcp/react/router` returns `{ tools, resources }` that go straight into `create({ tools, resources })`.
+
 For connecting to a remote MCP server (HTTP), create a server-bound `DirectMcpServer` via `connect()` from `@frontmcp/sdk` and pass that instance to the provider.
 
+- `useDynamicTool` registers a **real server tool** (through `server.registerTool()`), so it runs through the server's flows (plugin hooks, authorities, `availableWhen`) and every client sees it. A name a server tool already has is refused and reported through the provider's `onError` (or `console.warn`) — it no longer shadows the server tool; registering it again (a remount) retries it. The provider's tool listing follows the server's `notifications/tools/list_changed`. On a server with several local apps (`FrontMcpInstance.createDirect({ apps: [...] })`) every dynamic tool must say which app it joins: once per server with `<FrontMcpProvider dynamicToolApps={{ default: 'browser' }}>` (keyed by server name; covers `useDynamicTool`, `mcpComponent`, store actions and `useApiClient`), or per tool with `useDynamicTool({ app })`. A `create()` server has one app, so neither is needed.
+- Page code can add tools to the running server: `const unregister = await server.registerTool({ name, description, inputSchema, execute })`. The tool joins the server's app, so it is listed and run through the server's flows (plugin hooks, authorities, `availableWhen`). Arguments are not validated against `inputSchema` — validate in `execute`. `execute` runs outside the request's turn, so it may call the server back. A taken name rejects with `ToolNameConflictError`; names are 1–64 characters.
+- `registerTool()` checks the definition before adding it: `inputSchema` must be an object schema (`type: 'object'`), and a non-string `title`/`description` or malformed `annotations`/`availableWhen` rejects with `EntryValidationError` instead of breaking `tools/list` for every tool. Registering on a disposed server (or one disposed before the registration completes) rejects with `InternalMcpError`.
+
+## Exposing Tools to Browser Agents (WebMCP)
+
+Install `@frontmcp/plugin-webmcp` to register the page server's tools with WebMCP (`document.modelContext`), the API Gemini in Chrome and other in-browser agents use:
+
+```typescript
+import { WebMcpPlugin } from '@frontmcp/plugin-webmcp';
+
+const server = await create({
+  info: { name: 'shop', version: '1.0.0' },
+  tools: [SearchProducts, AddToCart],
+  plugins: [WebMcpPlugin.init({ prefix: 'shop.' })],
+});
+```
+
+- Every agent call runs `tools:call-tool` on the `'webmcp'` surface; use `availableWhen: { surface: ['webmcp'] }` for agent-only tools and `['mcp']` to keep a tool away from browser agents.
+- Tools added later (`server.registerTool()`, `useDynamicTool`) are registered automatically; `server.dispose()` unregisters everything.
+- WebMCP is in origin trial (Chrome/Edge 149–162). Develop with `chrome://flags/#enable-webmcp-testing` and inspect with DevTools → Application → WebMCP. Without `document.modelContext` the plugin does nothing; load a polyfill such as `@mcp-b/global` for other browsers.
+
 ## Browser vs Node vs SDK Target
 
 | Aspect      | `--target browser` | `--target node`   | `--target sdk`      |
@@ -171,15 +207,16 @@ ls dist/browser/
 
 ## Troubleshooting
 
-| Problem                     | Cause                                     | Solution                                                         |
-| --------------------------- | ----------------------------------------- | ---------------------------------------------------------------- |
-| `Module not found: fs`      | Node.js module imported in browser bundle | Use a separate browser entry point that avoids Node-only imports |
-| `crypto is not defined`     | Using `node:crypto` instead of WebCrypto  | Switch to `@frontmcp/utils` crypto functions                     |
-| CORS errors on tool calls   | MCP server missing CORS headers           | Configure CORS middleware on the MCP server                      |
-| Bundle too large            | All server-side code included             | Use `--target browser` and a dedicated client entry file         |
-| `@frontmcp/utils` fs throws | File system ops called in browser         | Remove fs calls; use API endpoints or in-memory alternatives     |
-| `AsyncContextOverlapError`  | Concurrent tool calls inside one request  | Await the calls one after another (no `AsyncContext` in browser) |
-| A call never returns        | A tool calls its own server via a client  | Call other tools through `this.scope` flows                      |
+| Problem                           | Cause                                          | Solution                                                         |
+| --------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
+| `Module not found: fs`            | Node.js module imported in browser bundle      | Use a separate browser entry point that avoids Node-only imports |
+| `crypto is not defined`           | Using `node:crypto` instead of WebCrypto       | Switch to `@frontmcp/utils` crypto functions                     |
+| CORS errors on tool calls         | MCP server missing CORS headers                | Configure CORS middleware on the MCP server                      |
+| Bundle too large                  | All server-side code included                  | Use `--target browser` and a dedicated client entry file         |
+| `@frontmcp/utils` fs throws       | File system ops called in browser              | Remove fs calls; use API endpoints or in-memory alternatives     |
+| `AsyncContextOverlapError`        | Concurrent tool calls inside one request       | Await the calls one after another (no `AsyncContext` in browser) |
+| A call never returns              | A tool calls its own server via a client       | Call other tools through `this.scope` flows                      |
+| `create()` never settles (Vite 7) | Top-level `await create()` in the entry module | Call `create()` from a function or `.then()`                     |
 
 ## Examples
 

package/catalog/frontmcp-deployment/references/build-for-mcpb.md

@@ -65,6 +65,11 @@ frontmcp mcpb validate dist/mcpb/my-server-1.0.0.mcpb
 - `@frontmcp/sdk` must be installed and reachable at the path used by the
   build (never exclude it from bundling).
 - For `--sea` builds, Node.js ≥ 24 is required (FrontMCP targets the current SEA API).
+- The SEA binary is self-contained like `server/index.js` (FrontMCP runtime and
+  `reflect-metadata` inlined): an SEA binary resolves a bare `require()` against
+  Node's built-ins only. Smoke-test it from the extracted archive with
+  `FRONTMCP_STDIO=1 ./bin/<platform>/<name>`; `frontmcp mcpb validate` flags a
+  binary that still `require()`s a runtime package.
 
 ## What the Archive Contains
 
@@ -174,14 +179,16 @@ bundled JS, so a partial matrix is fine.
 
 ## Troubleshooting
 
-| Problem                                                | Cause                                                          | Solution                                                                                                                    |
-| ------------------------------------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `@frontmcp/sdk is required for schema extraction`      | SDK missing or externalized from bundle                        | Ensure `@frontmcp/sdk` is installed                                                                                         |
-| Archive > 100 MB                                       | node_modules bundled or node runtime bloated                   | Tune `build.esbuild.external`, drop `--sea`, or disable `includeNodeModules`                                                |
-| `Unknown substitution variable` on validate            | Typo in `mcp_config.args` / `env`                              | Only `__dirname`, `HOME`, `DESKTOP`, `DOCUMENTS`, `DOWNLOADS`, `pathSeparator`, and declared `user_config` keys are allowed |
-| `entry_point is not present in archive`                | Custom `--entry` flag or bundler moved the file                | Re-run without the override, or update the config's `entry`                                                                 |
-| Two builds produce different SHA-256                   | `--no-deterministic` set, or inputs embed a changing timestamp | Restore deterministic mode; scan your sources for live date/time values                                                     |
-| `platform_overrides.{platform}.command` missing binary | `--merge-from` folders don't match MCPB platform keys          | See the expected layout below                                                                                               |
+| Problem                                                                           | Cause                                                                                 | Solution                                                                                                                             |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `@frontmcp/sdk is required for schema extraction`                                 | SDK missing or externalized from bundle                                               | Ensure `@frontmcp/sdk` is installed                                                                                                  |
+| `… requires "@frontmcp/sdk" but the archive has no node_modules`                  | Server entry still `require()`s a runtime package                                     | Rebuild with `frontmcp build --target mcpb` so runtime packages are bundled; `validate` reports archives that are not self-contained |
+| `bin/… requires "reflect-metadata", which a single-executable binary cannot load` | SEA binary built with the runtime left external (dies with `No such built-in module`) | Rebuild with `frontmcp build --target mcpb --sea`                                                                                    |
+| Archive > 100 MB                                                                  | node_modules bundled or node runtime bloated                                          | Tune `build.esbuild.external`, drop `--sea`, or disable `includeNodeModules`                                                         |
+| `Unknown substitution variable` on validate                                       | Typo in `mcp_config.args` / `env`                                                     | Only `__dirname`, `HOME`, `DESKTOP`, `DOCUMENTS`, `DOWNLOADS`, `pathSeparator`, and declared `user_config` keys are allowed          |
+| `entry_point is not present in archive`                                           | Custom `--entry` flag or bundler moved the file                                       | Re-run without the override, or update the config's `entry`                                                                          |
+| Two builds produce different SHA-256                                              | `--no-deterministic` set, or inputs embed a changing timestamp                        | Restore deterministic mode; scan your sources for live date/time values                                                              |
+| `platform_overrides.{platform}.command` missing binary                            | `--merge-from` folders don't match MCPB platform keys                                 | See the expected layout below                                                                                                        |
 
 Expected `--merge-from` layout (platform dirs must match MCPB platform keys):
 

package/catalog/frontmcp-deployment/references/build-for-sdk.md

@@ -98,7 +98,8 @@ const server = await create({
 // Call tools directly
 const result = await server.callTool('calculate', { a: 2, b: 2, operation: 'add' });
 
-// List available tools
+// List available tools: every page is read, so this is the whole list (no `nextCursor`).
+// To page yourself: `listTools({ paginate: true })`, then `listTools({ cursor: page.nextCursor })`.
 const { tools } = await server.listTools();
 
 // Clean up
@@ -208,15 +209,15 @@ const client = await connectOpenAI(config, {
 
 All `connect*()` functions return a `DirectClient` with these methods:
 
-| Method                  | Description                            |
-| ----------------------- | -------------------------------------- |
-| `listTools()`           | List tools in platform-specific format |
-| `callTool(name, args)`  | Execute a tool                         |
-| `listResources()`       | List available resources               |
-| `readResource(uri)`     | Read a resource                        |
-| `listPrompts()`         | List available prompts                 |
-| `getPrompt(name, args)` | Get a prompt                           |
-| `close()`               | Clean up connection                    |
+| Method                  | Description                             |
+| ----------------------- | --------------------------------------- |
+| `listTools()`           | List tools in platform-specific format  |
+| `callTool(name, args)`  | Execute a tool                          |
+| `listResources()`       | List all resources (follows every page) |
+| `readResource(uri)`     | Read a resource                         |
+| `listPrompts()`         | List all prompts (follows every page)   |
+| `getPrompt(name, args)` | Get a prompt                            |
+| `close()`               | Clean up connection                     |
 
 ## SDK vs Node Target