@frontmcp/skills 1.8.5 → 1.8.7

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

@@ -11,13 +11,23 @@ description: Complete GuardConfig interface reference for rate limiting, concurr
 interface GuardConfig {
   enabled: boolean;
 
-  // Storage for distributed rate limiting
+  // Storage for distributed rate limiting -- a StorageConfig from @frontmcp/utils,
+  // NOT the top-level `redis` shape (a block without `type` is auto-detected
+  // from REDIS_URL / REDIS_HOST and otherwise runs in memory)
   storage?: {
-    type: 'memory' | 'redis';
-    redis?: RedisOptionsInput;
+    type?: 'memory' | 'redis' | 'vercel-kv' | 'upstash' | 'auto';
+    redis?:
+      | { config: { host: string; port?: number; password?: string; db?: number; tls?: boolean } }
+      | { url: string };
+    vercelKv?: { url?: string; token?: string };
+    upstash?: { url?: string; token?: string };
+    // 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';
   };
 
-  keyPrefix?: string; // default: 'mcp:guard:'
+  keyPrefix?: string; // default: 'mcp:guard:' -- a trailing ':' is dropped, keys read 'mcp:guard:<entity>:...'
 
   // Server-wide limits
   global?: RateLimitConfig;
@@ -57,6 +67,11 @@ 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. If the backend goes away while the server runs, a limited call is refused with the same error (a readable 503, not `Internal FrontMCP error`). 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
 
 - **`'global'`**: Single counter shared by all clients. Protects total server capacity.

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

@@ -244,6 +244,22 @@ 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. If the store goes away while the server is running, a limited call is refused with the same error rather than `Internal FrontMCP error`. 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: {
+  type: 'redis',
+  redis: { url: process.env['REDIS_URL'] },
+  fallback: 'memory',
+},
+```
+
+The top-level `redis` and `transport.persistence` behave differently: they fall back to in-memory storage with an error log.
+
+Keys are `<keyPrefix><entity>:<partition>:<kind>:...` (`mcp:guard:export_tickets:global:rl:...`); a trailing `:` on `keyPrefix` is dropped. Before 1.8.6 the default prefix wrote `mcp:guard::...`, so counters briefly split between versions during a rolling deploy.
+
 ## Verification
 
 ```bash
@@ -297,13 +313,15 @@ done
 
 ## 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, 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                                                               |
+| 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                                                               |
+| Startup fails with `GuardStorageUnavailableError` | The `throttle.storage` backend is unreachable; rate limits fail closed                                                                                                                                    | Bring the store up, or set `throttle.storage.fallback: 'memory'` to start with per-instance counters                                         |
+| Redis-backed limits still per-instance            | `storage` written in the top-level `redis` shape (`{ provider: 'redis', host }`) with no `type`, so it was auto-detected as memory                                                                        | Use `{ type: 'redis', redis: { config: { host, port } } }`                                                                                   |
+| 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

@@ -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` (installs external runtime packages; `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                                                                                                                                        |
 
 ## 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-vercel/vercel-mcp-endpoint-test.md

@@ -55,7 +55,7 @@ vercel --prod
 // `rewrites` keyed on `api/frontmcp.ts`/`.js` (no such file exists).
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install"
 }
 ```

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

@@ -53,7 +53,7 @@ export default class MyServer {}
 // buildCommand/installCommand are detected from your lockfile.
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install"
 }
 ```
@@ -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/examples/deploy-to-vercel/vercel-with-skills-cache.md

@@ -58,7 +58,7 @@ vercel env add LOG_LEVEL info
 // Do not add functions/rewrites referencing api/frontmcp.* (no such file).
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install"
 }
 ```

package/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/minimal-vercel-config.md

@@ -11,6 +11,7 @@ tags:
   - minimal
 features:
   - The exact shape of the auto-generated `vercel.json` — three keys, nothing else
+  - That `buildCommand` builds the vercel target (`<exec> frontmcp build --target vercel`), not the `build` script
   - That routing and function configuration live in `.vercel/output/`, not `vercel.json`
   - That hand-authoring `api/frontmcp.ts` references in `vercel.json` is unnecessary and breaks deploys
 ---
@@ -25,7 +26,7 @@ features:
 // vercel.json — yarn project (yarn.lock present)
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install"
 }
 ```
@@ -34,7 +35,7 @@ features:
 // vercel.json — pnpm project (pnpm-lock.yaml present)
 {
   "version": 2,
-  "buildCommand": "pnpm run build",
+  "buildCommand": "pnpm exec frontmcp build --target vercel",
   "installCommand": "pnpm install"
 }
 ```
@@ -43,11 +44,13 @@ features:
 // vercel.json — npm project (package-lock.json present)
 {
   "version": 2,
-  "buildCommand": "npm run build",
+  "buildCommand": "npx frontmcp build --target vercel",
   "installCommand": "npm install"
 }
 ```
 
+`buildCommand` runs the vercel target through the project's package manager (bun projects get `bunx frontmcp build --target vercel`). It is never `<pm> run build`: the `build` script is `frontmcp build`, which builds the config's deployments and never writes `.vercel/output`.
+
 The actual function and routes live under `.vercel/output/`:
 
 ```text
@@ -64,6 +67,7 @@ The actual function and routes live under `.vercel/output/`:
 ## What This Demonstrates
 
 - The exact shape of the auto-generated `vercel.json` — three keys, nothing else
+- That `buildCommand` builds the vercel target (`<exec> frontmcp build --target vercel`), not the `build` script
 - That routing and function configuration live in `.vercel/output/`, not `vercel.json`
 - That hand-authoring `api/frontmcp.ts` references in `vercel.json` is unnecessary and breaks deploys
 

package/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/vercel-config-with-security-headers.md

@@ -25,11 +25,12 @@ The Vercel adapter emits a minimal `vercel.json` (version + buildCommand + insta
 
 ```json
 // vercel.json — extends the auto-generated minimum with regions + headers.
-// The adapter regenerates buildCommand/installCommand from your lockfile,
-// so keep them aligned (or let the build rewrite them).
+// The build never overwrites an existing vercel.json, so keep buildCommand
+// building the vercel target (`<exec> frontmcp build --target vercel`) —
+// `yarn build` would run the config's deployments and deploy nothing.
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install",
   "regions": ["iad1"],
   "headers": [

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

@@ -117,6 +117,14 @@ function ToolUI() {
 }
 ```
 
+Things that trip people up with `@frontmcp/react`:
+
+- `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.
 
 ## Browser vs Node vs SDK Target

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

@@ -174,14 +174,15 @@ 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 |
+| 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

@@ -208,15 +208,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
 

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

@@ -123,6 +123,8 @@ npx wrangler kv:namespace create FRONTMCP_KV
 
 Copy the returned `id` into your `wrangler.toml`.
 
+Cloudflare storage: `redis: { provider: 'vercel-kv' }` (the HTTP-based Upstash/Vercel KV client) is accepted by `--target cloudflare`; only TCP `redis` and `sqlite` configs are rejected at build time, since Workers cannot open raw sockets or load native modules.
+
 ## Step 4: Configure the Server
 
 ```typescript
@@ -149,7 +151,7 @@ For session storage, use Upstash Redis (HTTP) via `redis: { provider: 'vercel-kv
 
 ### 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`.
+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`. Inside a tool, resource, prompt or agent, read them with `this.workerEnv` (e.g. `this.workerEnv?.MY_KV as KVNamespace | undefined`) — it is the request's Worker `env`, read-only, and `undefined` outside a Worker request. `NODE_ENV = "production"` set in `wrangler.toml` `[vars]` is read live by the runtime context, so production mode takes effect even though the value reaches `process.env` only on the first request.
 
 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.
 

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

@@ -318,14 +318,15 @@ Lambda cold starts occur when a new execution environment is initialized. Strate
 
 ## Troubleshooting
 
-| Problem                              | Cause                                                           | Solution                                                                                                  |
-| ------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| Timeout errors                       | Function timeout too low or waiting on unreachable resource     | Increase `Timeout` in the SAM template; verify network connectivity to dependencies                       |
-| 502 Bad Gateway                      | Handler path mismatch, missing env vars, or unhandled exception | Check CloudWatch Logs; confirm `Handler: handler.handler` and `CodeUri: dist/lambda/`                     |
-| `Cannot find module @codegenie/...`  | Peer dep not installed locally or in Layer                      | `npm install @codegenie/serverless-express` (the build's `validate` hook checks for it)                   |
-| Cold starts too slow                 | Low memory, x86 architecture, or large bundle                   | Increase memory to 512+ MB, use `arm64`, or enable provisioned concurrency                                |
-| Redis connection refused from Lambda | Lambda not in the same VPC as ElastiCache                       | Place the Lambda in the ElastiCache VPC with appropriate security group rules                             |
-| `sam deploy` fails with IAM error    | Insufficient permissions for CloudFormation stack creation      | Ensure the deploying IAM user/role has `cloudformation:*`, `lambda:*`, `apigateway:*`, and `iam:PassRole` |
+| Problem                              | Cause                                                                                | Solution                                                                                                       |
+| ------------------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| Timeout errors                       | Function timeout too low or waiting on unreachable resource                          | Increase `Timeout` in the SAM template; verify network connectivity to dependencies                            |
+| 502 Bad Gateway                      | Handler path mismatch, missing env vars, or unhandled exception                      | Check CloudWatch Logs; confirm `Handler: handler.handler` and `CodeUri: dist/lambda/`                          |
+| `Cannot find module @codegenie/...`  | Peer dep not installed locally or in Layer                                           | `npm install @codegenie/serverless-express` (the build's `validate` hook checks for it)                        |
+| Cold starts too slow                 | Low memory, x86 architecture, or large bundle                                        | Increase memory to 512+ MB, use `arm64`, or enable provisioned concurrency                                     |
+| Redis connection refused from Lambda | Lambda not in the same VPC as ElastiCache                                            | Place the Lambda in the ElastiCache VPC with appropriate security group rules                                  |
+| 500 `server_misconfigured`           | A required secret is missing (`SESSION_SECRET_REQUIRED`, `JWT_SECRET_REQUIRED`, ...) | The response body names the `code` and the remedy; set the variable in the function's environment and redeploy |
+| `sam deploy` fails with IAM error    | Insufficient permissions for CloudFormation stack creation                           | Ensure the deploying IAM user/role has `cloudformation:*`, `lambda:*`, `apigateway:*`, and `iam:PassRole`      |
 
 ## Examples
 

package/catalog/frontmcp-deployment/references/deploy-to-vercel-config.md

@@ -16,12 +16,23 @@ After `frontmcp build --target vercel`, your `vercel.json` looks like:
 ```json
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install"
 }
 ```
 
-The `buildCommand` and `installCommand` are detected from your lockfile (`bun.lockb` -> bun, `pnpm-lock.yaml` -> pnpm, `yarn.lock` -> yarn, `package-lock.json` -> npm).
+The package manager is detected from your lockfile, and `buildCommand` runs the **vercel target** through it:
+
+| Lockfile                    | `buildCommand`                             | `installCommand` |
+| --------------------------- | ------------------------------------------ | ---------------- |
+| `package-lock.json` or none | `npx frontmcp build --target vercel`       | `npm install`    |
+| `yarn.lock`                 | `yarn frontmcp build --target vercel`      | `yarn install`   |
+| `pnpm-lock.yaml`            | `pnpm exec frontmcp build --target vercel` | `pnpm install`   |
+| `bun.lock` / `bun.lockb`    | `bunx frontmcp build --target vercel`      | `bun install`    |
+
+`frontmcp create --target vercel` scaffolds the same file (plus a `$schema` line). The build never overwrites an existing `vercel.json`.
+
+**Never use `<pm> run build` as the `buildCommand`.** The project's `build` script is `frontmcp build`, which builds the deployments in `frontmcp.config` (typically `node`) and never writes `.vercel/output` -- Vercel then has nothing to deploy. Files generated before 1.8.6 used `yarn build` / `npm run build`; replace them with the command above.
 
 ## Customizing
 
@@ -30,7 +41,7 @@ You can hand-edit `vercel.json` AFTER the build to add fields Vercel supports
 ```json
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install",
   "regions": ["iad1"]
 }
@@ -43,6 +54,7 @@ To add response headers, prefer setting them inside your FrontMCP server (where
 - Do **not** add a `rewrites` block routing to `/api/frontmcp` — there is no `api/` directory in the Vercel build output.
 - Do **not** add a `functions: { "api/frontmcp.ts": ... }` map — the function lives at `.vercel/output/functions/index.func/handler.cjs`, configured by `.vc-config.json` (runtime, handler) generated by the adapter.
 - Do **not** set `framework` to a value the FrontMCP build doesn't match. Leaving it unset is safest.
+- Do **not** set `buildCommand` to `<pm> run build` / `yarn build` -- that builds the config's deployments, not the vercel target.
 
 ## Function Runtime Config
 

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

@@ -58,7 +58,7 @@ This produces a Vercel Build Output API v3 structure:
 vercel.json                                # version, buildCommand, installCommand
 ```
 
-The adapter detects your package manager from the lockfile and writes the matching `buildCommand`/`installCommand` into `vercel.json`. No `api/` directory is involved.
+The adapter detects your package manager from the lockfile and writes the matching `installCommand` and a `buildCommand` that builds the **vercel target** through it: `npx frontmcp build --target vercel` (npm), `yarn frontmcp build --target vercel`, `pnpm exec frontmcp build --target vercel`, or `bunx frontmcp build --target vercel`. An existing `vercel.json` is left as it is — including one from `frontmcp create --target vercel`, which writes the same commands. Never set `buildCommand` to `<pm> run build`: the `build` script is `frontmcp build`, which builds the config's deployments (typically `node`) and never writes `.vercel/output`. No `api/` directory is involved.
 
 ## Step 2: Configure the Server for Vercel KV
 
@@ -90,6 +90,8 @@ export default MyServer;
 
 Provision the KV store in the Vercel dashboard under **Storage > Create Database > KV (Redis)**, then link it to your project. Vercel automatically injects the required environment variables.
 
+> **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`).
+
 ## Step 3: Environment Variables
 
 Vercel KV variables are injected automatically when the store is linked. For manual setup or additional configuration, set them in the Vercel dashboard (**Settings > Environment Variables**) or via the CLI:
@@ -178,6 +180,11 @@ Serverless functions are stateless between invocations. All persistent state mus
 | Routing               | `.vercel/output/config.json` (auto)                      | Hand-written `rewrites` to `/api/frontmcp` | The adapter writes `routes: [{ src: '/(.*)', dest: '/index' }]` for you |
 | Environment variables | Link KV store in dashboard (auto-injected)               | Hardcode `KV_REST_API_URL` in source       | Linked stores inject vars automatically and rotate tokens safely        |
 
+### Bundle-time behavior of serverless builds
+
+- `process.env.NODE_ENV` stays a runtime lookup in the Vercel and Lambda bundles. It is not inlined as `"production"` at build time, so a deployment's own `NODE_ENV` (and the production-only checks that read it) behave the same as on a Node server.
+- Optional packages the server may or may not use (`@frontmcp/storage-sqlite`, `@frontmcp/observability`, `@vercel/kv`, `@opentelemetry/sdk-trace-base`) are bundled when installed and left as a lazy `require()` when they are not, so a missing optional package no longer fails the build with "Module not found". `better-sqlite3` (a native addon) is always left external.
+
 ## Verification Checklist
 
 **Build**
@@ -205,13 +212,14 @@ Serverless functions are stateless between invocations. All persistent state mus
 
 ## Troubleshooting
 
-| Problem              | Cause                                   | Solution                                                                                       |
-| -------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| Function timeout     | Operation exceeds plan's max duration   | Check plan limits (Hobby: 10s, Pro: 60s); upgrade plan or refactor the slow tool               |
-| KV connection errors | KV store not linked or env vars missing | Re-link the KV store in the Vercel dashboard; verify `KV_REST_API_URL` and `KV_REST_API_TOKEN` |
-| 404 on every route   | Build did not produce `.vercel/output/` | Ensure `frontmcp build --target vercel` ran before `vercel` deploys                            |
-| Bundle too large     | Unnecessary dependencies included       | Review dependencies and remove unused packages to reduce bundle size                           |
-| Cold starts too slow | Heavy decorator initialization          | Lazy-load providers; defer heavy work until first tool call                                    |
+| Problem                    | Cause                                                                                | Solution                                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| Function timeout           | Operation exceeds plan's max duration                                                | Check plan limits (Hobby: 10s, Pro: 60s); upgrade plan or refactor the slow tool                            |
+| KV connection errors       | KV store not linked or env vars missing                                              | Re-link the KV store in the Vercel dashboard; verify `KV_REST_API_URL` and `KV_REST_API_TOKEN`              |
+| 404 on every route         | Build did not produce `.vercel/output/`                                              | Ensure `frontmcp build --target vercel` ran before `vercel` deploys                                         |
+| Bundle too large           | Unnecessary dependencies included                                                    | Review dependencies and remove unused packages to reduce bundle size                                        |
+| Cold starts too slow       | Heavy decorator initialization                                                       | Lazy-load providers; defer heavy work until first tool call                                                 |
+| 500 `server_misconfigured` | A required secret is missing (`SESSION_SECRET_REQUIRED`, `JWT_SECRET_REQUIRED`, ...) | The response body names the `code` and the remedy; set the variable in Vercel Project Settings and redeploy |
 
 ## Examples
 

package/catalog/frontmcp-deployment/references/protocol-versions.md

@@ -122,6 +122,15 @@ before the first `elicit()`/`sample()`/`listRoots()` call.
 and a 10-minute expiry — a tampered or replayed blob is discarded and the
 exchange restarts.
 
+**Multi-instance: set `VAULT_SECRET`.** The signing key is `VAULT_SECRET`, else
+`JWT_SECRET`, else a random per-process key. With the per-process key, a round
+that lands on another instance (or arrives after a restart) fails verification
+and the tool asks its first question again. Set `VAULT_SECRET` (or `JWT_SECRET`)
+to the same value on every instance. In production, `redis` or
+`transport.persistence` without either secret logs a startup warning; each
+rejection logs `mcp-20260728: rejected requestState` with `reason: 'bad-signature'`
+and a `hint` naming `VAULT_SECRET`.
+
 The client MUST declare the matching capability, or the server answers `-32021`. (An unversioned call the server only defaulted to 2026-07-28 comes from a client that never declared it; `elicit()` answers that one with `ElicitationNotSupportedError`, as for a legacy client without a session.)
 
 ```json

package/catalog/frontmcp-development/examples/official-plugins/cache-and-feature-flags.md

@@ -9,6 +9,7 @@ features:
   - 'Using `toolPatterns` glob patterns to cache groups of tools without per-tool configuration'
   - 'Per-tool `cache` metadata with custom `ttl` (seconds) and `slideWindow` for TTL refresh on hits'
   - 'Using `cache: true` for simple default-TTL caching'
+  - "A cache hit returns the same `content`/`structuredContent` as the miss, marked by `_meta.cache: 'hit'` on the result"
   - "Gating a tool with `featureFlag: 'beta-search'` -- the tool is hidden from `list_tools` when the flag is off"
   - 'Accessing `this.featureFlags.isEnabled()` inside a tool for runtime flag checks'
 ---
@@ -75,6 +76,9 @@ class GetWeatherTool extends ToolContext {
     return { city: input.city, temperature: weather.temp, condition: weather.condition };
   }
 }
+
+// A second identical call is a hit: execute() does not run, `structuredContent` is the same
+// `{ city, temperature, condition }` as the first call, and `result._meta.cache === 'hit'`.
 ```
 
 ```typescript
@@ -106,6 +110,7 @@ class BetaSearchTool extends ToolContext {
 - Using `toolPatterns` glob patterns to cache groups of tools without per-tool configuration
 - Per-tool `cache` metadata with custom `ttl` (seconds) and `slideWindow` for TTL refresh on hits
 - Using `cache: true` for simple default-TTL caching
+- A cache hit returns the same `content`/`structuredContent` as the miss, marked by `_meta.cache: 'hit'` on the result
 - Gating a tool with `featureFlag: 'beta-search'` -- the tool is hidden from `list_tools` when the flag is off
 - Accessing `this.featureFlags.isEnabled()` inside a tool for runtime flag checks