npm - @frontmcp/skills - Versions diffs - 1.8.5 → 1.8.7 - Mend

@frontmcp/skills 1.8.5 → 1.8.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (55) hide show

package/catalog/create-tool/SKILL.md CHANGED Viewed

@@ -32,8 +32,8 @@ when_to_use: |
   Trigger when creating or editing a `*.tool.ts` / `*.tool.tsx` file, adding a `@Tool`
   decorator, defining `inputSchema` / `outputSchema` for a tool, deriving `execute()`
   parameter or return types, wiring dependency injection into a tool, returning
-  structured / media / resource content, adding a `ui:` block (HTML / MDX / React /
-  FileSource), configuring throttling, declaring auth providers, restricting platforms
+  structured / media / resource content, adding a `ui:` block (FileSource / React /
+  HTML / Markdown), configuring throttling, declaring auth providers, restricting platforms
   via `availableWhen`, requesting interactive input via `this.elicit`, adding tool
   `annotations`, or registering a tool in `@App({ tools })`.
@@ -203,7 +203,7 @@ If a request seems to conflict with an inherited default (e.g., "wrap `inputSche
           │                            See: examples/22-tool-with-ui-html-template.md
           ├── React widget (file)   → ui: { template: { file: widgetPath } }
           │                            See: examples/23-tool-with-ui-filesource-tsx.md
-          ├── Calls other tools     → widgetAccessible: true + window.FrontMcpBridge
+          ├── Calls other tools     → window.FrontMcpBridge.callTool
           │                            See: examples/24-tool-with-ui-csp-and-bridge.md
           └── Claude target         → resourceMode is auto-detected; do not set
                                        See: references/ui-widgets.md
@@ -240,7 +240,7 @@ If a request seems to conflict with an inherited default (e.g., "wrap `inputSche
 | Tool restricted to one OS / runtime / target | [`21-tool-with-availability-constraints`](./examples/21-tool-with-availability-constraints.md) | `availableWhen` axes                                                    |
 | Tool with a quick inline HTML widget         | [`22-tool-with-ui-html-template`](./examples/22-tool-with-ui-html-template.md)                 | `ui: { template: (ctx) => '<div>…</div>' }`                             |
 | Tool with a separate `.tsx` widget file      | [`23-tool-with-ui-filesource-tsx`](./examples/23-tool-with-ui-filesource-tsx.md)               | `FileSource` + `import.meta.url` anchoring                              |
-| Tool widget that calls other tools           | [`24-tool-with-ui-csp-and-bridge`](./examples/24-tool-with-ui-csp-and-bridge.md)               | `widgetAccessible: true` + `window.FrontMcpBridge.callTool`             |
+| Tool widget that calls other tools           | [`24-tool-with-ui-csp-and-bridge`](./examples/24-tool-with-ui-csp-and-bridge.md)               | `window.FrontMcpBridge.callTool`                                        |
 | Tool that triggers a job + tracks it         | [`25-tool-handing-off-to-job`](./examples/25-tool-handing-off-to-job.md)                       | Thin tool + heavy job — the right split                                 |
 | Tool that returns a resource handle          | [`26-tool-with-resource-link-output`](./examples/26-tool-with-resource-link-output.md)         | `outputSchema: 'resource_link'` — the host fetches the resource         |
 | Tool with `examples` metadata for discovery  | [`27-tool-with-examples-metadata`](./examples/27-tool-with-examples-metadata.md)               | `examples: [{ description, input, output? }]`                           |
@@ -269,26 +269,26 @@ Before considering a tool "done":
 ## References (deep dives)
-| Reference                                                             | Covers                                                                                                                |
-| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| [`quick-start.md`](./references/quick-start.md)                       | 60-second tour: minimal tool, registration, calling it from a test                                                    |
-| [`decorator-options.md`](./references/decorator-options.md)           | Every field on `@Tool({...})` — what it does, default, when to set it                                                 |
-| [`input-schema.md`](./references/input-schema.md)                     | Raw shape vs `z.object`, refinements, defaults, optional, describe                                                    |
-| [`output-schema.md`](./references/output-schema.md)                   | All supported output types: Zod shape, Zod schema, primitives, media, arrays                                          |
-| [`derived-types.md`](./references/derived-types.md)                   | `ToolInputOf` / `ToolOutputOf` patterns, file layout, schema hoisting                                                 |
-| [`execution-context.md`](./references/execution-context.md)           | `ToolContext` methods + properties — `this.get`, `this.fetch`, `this.notify`, `this.context`, etc.                    |
-| [`error-handling.md`](./references/error-handling.md)                 | `this.fail`, MCP error classes (`PublicMcpError`, `ResourceNotFoundError`), error flow, when to throw vs `fail`       |
-| [`throttling.md`](./references/throttling.md)                         | `rateLimit`, `concurrency`, `timeout` — semantics, interaction, defaults                                              |
-| [`auth-providers.md`](./references/auth-providers.md)                 | `authProviders` string shorthand vs full mapping, scopes, alias, credential vault basics                              |
-| [`availability.md`](./references/availability.md)                     | `availableWhen` axes (os / runtime / deployment / provider / target / surface / env), `missingAxes`, `isPlatform`     |
-| [`elicitation.md`](./references/elicitation.md)                       | `this.elicit`, server-level enable, `ElicitationDisabledError`, accept / decline / cancel                             |
-| [`ui-widgets.md`](./references/ui-widgets.md)                         | `@Tool({ ui })` — template formats, `servingMode`, `resourceMode` host-detect, CSP, `widgetAccessible`, MCP Apps spec |
-| [`annotations.md`](./references/annotations.md)                       | `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`                                         |
-| [`function-style-builder.md`](./references/function-style-builder.md) | `tool({...})(handler)` — when to pick over a class, register, ctx parameter                                           |
-| [`remote-and-esm.md`](./references/remote-and-esm.md)                 | `Tool.esm(...)` / `Tool.remote(...)` — load tools from ESM URLs or remote MCP servers                                 |
-| [`registration.md`](./references/registration.md)                     | `@App({ tools })` vs `@FrontMcp({ tools })`, multi-app composition                                                    |
-| [`file-layout.md`](./references/file-layout.md)                       | Flat-sibling vs folder-per-tool, `<name>.schema.ts` / `<name>.tool.ts` / `<name>.tool.spec.ts`                        |
-| [`testing.md`](./references/testing.md)                               | Per-tool unit tests — `@frontmcp/testing`, mocking DI, asserting output validation                                    |
+| Reference                                                             | Covers                                                                                                             |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| [`quick-start.md`](./references/quick-start.md)                       | 60-second tour: minimal tool, registration, calling it from a test                                                 |
+| [`decorator-options.md`](./references/decorator-options.md)           | Every field on `@Tool({...})` — what it does, default, when to set it                                              |
+| [`input-schema.md`](./references/input-schema.md)                     | Raw shape vs `z.object`, refinements, defaults, optional, describe                                                 |
+| [`output-schema.md`](./references/output-schema.md)                   | All supported output types: Zod shape, Zod schema, primitives, media, arrays                                       |
+| [`derived-types.md`](./references/derived-types.md)                   | `ToolInputOf` / `ToolOutputOf` patterns, file layout, schema hoisting                                              |
+| [`execution-context.md`](./references/execution-context.md)           | `ToolContext` methods + properties — `this.get`, `this.fetch`, `this.notify`, `this.context`, etc.                 |
+| [`error-handling.md`](./references/error-handling.md)                 | `this.fail`, MCP error classes (`PublicMcpError`, `ResourceNotFoundError`), error flow, when to throw vs `fail`    |
+| [`throttling.md`](./references/throttling.md)                         | `rateLimit`, `concurrency`, `timeout` — semantics, interaction, defaults                                           |
+| [`auth-providers.md`](./references/auth-providers.md)                 | `authProviders` string shorthand vs full mapping, scopes, alias, credential vault basics                           |
+| [`availability.md`](./references/availability.md)                     | `availableWhen` axes (os / runtime / deployment / provider / target / surface / env), `missingAxes`, `isPlatform`  |
+| [`elicitation.md`](./references/elicitation.md)                       | `this.elicit`, server-level enable, `ElicitationDisabledError`, accept / decline / cancel                          |
+| [`ui-widgets.md`](./references/ui-widgets.md)                         | `@Tool({ ui })` — template formats, `servingMode`, `resourceMode` host-detect, CSP, ignored options, MCP Apps spec |
+| [`annotations.md`](./references/annotations.md)                       | `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`                                      |
+| [`function-style-builder.md`](./references/function-style-builder.md) | `tool({...})(handler)` — when to pick over a class, register, ctx parameter                                        |
+| [`remote-and-esm.md`](./references/remote-and-esm.md)                 | `Tool.esm(...)` / `Tool.remote(...)` — load tools from ESM URLs or remote MCP servers                              |
+| [`registration.md`](./references/registration.md)                     | `@App({ tools })` vs `@FrontMcp({ tools })`, multi-app composition                                                 |
+| [`file-layout.md`](./references/file-layout.md)                       | Flat-sibling vs folder-per-tool, `<name>.schema.ts` / `<name>.tool.ts` / `<name>.tool.spec.ts`                     |
+| [`testing.md`](./references/testing.md)                               | Per-tool unit tests — `@frontmcp/testing`, mocking DI, asserting output validation                                 |
 ## Rules (constraints — read these once, then they're enforced)

package/catalog/create-tool/examples/22-tool-with-ui-html-template.md CHANGED Viewed

@@ -38,7 +38,6 @@ type Out = { city: string; temperatureF: number; conditions: string };
   inputSchema,
   outputSchema,
   ui: {
-    widgetDescription: 'Current weather card',
     // `html` escapes interpolated values — no manual escapeHtml needed
     template: (ctx: TemplateContext<In, Out>) => ctx.helpers.html`
       <div style="padding:16px;font-family:system-ui;border-radius:12px;background:#f5f7fa">

package/catalog/create-tool/examples/23-tool-with-ui-filesource-tsx.md CHANGED Viewed

@@ -16,7 +16,7 @@ Tool with a `.tsx` widget in a separate file via the `FileSource` form — the r
 For any React widget, FileSource is the right pattern. The widget lives in its own `.widget.tsx` file with its own React imports; the tool decorator just points at it.
-> **Prerequisite:** `@frontmcp/ui` installed at the same version as `@frontmcp/sdk`. Without it, server-side bundling fails — the framework injects an auto-generated React mount that imports `McpBridgeProvider` from `@frontmcp/ui/react`.
+> **Prerequisites:** `@frontmcp/ui` installed at the same version as `@frontmcp/sdk` — the framework injects an auto-generated React mount that imports `McpBridgeProvider` from `@frontmcp/ui/react`. And `esbuild` installed as a runtime dependency (`npm install esbuild`, not a devDependency) — `@frontmcp/uipack` loads it to bundle the widget when the tool is called. `frontmcp create` projects get `esbuild` through the `frontmcp` package.
 ## Code
@@ -41,8 +41,10 @@ import { Tool, ToolContext } from '@frontmcp/sdk';
 import { inputSchema, outputSchema, type SalesChartInput, type SalesChartOutput } from './sales-chart.schema';
-// Anchor the widget path to THIS source file — bare relative paths resolve
-// against process.cwd() (issue #444), which fails in any non-trivial layout.
+// Anchor the widget path to THIS file — bare relative paths resolve against
+// process.cwd() (issue #444), which fails in any non-trivial layout. Once
+// compiled, this resolves next to the compiled file, so the widget must ship
+// with the build (`frontmcp build` copies *.widget.tsx files — #649).
 const widgetPath = fileURLToPath(new URL('./sales-chart.widget.tsx', import.meta.url));
 @Tool({
@@ -51,12 +53,10 @@ const widgetPath = fileURLToPath(new URL('./sales-chart.widget.tsx', import.meta
   inputSchema,
   outputSchema,
   ui: {
-    widgetDescription: 'Monthly revenue chart',
     template: { file: widgetPath },
     // resourceMode is intentionally UNSET — framework host-detects: 'inline' for Claude
     // (React bundled in, widget renders under Claude's CSP), 'cdn' for OpenAI / ChatGPT /
     // Cursor / MCP Inspector (smaller payload from esm.sh). Issue #456.
-    hydrate: false, // SSR-only — dodges React error #418 in iframe sandboxes
   },
 })
 export class SalesChartTool extends ToolContext {
@@ -107,6 +107,7 @@ export default function SalesChartWidget({ output }: Props) {
 ## Why these defaults matter
 - **`import.meta.url` anchoring** — relative paths in `FileSource` resolve against `process.cwd()`, not the tool file (#444). Running the server from a different directory breaks the widget at tool-call time. Anchoring fixes it once.
+- **Ship the widget** — the anchored path points next to the **compiled** file after a build, and tsc doesn't emit `*.widget.tsx`. `frontmcp build` copies widget files into the output (directly next to the bundle for the bundled `node` / `cli` / `lambda` / `vercel` targets, so keep widget file names unique); a plain `tsc` build needs its own copy step (#649).
 - **`resourceMode` unset** — leave it. The framework picks `'inline'` for Claude (React bundled into the widget — actually renders) and `'cdn'` for everyone else (smaller payload via esm.sh). Setting it explicitly only locks in one behavior across all clients.
-- **`hydrate: false`** — default. React SSR output is static HTML; the bridge IIFE handles any interactivity. Enabling hydration creates React error #418 in Claude's iframe sandbox where the client-side render diverges from the SSR render.
+- **No `hydrate` option** — `ui.hydrate` is accepted but has no effect yet (startup logs a warning). The `.tsx` widget is bundled and mounted on the client by the generated entry.
 - **`*.widget.tsx` naming** — the scaffolded `tsconfig.json` excludes `**/*.widget.tsx` from the server typecheck (#445). The widget compiles via uipack/esbuild at render time with its own React-aware config.

package/catalog/create-tool/examples/24-tool-with-ui-csp-and-bridge.md CHANGED Viewed

@@ -2,10 +2,10 @@
 name: 24-tool-with-ui-csp-and-bridge
 level: advanced
 description: 'Interactive tool widget that fetches from an allow-listed CSP origin and invokes another tool via `window.FrontMcpBridge.callTool` — the full pattern for live-data widgets that need cross-tool composition.'
-tags: [ui, csp, widgetAccessible, FrontMcpBridge, interactive-widget]
+tags: [ui, csp, callTool, FrontMcpBridge, interactive-widget]
 features:
   - "Restricting the widget's outbound `fetch` via `ui.csp.connectDomains` (emitted on the resource per #455)"
-  - 'Opting the widget into cross-tool calls with `widgetAccessible: true` and using `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs'
+  - 'Calling other tools from the widget with `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs'
   - 'Building the markup with `ctx.helpers.html` and embedding initial data into the inline `<script>` via `trustedHtml(jsonEmbed(...))` (`jsonEmbed` escapes `<`, `>` and `&`)'
   - 'Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback'
 ---
@@ -58,8 +58,6 @@ type Out = { symbol: string; priceUsd: number; asOf: string };
   inputSchema,
   outputSchema,
   ui: {
-    widgetDescription: 'Live stock quote with refresh',
-    widgetAccessible: true, // required for window.FrontMcpBridge.callTool
     invocationStatus: { invoking: 'Fetching quote…', invoked: 'Quote loaded' },
     csp: {
       // CSP applies to the widget iframe — only allow fetches to our own market-data API.
@@ -117,13 +115,13 @@ export class ShowQuoteTool extends ToolContext {
 ## What This Demonstrates
 - Restricting the widget's outbound `fetch` via `ui.csp.connectDomains` (emitted on the resource per #455)
-- Opting the widget into cross-tool calls with `widgetAccessible: true` and using `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs
+- Calling other tools from the widget with `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs
 - Building the markup with `ctx.helpers.html` and embedding initial data into the inline `<script>` via `trustedHtml(jsonEmbed(...))` (`jsonEmbed` escapes `<`, `>` and `&`)
 - Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback
 ## Why these choices
-- **`widgetAccessible: true`** — required for `window.FrontMcpBridge.callTool`. Without it, the bridge is read-only (the widget can read `getToolInput` / `getToolOutput` but can't invoke tools).
+- **No `widgetAccessible` / `widgetDescription`** — both are accepted by the schema but nothing reads them yet (startup logs a warning), so they are left out. Whether the widget may call tools is decided by the host.
 - **`csp.connectDomains`** — limits what the widget can `fetch` to. Without a CSP, the host's default applies (which may block everything in Claude). With `connectDomains: ['https://api.market.example']`, only that origin is reachable.
 - **`window.FrontMcpBridge.callTool` not `window.openai.callTool`** — the bridge handles host detection. `window.openai.*` works on OpenAI Apps SDK but breaks everywhere else.
 - **`jsonEmbed` not `JSON.stringify`** — `JSON.stringify` doesn't escape `</script>` or `<!--` and can break out of the inline script tag. `jsonEmbed` writes `<`, `>` and `&` as `\u003c`, `\u003e`, `\u0026`.

package/catalog/create-tool/examples/27-tool-with-examples-metadata.md CHANGED Viewed

@@ -14,7 +14,7 @@ features:
 Tool with the `examples: [...]` field on `@Tool({...})` — concrete input (and optional expected output) examples consumed by the CodeCall `codecall:describe` tool to give agents accurate usage examples.
-The `examples` field is purely advisory — the CodeCall `describe` tool uses it as the highest-priority source of usage examples (user-provided examples take precedence over auto-generated ones, up to 5). It is **not** emitted in the `tools/list` MCP response. Use it for any tool that benefits from concrete usage hints when CodeCall is enabled.
+The `examples` field is purely advisory — the CodeCall `describe` tool uses it as the source of usage examples: when a tool declares examples, `codecall:describe` returns only those (up to 5) and adds no auto-generated one. It is **not** emitted in the `tools/list` MCP response. Use it for any tool that benefits from concrete usage hints when CodeCall is enabled.
 ## Code
@@ -74,7 +74,8 @@ export class ConvertCurrencyTool extends ToolContext {
 ## Where examples show up
-- **`codecall:describe`** — the CodeCall plugin's `describe` tool uses these as its top-priority source of usage examples (user-provided examples win over auto-generated ones, capped at 5). This is the one place `examples` is actually read.
+- **`codecall:describe`** — the CodeCall plugin's `describe` tool returns these as the tool's usage examples (capped at 5), with no auto-generated example next to them. This is the one place `examples` is actually read.
+- **Without `examples`** — `codecall:describe` generates one example from the tool's intent, with arguments built only from the input schema's properties (required ones, the query-like or first filter property for a search, the real pagination properties for a list, the first enum value), or `{}` when none fits. Values stay within the property's `enum`, `const`, bounds and length limits; a `pattern` or `format` is not generated, so an optional property that has one is left out. It never shows an argument the schema does not declare, such as a made-up `query`.
 - **Not in `tools/list`** — the `tools/list` MCP response does not include `examples`; clients never see them there.
 ## When to include `output?`

package/catalog/create-tool/references/decorator-options.md CHANGED Viewed

@@ -43,7 +43,7 @@ Full surface of the `@Tool` decorator. Mandatory fields are bolded.
 - **`rateLimit` + `concurrency`** — independent. Rate-limit caps invocations over time; concurrency caps simultaneous in-flight. A "1 req/s with max 2 concurrent" tool is fine: bursts can run two at once, then back off.
 - **`timeout` + `rateLimit`** — orthogonal. Timeout wraps a single call; rate-limit wraps the rate of calls.
-- **`authProviders` + `ui.widgetAccessible`** — the widget bridge respects the tool's auth requirements. A widget that calls back to a tool requiring `authProviders: ['github']` will fail in the bridge if no GitHub session exists.
+- **`authProviders` + widget tool calls** — a widget that calls back to a tool requiring `authProviders: ['github']` fails if no GitHub session exists. (`ui.widgetAccessible` is accepted but has no effect yet.)
 - **`availableWhen` + `visibility`** — `availableWhen` is a hard constraint (filtered out of `tools/list` AND blocked from execution when context doesn't match); `visibility: 'hidden'` is a soft hide (filtered from `tools/list` but still callable by name). `visibility: 'internal'` blocks external `tools/call` entirely (in-process `this.callTool` only).
 - **`ui.servingMode === 'static'` + `availableWhen`** — static widgets pre-compile at startup. If a tool is filtered out by `availableWhen`, its static widget isn't compiled either.

package/catalog/create-tool/references/elicitation.md CHANGED Viewed

@@ -129,6 +129,7 @@ There are no server-to-client requests in this revision. `this.elicit()` answers
 - A client without the `elicitation` capability for the mode gets error `-32021`. Capabilities come with each request, and `this.elicit()` checks them itself. A session-based check such as `this.scope.notifications.getClientCapabilities(sessionId)` finds nothing here, so call `this.elicit()` directly.
 - `sendElicitationResult` is not listed to 2026-07-28 clients.
 - Anonymous callers keep their `requestState` across rounds (it binds to one shared anonymous principal).
+- **More than one instance? Set `VAULT_SECRET` (or `JWT_SECRET`) to the same value on every instance.** `requestState` is signed with `VAULT_SECRET`, else `JWT_SECRET`, else a random per-process key; under the per-process key a round that lands on another instance (or after a restart) fails verification and the tool asks its first question again. Production servers with `redis`/`transport.persistence` but neither secret log a startup warning, and each rejected round logs `reason: 'bad-signature'` with a `hint` naming `VAULT_SECRET`.
 ## See also

package/catalog/create-tool/references/file-layout.md CHANGED Viewed

@@ -89,6 +89,8 @@ If you hoisted the entire `@Tool({...})` config, consumers would drag the `@Tool
 `.tsx` / `.jsx` widget files use the `*.widget.tsx` naming convention. The scaffolded `tsconfig.json` excludes `**/*.widget.tsx` from the server typecheck (#445 fix) — widgets are bundled separately by `@frontmcp/uipack` (esbuild) at render time, with React loaded externally. If you want IDE typecheck for widget sources, add a sibling `tsconfig.widget.json` with `jsx: 'react-jsx'` and `include: ['src/**/*.widget.tsx']`.
+Keep each widget beside the tool that uses it, with a unique file name. tsc never emits widget files, so `frontmcp build` copies them into the output — for the bundled `node` / `cli` / `lambda` / `vercel` targets directly next to the bundle, where every tool's `__dirname` points (#649). Two widgets with the same file name can't both go there; the build skips them with a warning.
 ## See also
 - [`derived-types.md`](./derived-types.md) — why schemas hoist

package/catalog/create-tool/references/ui-widgets.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: ui-widgets
-description: @Tool({ ui }) — template formats, trusted markup (html / escapeStringResults), servingMode, host-detect resourceMode, CSP, widgetAccessible, MCP Apps spec.
+description: @Tool({ ui }) — template formats, trusted markup (html / escapeStringResults), servingMode, host-detect resourceMode, CSP, ignored options, MCP Apps spec.
 ---
 # Tool UI widgets
@@ -39,12 +39,12 @@ That's it. The framework:
 ## Template formats
-| Format                       | Shape                                     | When                                                                                                      |
-| ---------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| **FileSource (recommended)** | `{ file: widgetPath }`                    | `.tsx` / `.jsx` / `.html` source files. Anchor with `import.meta.url`.                                    |
-| **Function**                 | `` (ctx) => ctx.helpers.html`…` ``        | Quick demo / one-liner HTML. Annotate `ctx: TemplateContext<In, Out>` ([why](#typescript-gotcha-ts7006)). |
-| **HTML / MDX string**        | `'<div>…</div>'` or `'# Title\n<Card />'` | Static markup; pair with `mdxComponents` for MDX.                                                         |
-| **React component**          | `MyWidget`                                | SSR React. Set `hydrate: false` (default) for Claude/ChatGPT.                                             |
+| Format                       | Shape                                   | When                                                                                                                               |
+| ---------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| **FileSource (recommended)** | `{ file: widgetPath }`                  | `.tsx` / `.jsx` / `.html` source files. Anchor with `import.meta.url`.                                                             |
+| **Function**                 | `` (ctx) => ctx.helpers.html`…` ``      | Quick demo / one-liner HTML. Annotate `ctx: TemplateContext<In, Out>` ([why](#typescript-gotcha-ts7006)).                          |
+| **HTML / Markdown string**   | `'<div>…</div>'` or `'# Title\n- item'` | A string with both `<` and `>` is HTML as written; any other string is Markdown, converted on the server. MDX is **not** compiled. |
+| **React component**          | `MyWidget`                              | A bare component reference cannot be bundled for the widget; use the `{ file }` form instead.                                      |
 The renderer auto-detects which one you passed.
@@ -64,26 +64,54 @@ Or use the FileSource form — it sidesteps the issue.
 ## `ToolUIConfig` fields
-| Field                                                                                                           | Default     | Purpose                                                                                                                         |
-| --------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `template`                                                                                                      | —           | Required. Function / HTML-string / React component / `{ file }` FileSource.                                                     |
-| `widgetDescription`                                                                                             | —           | Human-readable description surfaced to the host UI.                                                                             |
-| `servingMode`                                                                                                   | `'auto'`    | `'inline'` / `'static'` / `'hybrid'` / `'direct-url'` / `'custom-url'`. `'auto'` picks the best per-host.                       |
-| `displayMode`                                                                                                   | `'inline'`  | `'inline'` / `'fullscreen'` / `'pip'` — host display hint.                                                                      |
-| `preferredHeight`                                                                                               | —           | `number` (px) or CSS string (`'50vh'`). Initial widget height; auto-resize grows/shrinks from this baseline.                    |
-| `minHeight` / `maxHeight`                                                                                       | —           | `number` (px) or CSS string. Clamp the widget height; auto-resize never reports outside this range.                             |
-| `aspectRatio`                                                                                                   | —           | CSS `aspect-ratio` (`'16 / 9'` or `1.5`). Hosts that honor it size by ratio instead of measured height.                         |
-| `autoResize`                                                                                                    | `true`      | Auto-report content height to the host via a debounced `ResizeObserver` on `#root`. Set `false` to opt out (CSS still applies). |
-| `csp`                                                                                                           | —           | `{ connectDomains?, resourceDomains? }` — emitted on the resource content's `_meta.ui.csp` (#455). Claude honors CSP only here. |
-| `contentSecurity`                                                                                               | strict      | `{ allowUnsafeLinks?, allowInlineScripts?, bypassSanitization? }` — keep defaults.                                              |
-| `escapeStringResults`                                                                                           | unset       | `true` escapes plain string results of a template function; `html` / `trustedHtml` stay markup. Default in 1.9.                 |
-| `widgetAccessible`                                                                                              | `false`     | `true` exposes `window.FrontMcpBridge.callTool` in the widget.                                                                  |
-| `resourceUri`                                                                                                   | auto        | Override the `ui://widget/{toolName}.html` URI.                                                                                 |
-| `uiType`                                                                                                        | `'auto'`    | Force `'html'` / `'react'` / `'mdx'` / `'markdown'`.                                                                            |
-| `resourceMode`                                                                                                  | host-detect | `'cdn'` / `'inline'`. Leave unset — the framework host-detects (Claude → `'inline'`, #456).                                     |
-| `hydrate`                                                                                                       | `false`     | Enable React hydration after SSR. Off by default — avoids React error #418 in Claude.                                           |
-| `externals`, `dependencies`                                                                                     | —           | CDN externals for FileSource widgets.                                                                                           |
-| `customShell`, `invocationStatus`, `widgetCapabilities`, `prefersBorder`, `sandboxDomain`, `htmlResponsePrefix` | —           | Platform-specific knobs.                                                                                                        |
+| Field                                                                                                     | Default     | Purpose                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `template`                                                                                                | —           | Required. `{ file }` FileSource (recommended) / function / HTML or Markdown string / React component.                                                                                                                                              |
+| `widgetDescription`                                                                                       | —           | **No effect yet** — accepted, not read.                                                                                                                                                                                                            |
+| `servingMode`                                                                                             | `'auto'`    | `'inline'` / `'static'` / `'hybrid'`. `'auto'` picks the best per-host. `'direct-url'` / `'custom-url'` are not implemented (served inline, startup warning). `'hybrid'` sends only `_meta['ui/component']` = `{ type, hash, toolName }`, no code. |
+| `displayMode`                                                                                             | `'inline'`  | **No effect yet.**                                                                                                                                                                                                                                 |
+| `preferredHeight`                                                                                         | —           | `number` (px) or CSS string (`'50vh'`). Initial widget height; auto-resize grows/shrinks from this baseline.                                                                                                                                       |
+| `minHeight` / `maxHeight`                                                                                 | —           | `number` (px) or CSS string. Clamp the widget height; auto-resize never reports outside this range.                                                                                                                                                |
+| `aspectRatio`                                                                                             | —           | CSS `aspect-ratio` (`'16 / 9'` or `1.5`). Hosts that honor it size by ratio instead of measured height.                                                                                                                                            |
+| `autoResize`                                                                                              | `true`      | Report the document height (margins included) to the host after the handshake. Set `false` to opt out (CSS still applies).                                                                                                                         |
+| `csp`                                                                                                     | —           | `{ connectDomains?, resourceDomains? }` — emitted on the resource content's `_meta.ui.csp` (#455). Claude honors CSP only here.                                                                                                                    |
+| `contentSecurity`                                                                                         | strict      | **No effect yet.**                                                                                                                                                                                                                                 |
+| `escapeStringResults`                                                                                     | unset       | `true` escapes plain string results of a template function; `html` / `trustedHtml` stay markup. Default in 1.9.                                                                                                                                    |
+| `widgetAccessible`                                                                                        | `false`     | **No effect yet.**                                                                                                                                                                                                                                 |
+| `resourceUri`                                                                                             | auto        | Override the `ui://widget/{toolName}.html` URI.                                                                                                                                                                                                    |
+| `uiType`                                                                                                  | `'auto'`    | **No effect yet** — the type is auto-detected.                                                                                                                                                                                                     |
+| `resourceMode`                                                                                            | host-detect | `'cdn'` / `'inline'`. Leave unset — the framework host-detects (Claude → `'inline'`, #456).                                                                                                                                                        |
+| `hydrate`                                                                                                 | `false`     | **No effect yet.**                                                                                                                                                                                                                                 |
+| `externals`, `dependencies`                                                                               | —           | CDN externals for FileSource widgets.                                                                                                                                                                                                              |
+| `customShell`, `invocationStatus`, `widgetCapabilities`                                                   | —           | Platform-specific knobs.                                                                                                                                                                                                                           |
+| `prefersBorder`, `sandboxDomain`, `runtimeOptions`, `mdxComponents`, `bundlingMode`, `htmlResponsePrefix` | —           | **No effect yet.** There is no dual HTML payload for Claude.                                                                                                                                                                                       |
+## Components and hooks
+`@frontmcp/ui` has **no** `card()`, `badge()`, `descriptionList()`, `button()`, `form()` or `input()` functions. Widgets use React: components from `@frontmcp/ui/components` (`Alert`, `Avatar`, `Badge`, `Button`, `Card`, `List`, `Loader`, `Modal`, `Select`, `Table`, `TextField`) and bridge hooks from `@frontmcp/ui/react` (`useToolInput`, `useToolOutput`, `useCallTool`, `useTheme`, `useHostContext`, ...). A `.tsx` widget receives `{ output, loading }`.
+`useCallTool` returns a **tuple**, not an object:
+```tsx
+import { Card } from '@frontmcp/ui/components';
+import { useCallTool } from '@frontmcp/ui/react';
+export default function Widget({ output }: { output: { id: string } | null }) {
+  const [refresh, { data, loading, error, called }, reset] = useCallTool('get_order');
+  if (!output) return <Card title="Loading..." />;
+  return (
+    <button disabled={loading} onClick={() => refresh({ orderId: output.id })}>
+      Refresh
+    </button>
+  );
+}
+```
+## Markdown, MDX and sanitization
+- A string template with both `<` and `>` is HTML and is used as written. Any other string is Markdown: headings, paragraphs, fenced code, lists, bold, italic, inline code and links are converted server-side; raw HTML is escaped; a link survives only if its target starts with `http:`, `https:`, `mailto:`, `/` or `#`.
+- MDX is not compiled: `{output.field}` expressions are not evaluated and `mdxComponents` is ignored. Use a `.tsx` FileSource widget for interactivity.
+- Author-written markup (template literals, HTML strings, `.tsx`) is trusted and not sanitized. Values interpolated into `` html`…` `` are escaped; plain string results are escaped only with `escapeStringResults: true`.
 ## Widget resources and per-call renders
@@ -140,6 +168,12 @@ ui: {
 See [`rules/widget-paths-anchor-with-import-meta-url.md`](../rules/widget-paths-anchor-with-import-meta-url.md).
+The widget is read when the tool is called, from the path the **compiled** tool computes — an anchored path points into the build output once the tool is compiled, so the file has to ship there (#649):
+- `frontmcp build` copies every `*.widget.tsx` / `*.widget.jsx` under the entry's directory into the output. tsc-output targets (`distributed`, `cloudflare`) get them at the same relative path, next to each compiled tool. Bundled targets (`node`, `cli`, `lambda`, `vercel`) get them directly next to the bundle, because every bundled module's `__dirname` is the bundle's directory — keep each widget beside its tool and give it a unique file name (the build skips, and warns about, names used twice).
+- Only widget files are copied, not other local files a widget imports.
+- A plain `tsc` build copies nothing — add a copy step. A missing widget fails the call with an `ENOENT` error naming the path it looked for, and the `src/` file when one matches.
 ## `@frontmcp/ui` prerequisite (#443)
 `.tsx` / `.jsx` FileSource widgets require `@frontmcp/ui` in the consuming project — the bundler injects an auto-generated React mount that imports `McpBridgeProvider` from `@frontmcp/ui/react`:
@@ -151,9 +185,19 @@ npm install @frontmcp/ui
 Match the version to `@frontmcp/sdk`. Without it, server-side bundling fails with a friendly error pointing at this requirement.
+## `esbuild` prerequisite (#649)
+`@frontmcp/uipack` loads `esbuild` on demand to bundle a `.tsx` / `.jsx` widget **when the tool is called**, so it must be installed where the server runs — as a runtime dependency:
+```bash
+npm install esbuild   # in "dependencies", not "devDependencies"
+```
+Projects created with `frontmcp create` already have it through the `frontmcp` package. `@frontmcp/uipack` declares it as an optional peer dependency (`>=0.27.0 <1`). Without it, the call fails with an error naming the widget.
 ## Widget bridge — `window.FrontMcpBridge`
-When the widget needs to read tool data or invoke other tools, the bridge IIFE is injected automatically. Set `widgetAccessible: true` to enable `callTool`:
+When the widget needs to read tool data or invoke other tools, the bridge IIFE is injected automatically; no option is needed (`widgetAccessible` is accepted but has no effect yet):
 ```typescript
 ui: {
@@ -166,21 +210,31 @@ ui: {
       };
     </script>
   `,
-  widgetAccessible: true,
 }
 ```
-| Bridge method                                                   | Purpose                                                 |
-| --------------------------------------------------------------- | ------------------------------------------------------- |
-| `callTool(name, args)`                                          | Invoke another tool (requires `widgetAccessible: true`) |
-| `getToolInput()` / `getToolOutput()` / `getStructuredContent()` | Read the tool data                                      |
-| `getWidgetState()` / `setWidgetState(state)`                    | Persisted per-widget state                              |
-| `getHostContext()` / `getTheme()` / `getDisplayMode()`          | Host context                                            |
-| `hasCapability(cap)`                                            | Probe adapter capabilities                              |
-| `onToolResponseMetadata(cb)`                                    | Subscribe to `ui/html` arrival (inline mode)            |
+| Bridge method                                                   | Purpose                                                |
+| --------------------------------------------------------------- | ------------------------------------------------------ |
+| `callTool(name, args)`                                          | Invoke another tool (the host may still refuse)        |
+| `getToolInput()` / `getToolOutput()` / `getStructuredContent()` | Read the tool data                                     |
+| `getWidgetState()` / `setWidgetState(state)`                    | Persisted per-widget state                             |
+| `getHostContext()` / `getTheme()` / `getDisplayMode()`          | Host context                                           |
+| `onContextChange(cb)`                                           | Subscribe to host context changes (handshake included) |
+| `hasCapability(cap)`                                            | Probe adapter capabilities                             |
+| `onToolResponseMetadata(cb)`                                    | Subscribe to `ui/html` arrival (inline mode)           |
 The bridge routes to the right host adapter (OpenAI SDK / Claude postMessage / FrontMCP direct) automatically. **Never call `window.openai.*` directly** — it works on OpenAI but breaks everywhere else.
+### Theme
+The page follows the host theme. When an MCP Apps host sends `theme: 'light' | 'dark'` — in the `ui/initialize` result or a later `ui/notifications/host-context-changed` — the bridge sets `<meta name="color-scheme" content="…">` and `<html data-theme="…">`:
+- The frame's canvas and form controls match the host (a dark host no longer gets an opaque white frame).
+- Style dark mode with `[data-theme='dark'] …` selectors.
+- `getTheme()` returns the same value; `onContextChange` listeners fire for the handshake context too.
+- Nothing is written when the host sends no theme (the OS fallback `getTheme()` starts with is never applied).
+- A widget styled for light only keeps it with `:root { color-scheme: light }` — author CSS wins over the meta tag.
 ## Host considerations
 | Host                 | Notes                                                                                                                                                                                                                                  |
@@ -209,13 +263,15 @@ What FrontMCP does with it:
 - **Static sizing CSS** — `preferredHeight` (initial `height`), `minHeight`, `maxHeight`, and `aspectRatio` are injected as a `<style>` block on `html` / `body` / `#root`, so the widget opens at the right size before any JS runs.
 - **`_meta` hints** — the same values ride along on the response/discovery `_meta` as `ui/preferredHeight`, `ui/minHeight`, `ui/maxHeight`, `ui/aspectRatio` (and nested under `_meta.ui` in `tools/list`), so hosts that read sizing from metadata pick it up.
-- **Runtime auto-resize** — when `autoResize !== false` and `ResizeObserver` is available, the bridge observes `#root` and reports the measured height to the host (debounced via `requestAnimationFrame`), also firing a `widget:resize` event you can listen for. Call `window.FrontMcpBridge.setSize({ height, width, aspectRatio })` to report manually.
+- **Runtime auto-resize** — when `autoResize !== false` and `ResizeObserver` is available, the bridge observes `<html>`, `<body>` and `#root` and reports the page height to the host (debounced via `requestAnimationFrame`), also firing a `widget:resize` event you can listen for. Call `window.FrontMcpBridge.setSize({ height, width, aspectRatio })` to report manually.
+- **What is measured** — the whole document: `<html>` at `height: fit-content`, plus any content overflowing a fixed-height `<body>`, clamped by a px `max-height` on `<html>`. Body margins and margins collapsed through the body (an `<h2>` or `<ul>` at the edge) are counted, and the height shrinks when content does. `preferredHeight` / `minHeight` / `maxHeight` act as the floor and ceiling.
+- **When it is sent** — auto-resize reports wait for the bridge to initialize. In an ext-apps host the first report is sent after the `ui/initialize` handshake settles. `ui/notifications/size-changed` is a notification, so the host never answers it; it is refused locally (the promise rejects) only when no trusted origin exists, and auto-resize then retries that height on a later observation. A manual `setSize` called before the handshake, with no trusted origin configured, is held and only the latest size is sent right after it. `aspectRatio` stays part of the cross-platform `FrontMcpBridge.setSize` API; the ext-apps adapter leaves it out of the notification payload.
 Per-host behavior:
 - **Claude / static widgets** — the host measures the iframe DOM height itself, so auto-resize is effectively CSS-only (the `setSize` report is a no-op). The injected CSS is what makes a fixed-tall widget (media players, canvases) open without clipping.
 - **OpenAI ChatGPT** — auto-resize forwards to the Apps SDK sizing API when one is exposed; otherwise the SDK's own DOM measurement applies.
-- **ext-apps hosts** — the measured size is reported via a `ui/setSize` request (parallels `ui/setDisplayMode`).
+- **ext-apps hosts** — the measured size is reported with the standard `ui/notifications/size-changed` notification (`{ width, height }` in px), which any spec-compliant host handles.
 - **Gemini / generic / unknown** — `setSize` is a no-op; only the static CSS applies.
 `displayMode: 'fullscreen'` remains a separate, best-effort hint a host may ignore.
@@ -228,7 +284,7 @@ Per-host behavior:
 - [`22-tool-with-ui-html-template`](../examples/22-tool-with-ui-html-template.md) — inline function template
 - [`23-tool-with-ui-filesource-tsx`](../examples/23-tool-with-ui-filesource-tsx.md) — `.tsx` widget, host-detect
-- [`24-tool-with-ui-csp-and-bridge`](../examples/24-tool-with-ui-csp-and-bridge.md) — CSP + `widgetAccessible` + bridge
+- [`24-tool-with-ui-csp-and-bridge`](../examples/24-tool-with-ui-csp-and-bridge.md) — CSP + bridge `callTool`
 ## Related rules

package/catalog/create-tool/rules/widget-paths-anchor-with-import-meta-url.md CHANGED Viewed

@@ -40,11 +40,11 @@ const widgetPath = fileURLToPath(new URL('./sales-chart.widget.tsx', import.meta
 - **`process.cwd()` is whoever launched the process.** `yarn dev` from the repo root, `node dist/main.js` from `/opt/app`, a containerized run from `/`, a serverless cold start from `/var/task`, an Nx executor from `apps/<thing>/` — all different cwds.
 - **Tool sources move around at build time.** ESM build output is often in `dist/`; `.tool.ts` becomes `.tool.js`. The relative reference's resolution chain is fragile to that.
-- **`fileURLToPath(new URL('./x', import.meta.url))` is invariant.** It anchors to the **source file** that contains the URL literal — same answer at dev, build, and runtime.
+- **`fileURLToPath(new URL('./x', import.meta.url))` is independent of cwd.** It anchors to the file that contains the URL literal — the source file under `frontmcp dev`, the **compiled** file once the tool is built. That's why the widget must ship with the build (below).
 ## CommonJS projects (`__dirname`)
-`import.meta.url` is **ESM-only**. In a CommonJS project (`package.json` `"type": "commonjs"`, or `tsconfig` `"module": "commonjs"`) `import.meta` is unavailable and the build fails. Anchor with `__dirname` instead — the CJS equivalent, equally invariant to `process.cwd()`:
+`import.meta.url` is **ESM-only**. In a CommonJS project (`package.json` `"type": "commonjs"`, or `tsconfig` `"module": "commonjs"`) `import.meta` is unavailable and the build fails. Anchor with `__dirname` instead — the CJS equivalent, equally independent of `process.cwd()`:
 ```typescript
 import { join } from 'node:path';
@@ -57,7 +57,14 @@ const widgetPath = join(__dirname, 'sales-chart.widget.tsx');
 })
 ```
-Pick the anchor that matches your module system — both resolve to the tool source's directory regardless of cwd. The rule is only that the path must **never** be a bare relative string.
+Pick the anchor that matches your module system — both resolve to the directory of the file that is running, regardless of cwd. The rule is only that the path must **never** be a bare relative string.
+## Ship the widget with the build (#649)
+The widget is read when the tool is called, from the path the **compiled** tool computes, so after a build it has to exist in the output — tsc never emits `*.widget.tsx`:
+- `frontmcp build` copies every `*.widget.tsx` / `*.widget.jsx` under the entry's directory. tsc-output targets get them next to each compiled tool (same relative path). Bundled targets (`node`, `cli`, `lambda`, `vercel`) get them directly next to the bundle, because every bundled module's `__dirname` is the bundle's directory — so keep each widget beside the tool that uses it and give it a unique file name.
+- A plain `tsc` build copies nothing — add a copy step, or the call fails with an `ENOENT` error that names the path it looked for.
 ## Also: name the widget `*.widget.tsx`

package/catalog/frontmcp-config/examples/configure-throttle/distributed-redis-throttle.md CHANGED Viewed

@@ -9,6 +9,7 @@ features:
   - 'Using `keyPrefix` to namespace guard keys in a shared Redis instance'
   - "Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool"
   - 'In-memory counters are per-process and would allow N times the intended rate with N instances'
+  - "Startup fails closed, and a limited call is refused, with `GuardStorageUnavailableError` when Redis is down, unless `fallback: 'memory'`"
 ---
 # Distributed Rate Limiting with Redis
@@ -86,6 +87,13 @@ class Server {}
 - Using `keyPrefix` to namespace guard keys in a shared Redis instance
 - Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool
 - In-memory counters are per-process and would allow N times the intended rate with N instances
+- Startup fails closed, and a limited call is refused, with `GuardStorageUnavailableError` when Redis is down, unless `fallback: 'memory'`
+## Notes
+- `storage` is the `@frontmcp/utils` storage shape (`type` + `redis: { config }` or `redis: { url }`), not the top-level `redis` shape. A block without `type` is auto-detected from the environment and otherwise runs in memory.
+- Keys read `payments:guard:process_payment:<partition>:rl:...`: a trailing `:` on `keyPrefix` is dropped. Before 1.8.6 it was doubled (`payments:guard::...`), so counters briefly split between versions during a rolling deploy.
+- To keep serving with per-instance counters while Redis is down (at startup or mid-run), add `fallback: 'memory'` to `storage`.
 ## Related

package/catalog/frontmcp-config/references/configure-auth.md CHANGED Viewed

@@ -97,6 +97,7 @@ class Server {}
 - `local.issuer` -- the issuer named everywhere: discovery's `issuer` and `authorization_servers`, the RFC 9207 `iss` on every authorization response (errors included), and the tokens' `iss`. Without it: `FRONTMCP_PUBLIC_URL` (plus the entry path) when pinned, else the `FRONTMCP_PUBLIC_HOST` boot-time issuer (`http://<host>:<port>`), else the request's origin -- the same on the Node server and under `createFetchHandler()`.
 - The protected resource metadata's `scopes_supported` is what the mode grants: `allowedScopes` (local/remote), `anonymousScopes` (public), `scopes` (static), `requiredScopes` then `scopes` (transparent), plus `authProviders` scopes outside local/remote mode.
 - An MCP 2026-07-28 request has no session: anonymous and static-key callers get none minted, so `MCP_SESSION_SECRET` is needed only for session clients; `this.context.verifiedSessionId` is `undefined` there.
+- A session client's `mcp-session-id` (or legacy SSE `?sessionId=`) is served only when `session:verify` verified it: in `public`, `static` and anonymous `transparent` mode it must decrypt under `MCP_SESSION_SECRET` with the mode's signature (static: of the token that opened it); in authenticated modes it must also belong to the caller's token. Any other id gets HTTP 404 (`-32000`) and the client re-initializes -- the raw id is never used to look up a transport, since anonymous sessions share an empty token and the id is their only credential. Run every instance with the same `MCP_SESSION_SECRET`; any instance then serves a session another one minted.
 Token signing uses **HS256, a symmetric secret** read from the `JWT_SECRET` environment variable -- there is **no RSA/EC key pair** and no key store. Generate a stable secret (`JWT_SECRET=$(openssl rand -hex 32)`); if it is unset, FrontMCP falls back to a random per-process secret and all tokens are invalidated on restart.

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

@@ -230,9 +230,11 @@ 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`:
@@ -249,6 +251,22 @@ The config is consumed by every `frontmcp` command, not just `build`:
 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 generated runner script exports `FRONTMCP_HTTP_ENTRY_PATH` (default only; 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 CHANGED Viewed

@@ -260,10 +260,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: