{
  "version": 1,
  "skills": [
    {
      "name": "create-tool",
      "category": "development/create",
      "description": "ALWAYS use this skill when the user asks to build, modify, or audit a FrontMCP tool. Covers everything inside `@Tool({...})`: class and function-style tools, Zod input/output schemas with derived `execute()` types, dependency injection (`this.get` / `this.tryGet`), error handling (`this.fail`, MCP error classes), throttling (rate-limit / concurrency / timeout), auth providers (single / multi / vault), availability constraints (`availableWhen`), elicitation (`this.elicit`), interactive UI widgets via `@Tool({ ui })` (MCP Apps / SEP-1865 — including `.tsx` FileSource, CSP, `window.FrontMcpBridge`, host-detect `resourceMode`), annotations (`readOnlyHint` / `destructiveHint` / …), `examples` metadata, registration in `@App({ tools })`, and per-tool unit testing.",
      "path": "create-tool",
      "targets": ["all"],
      "hasResources": true,
      "layout": "component",
      "tags": [
        "development",
        "tool",
        "create-tool",
        "decorator",
        "input-schema",
        "output-schema",
        "ToolContext",
        "ui",
        "mcp-apps",
        "annotations",
        "throttling",
        "auth-providers",
        "availability",
        "elicitation"
      ],
      "bundle": ["recommended", "minimal", "full"],
      "priority": 10,
      "references": [
        {
          "name": "annotations",
          "description": "readOnlyHint, destructiveHint, idempotentHint, openWorldHint, title — behavioral hints for clients."
        },
        {
          "name": "auth-providers",
          "description": "authProviders shorthand vs full mapping, scopes, alias, credential vault basics."
        },
        {
          "name": "availability",
          "description": "availableWhen axes (os / runtime / deployment / provider / target / surface / env), missingAxes, isPlatform, and enabled (fileSignal, FEATURE_OFF, list_changed, the surface hash, STALE_TOOL_LIST)."
        },
        {
          "name": "decorator-options",
          "description": "Every field on @Tool({...}) — what it does, default, when to set it."
        },
        {
          "name": "derived-types",
          "description": "Derive execute() parameter and return types from the schemas via ToolInputOf / ToolOutputOf."
        },
        {
          "name": "elicitation",
          "description": "this.elicit — request interactive input mid-execution. Server enable + accept/decline/cancel flow."
        },
        {
          "name": "error-handling",
          "description": "this.fail, MCP error classes, refused() and remedies, error flow — when to throw vs fail."
        },
        {
          "name": "execution-context",
          "description": "What ToolContext provides at runtime — this.get, this.fetch, this.notify, this.context."
        },
        {
          "name": "file-layout",
          "description": "Flat sibling vs folder-per-tool layouts. <name>.schema.ts / <name>.tool.ts / <name>.tool.spec.ts."
        },
        {
          "name": "function-style-builder",
          "description": "tool({...})(handler) — when to pick over a class, register, ctx parameter."
        },
        {
          "name": "input-schema",
          "description": "Define the tool's input contract — raw Zod shapes, refinements, defaults, optional fields."
        },
        {
          "name": "output-schema",
          "description": "Define the tool's output contract — Zod shape, primitives, media, multi-content arrays."
        },
        { "name": "quick-start", "description": "60-second tour — minimal tool, schemas, registration, calling it." },
        { "name": "registration", "description": "@App({ tools }) vs @FrontMcp({ tools }), multi-app composition." },
        {
          "name": "remote-and-esm",
          "description": "Tool.esm / Tool.remote — load tools from npm packages or remote MCP servers."
        },
        {
          "name": "testing",
          "description": "Per-tool unit tests — pointer to the dedicated `testing` skill for the canonical patterns."
        },
        { "name": "throttling", "description": "rateLimit, concurrency, timeout — semantics, interaction, defaults." },
        {
          "name": "ui-widgets",
          "description": "@Tool({ ui }) — template formats, trusted markup (html / escapeStringResults), servingMode, host-detect resourceMode, CSP, ignored options, MCP Apps spec."
        }
      ],
      "examples": [
        {
          "name": "01-basic-class-tool",
          "description": "Minimal class-based tool with Zod input/output schemas and types derived from the schemas. The foundation every other example builds on.",
          "level": "basic",
          "tags": ["foundation", "class-tool", "output-schema", "derived-types"],
          "features": [
            "Extending `ToolContext` (no generics) and implementing `execute()`",
            "Hoisting `inputSchema` / `outputSchema` to a sibling `.schema.ts` file",
            "Deriving the `execute()` parameter and return types via `ToolInputOf<>` / `ToolOutputOf<>`",
            "Using a Zod raw shape for `inputSchema` (not `z.object(...)`)",
            "Always defining `outputSchema` so the tool can't accidentally leak extra fields",
            "Registering the tool in an `@App({ tools })`"
          ]
        },
        {
          "name": "02-basic-function-tool",
          "description": "Function-style `tool({...})(handler)` for a tiny pure-input tool — pick this over a class only when the tool needs no DI / lifecycle / UI.",
          "level": "basic",
          "tags": ["foundation", "function-tool", "tool-builder"],
          "features": [
            "Using the `tool({...})(handler)` builder for a one-liner",
            "Returning a primitive via `outputSchema: 'number'`",
            "Registering the function-style tool in `@App({ tools })` exactly like a class tool",
            "When function-style is the right choice (and when it isn't)"
          ]
        },
        {
          "name": "03-tool-with-zod-shape-output",
          "description": "Tool returning structured JSON declared via a Zod raw shape outputSchema — the recommended pattern for any complex output.",
          "level": "basic",
          "tags": ["output-schema", "zod-shape", "structured-output"],
          "features": [
            "Declaring `outputSchema` as a Zod raw shape `{ field: z.string(), … }`",
            "Constraining values with `.int().min(0)` so invalid output is rejected at the boundary",
            "Letting unrelated fields returned by the implementation (e.g. an upstream API's extras) be stripped silently",
            "Deriving `OrderSummaryOutput` once so the type and runtime contract can't drift"
          ]
        },
        {
          "name": "04-tool-with-zod-schema-output",
          "description": "Tool returning a discriminated union via a full `z.discriminatedUnion(...)` outputSchema — for outputs that branch on a kind field.",
          "level": "advanced",
          "tags": ["output-schema", "zod-schema", "discriminated-union"],
          "features": [
            "Using a full Zod schema (`z.discriminatedUnion(...)`) as `outputSchema` instead of a raw shape",
            "Branching the runtime output on a discriminant `kind` literal",
            "Letting TypeScript narrow the return type per branch (via `as const` on the discriminant)",
            "Knowing when full Zod schemas are the right pick (unions, transforms) and when a raw shape is enough"
          ]
        },
        {
          "name": "05-tool-with-primitive-output",
          "description": "Tool returning a single primitive — `outputSchema: 'string' | 'number' | 'boolean' | 'date'` for single-value outputs.",
          "level": "basic",
          "tags": ["output-schema", "primitive-output"],
          "features": [
            "Using a primitive literal (`'string'`, `'number'`, `'boolean'`, `'date'`) for `outputSchema`",
            "Returning the bare value directly from `execute()` instead of wrapping it",
            "Picking primitive literals over a one-field Zod shape for ergonomic clarity",
            "Four concrete tools in one file (`fmt_currency`, `add`, `is_palindrome`, `now`) demonstrating each primitive form"
          ]
        },
        {
          "name": "06-tool-with-media-output",
          "description": "Tool returning binary content (image / audio) or a multi-content array of `[text, image]` — for outputs that aren't plain JSON.",
          "level": "intermediate",
          "tags": ["output-schema", "media-output", "image", "multi-content"],
          "features": [
            "Returning a base64-encoded image with `outputSchema: 'image'` and `{ type: 'image', data, mimeType }`",
            "Returning audio with `outputSchema: 'audio'` (same `{ type: 'audio', data, mimeType }` shape, audio MIME types)",
            "Returning multi-content via `outputSchema: ['string', 'image']` — text summary + annotated image in one response",
            "When to pick a media literal vs `'resource_link'` (host-fetched URI)"
          ]
        },
        {
          "name": "08-tool-with-provider-injection",
          "description": "Tool that resolves a DI-registered service via `this.get(TOKEN)` and uses it to power `execute()` — the standard pattern for tools that talk to a database or external API.",
          "level": "intermediate",
          "tags": ["di", "provider", "this.get", "error-handling"],
          "features": [
            "Defining a typed DI token with `Symbol('UserService')` and `Token<UserService>`",
            "Binding the token with a factory provider (`{ name, provide, inject, useFactory }`) and registering it in the same `@App` as the tool",
            "Resolving the service inside `execute()` via `this.get(USER_SERVICE)` (throws when missing)",
            "Translating \"not found\" into `ResourceNotFoundError` via `this.fail(...)` so the client gets a proper MCP error code (-32002)"
          ]
        },
        {
          "name": "09-tool-with-multiple-providers",
          "description": "Tool composing three DI services — config (env-only), cache (optional, `tryGet`), and database (required) — the realistic shape for a production tool.",
          "level": "intermediate",
          "tags": ["di", "multiple-providers", "cache-aside", "tryGet"],
          "features": [
            "Resolving multiple providers via `this.get(TOKEN)` and `this.tryGet(TOKEN)`",
            "Cache-aside pattern — check `tryGet(CACHE)` first, fall back to the database",
            "Reading typed config from a `CONFIG` token vs `process.env` directly",
            "Letting the tool work in production (with cache) AND in test (without it)"
          ]
        },
        {
          "name": "11-tool-with-fetch",
          "description": "Tool calling an external HTTP API with `this.fetch` — context propagation, status-code handling, and bounding the call with a tool `timeout`.",
          "level": "intermediate",
          "tags": ["fetch", "http", "external-api", "error-handling"],
          "features": [
            "Using `this.fetch(url, init?)` so trace context propagates to the upstream service",
            "Translating non-2xx HTTP responses into `PublicMcpError` so the MCP client gets a clean error",
            "Bounding the call with a tool `timeout` (and `this.fetch`'s built-in per-request timeout) — without relying on a non-existent context abort signal",
            "Letting genuine network errors (DNS failure, ECONNREFUSED) propagate to the framework's error flow"
          ]
        },
        {
          "name": "12-tool-with-fetch-and-retries",
          "description": "Tool calling a flaky external API with exponential backoff retries, an Idempotency-Key for safety, and respect for `Retry-After` on 429s.",
          "level": "advanced",
          "tags": ["fetch", "retries", "exponential-backoff", "idempotency-key", "429-rate-limit"],
          "features": [
            "Retrying on transient errors (5xx + 429) with exponential backoff plus jitter",
            "Generating an `Idempotency-Key` so retried POSTs don't duplicate side effects on the upstream",
            "Respecting an upstream `Retry-After` header on 429 responses instead of guessing",
            "Capping the total retry budget with `timeout: { executeMs }` so a wedged upstream can't hang the call indefinitely"
          ]
        },
        {
          "name": "13-tool-with-single-auth-provider",
          "description": "Tool requiring a single OAuth provider via the `authProviders: ['github']` string shorthand — credentials loaded before `execute()` runs.",
          "level": "intermediate",
          "tags": ["auth-providers", "oauth", "github", "this.authProviders"],
          "features": [
            "Declaring a single required OAuth provider with the `authProviders: ['github']` shorthand",
            "Reading pre-formatted credentials via `await this.authProviders.headers('github')`",
            "Letting the framework reject calls whose required credential is missing **before** `execute()` runs — a JSON-RPC `-32001` (MCP `UNAUTHORIZED`) error whose `data` carries `{ tool, providers: ['github'], authUrl }` (no auth-check boilerplate)",
            "Trusting the framework to handle token refresh, expiration, and the connect/authorize URL"
          ]
        },
        {
          "name": "14-tool-with-multiple-auth-providers",
          "description": "Tool with the full `authProviders` mapping form — one required provider with explicit scopes, one optional provider with an alias, and graceful degradation when the optional creds are missing.",
          "level": "advanced",
          "tags": ["auth-providers", "oauth", "scopes", "optional-auth", "this.authProviders.headers"],
          "features": [
            "Using the object form of `authProviders` to set `required`, `scopes`, and `alias`",
            "Declaring required OAuth scopes that the server advertises in its Protected Resource Metadata (`scopes_supported`) so clients request them",
            "Resolving an optional provider via `await this.authProviders.headers('cloud')` (returns an empty object `{}` when absent)",
            "Branching the tool's behavior — full deploy when both providers are present; preview-only when the cloud provider is missing",
            "The required `github` provider gating the call: when its credential is missing the framework aborts before `execute()` with `-32001` and `data: { tool, providers: ['github'], authUrl }`; the optional `aws`/`cloud` provider never gates"
          ]
        },
        {
          "name": "15-tool-with-credential-vault",
          "description": "Tool that reads a user-supplied static credential (a Slack webhook URL) from the per-session encrypted credential vault — the pattern for credentials that aren't OAuth.",
          "level": "advanced",
          "tags": ["auth-providers", "credential-vault", "slack-webhook", "encryption-at-rest"],
          "features": [
            "Declaring a vault-backed auth provider with `authProviders: ['slack-webhook']`",
            "Reading the user's pasted-in credential via `await this.authProviders.headers('slack-webhook')` — same API as OAuth",
            "Letting the framework handle per-session AES-256-GCM encryption at rest (Redis or memory store)",
            "Knowing when to pick the vault (static secrets the user knows) vs OAuth (delegated identity)"
          ]
        },
        {
          "name": "16-tool-with-rate-limit",
          "description": "Tool with `rateLimit: { maxRequests, windowMs }` capping invocations per session per minute — the protection for expensive / external-API-billed operations.",
          "level": "intermediate",
          "tags": ["throttling", "rate-limit", "abuse-protection"],
          "features": [
            "Capping the tool to N invocations per windowMs, partitioned per session via `partitionBy: 'session'`",
            "Letting the framework reject over-limit calls with `RateLimitError` (code `'RATE_LIMIT_EXCEEDED'`, HTTP status 429) carrying a retry-after hint in its message that clients can back off against",
            "Combining `rateLimit` with `annotations.openWorldHint: true` so clients know the tool talks to billed external services",
            "Sizing the limit against upstream quota / billing — not just \"what feels reasonable\""
          ]
        },
        {
          "name": "17-tool-with-concurrency-and-timeout",
          "description": "Tool with `concurrency` + `timeout` for a real bottleneck (PDF rendering) — caps simultaneous in-flight work AND hard-caps per-call duration.",
          "level": "advanced",
          "tags": ["throttling", "concurrency", "timeout"],
          "features": [
            "Capping simultaneous in-flight executions with `concurrency: { maxConcurrent }` (server-wide by default)",
            "Hard-bounding any single call with `timeout: { executeMs }` so a wedged invocation can't hold a concurrency slot indefinitely",
            "Giving long child work its own deadline, since `timeout` bounds `execute()` but does not pass an abort signal into it",
            "Combining `rateLimit` + `concurrency` + `timeout` as a production triple"
          ]
        },
        {
          "name": "18-tool-with-progress-and-notify",
          "description": "Long-running tool emitting progress updates (`this.progress`), log notifications (`this.notify`), and stage markers (`this.mark`) — the standard pattern for jobs you don't want to feel hung.",
          "level": "intermediate",
          "tags": ["progress", "notifications", "mark", "long-running"],
          "features": [
            "Emitting per-item progress with `await this.progress(current, total, message)`",
            "Sending free-form log notifications at `info` / `warning` / `error` levels with `await this.notify(message, level)`",
            "Marking execution stages with `this.mark(stage)` so observability tools have breadcrumbs",
            "Letting `this.progress(...)` return `false` cheaply when no progress token was provided (zero-cost when nobody's listening)"
          ]
        },
        {
          "name": "19-tool-with-elicitation",
          "description": "Tool that pauses mid-execution to ask the user for confirmation + extra input via `this.elicit(...)` — the safe pattern for destructive or expensive actions.",
          "level": "advanced",
          "tags": ["elicitation", "this.elicit", "destructive-action", "confirmation"],
          "features": [
            "Calling `this.elicit(message, z.object({ ... }))` to request interactive input mid-`execute()`",
            "Branching on `result.status` — `accept` / `decline` / `cancel` — and matching the early returns against `outputSchema`",
            "Pairing elicitation with `annotations.destructiveHint: true` so clients know to render the confirmation prominently",
            "Requiring `elicitation: { enabled: true }` at the `@FrontMcp({...})` server level — and what fails when it isn't"
          ]
        },
        {
          "name": "20-tool-with-annotations",
          "description": "Four tools showing the standard annotation combinations — read-only query, destructive delete, send-email side-effecting, external-API search — and the client behavior each combination opts into.",
          "level": "basic",
          "tags": ["annotations", "readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"],
          "features": [
            "Setting `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint` to opt into specific client behaviors (auto-retry, confirmation gating, parallelization)",
            "Providing a human-readable `title` that overrides the snake_case `name` in client UIs",
            "Picking the conservative defaults when the annotations aren't obvious (omitting fields is safer than guessing)",
            "Why `send_email` sets `idempotentHint: false` (each call sends a new email) while `delete_user` sets it to `true` (deleting twice still leaves the user deleted)"
          ]
        },
        {
          "name": "21-tool-with-availability-constraints",
          "description": "Three tools showing the `availableWhen` axes — macOS-only OS gate, production+Node runtime gate, and a `surface` gate that allows agent + job invocation but blocks direct MCP-client calls.",
          "level": "advanced",
          "tags": ["availableWhen", "os", "runtime", "surface", "EntryUnavailableError"],
          "features": [
            "Restricting a tool to macOS with `availableWhen: { os: ['darwin'] }`",
            "Composing constraints — `runtime: ['node']` AND `env: ['production']` — both must match for the tool to be available",
            "Using the `surface` axis to expose an internal tool to agents and jobs while hiding it from direct user invocation",
            "Knowing what happens on mismatch — `EntryUnavailableError` (`-32003` FORBIDDEN) with `data.missingAxes` so clients show the right \"not available here\" reason"
          ]
        },
        {
          "name": "22-tool-with-ui-html-template",
          "description": "Tool with an inline HTML function template — ``ui: { template: (ctx) => ctx.helpers.html`<div>…</div>` }`` — for a quick widget that doesn't need a separate `.tsx` file.",
          "level": "intermediate",
          "tags": ["ui", "ui-widgets", "html-template", "html-tag", "escapeStringResults", "TemplateContext"],
          "features": [
            "Adding a `ui:` block with a function template that returns markup built with the `ctx.helpers.html` tagged template",
            "Annotating `ctx` explicitly to dodge the TS7006 inference gap on the union `ui.template` type",
            "Letting `ctx.helpers.html` escape every interpolated value so tool output can't inject markup into the widget",
            "Relying on the default since 1.9.2 (`escapeStringResults` unset), which escapes any plain string result while `html` results stay markup",
            "Reading from `ctx.output` and `ctx.helpers` — the typed runtime context the template renderer hands you"
          ]
        },
        {
          "name": "23-tool-with-ui-filesource-tsx",
          "description": "Tool with a `.tsx` widget in a separate file via the `FileSource` form — the recommended pattern for any React widget. Path anchored with `import.meta.url` so it survives any cwd.",
          "level": "advanced",
          "tags": ["ui", "ui-widgets", "FileSource", "tsx", "import.meta.url", "host-detect"],
          "features": [
            "Pointing `template` at a sibling `.tsx` file via the `FileSource` form `{ file: ... }`",
            "Anchoring the path to the tool source with `fileURLToPath(new URL('./...widget.tsx', import.meta.url))` so `process.cwd()` doesn't matter",
            "Leaving `resourceMode` unset — the framework host-detects (`'inline'` for Claude, `'cdn'` for others)",
            "Naming the widget `*.widget.tsx` so the scaffolded `tsconfig.json`'s `exclude` keeps it out of the server typecheck"
          ]
        },
        {
          "name": "24-tool-with-ui-csp-and-bridge",
          "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.",
          "level": "advanced",
          "tags": ["ui", "csp", "callTool", "FrontMcpBridge", "interactive-widget"],
          "features": [
            "Restricting the widget's outbound `fetch` via `ui.csp.connectDomains` (emitted on the resource per #455)",
            "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"
          ]
        },
        {
          "name": "25-tool-handing-off-to-job",
          "description": "Thin tool that validates input and enqueues a `@Job` to do the heavy lifting — the right pattern for any operation that takes more than a few seconds.",
          "level": "advanced",
          "tags": ["composition", "jobs", "job-handoff", "hideFromDiscovery"],
          "features": [
            "Splitting a long-running operation into a thin tool (validates, enqueues, returns a tracking handle) plus a `@Job` (does the work)",
            "Returning the job ID + status URL from the tool so the client can poll or stream updates",
            "Using `availableWhen: { surface: ['mcp', 'agent'] }` on the tool while leaving the heavy `@Job` invisible to direct invocation",
            "Why this beats running the heavy work inside `execute()` (avoids tool-call timeout limits, lets the job retry independently)"
          ]
        },
        {
          "name": "26-tool-with-resource-link-output",
          "description": "Tool returning `outputSchema: 'resource_link'` — the URI is sent to the client; the client fetches the body via `resources/read`. The right pattern for large or cacheable payloads.",
          "level": "advanced",
          "tags": ["output-schema", "resource_link", "large-payload", "caching"],
          "features": [
            "Returning `outputSchema: 'resource_link'` from a tool — `{ type: 'resource_link', uri }`, body fetched separately",
            "Pairing the tool with a matching `@Resource({ uri: 'export://{exportId}.csv' })` URI template that resolves to the actual body",
            "When `'resource_link'` beats `'image'` / `'audio'` / a raw byte response (large payloads, cacheable URIs, deferred fetch)",
            "Cross-linking to the `create-resource` skill for the URI-template resource on the other end"
          ]
        },
        {
          "name": "27-tool-with-examples-metadata",
          "description": "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.",
          "level": "basic",
          "tags": ["examples-metadata", "codecall", "describe"],
          "features": [
            "Adding `examples: [{ description, input, output? }]` to `@Tool({...})` so `codecall:describe` surfaces canned invocations",
            "Writing realistic example inputs so the generated describe output is concrete, not abstract",
            "Including `output?` for examples where showing the expected result helps an agent understand the tool",
            "Why `examples` are advisory metadata — not emitted in `tools/list`, only consumed by `codecall:describe`"
          ]
        }
      ],
      "rules": [
        {
          "name": "always-define-output-schema",
          "constraint": "Every `@Tool` defines `outputSchema`.",
          "severity": "required"
        },
        {
          "name": "derive-execute-types",
          "constraint": "`execute()` parameter and return types come from `ToolInputOf<>` / `ToolOutputOf<>` — never duplicated inline.",
          "severity": "required"
        },
        {
          "name": "input-schema-is-raw-shape",
          "constraint": "`inputSchema` is a raw Zod shape, never `z.object(...)`.",
          "severity": "required"
        },
        {
          "name": "no-toolcontext-generics",
          "constraint": "`class MyTool extends ToolContext` — never `extends ToolContext<typeof inputSchema>`.",
          "severity": "required"
        },
        {
          "name": "no-try-catch-around-execute",
          "constraint": "Do not wrap the body of `execute()` in `try/catch`. The framework owns the error flow.",
          "severity": "required"
        },
        {
          "name": "register-in-app",
          "constraint": "Register tools in `@App({ tools })`, not directly on `@FrontMcp({ tools })` (the latter is the simple-server escape hatch).",
          "severity": "recommended"
        },
        {
          "name": "snake-case-tool-names",
          "constraint": "Tool `name:` field is always `snake_case` (e.g. `get_weather`, not `getWeather`).",
          "severity": "required"
        },
        {
          "name": "use-this-fail-for-business-errors",
          "constraint": "`this.fail(new SomeMcpError(...))` for business-logic errors — never raw `throw new Error(...)`.",
          "severity": "required"
        },
        {
          "name": "widget-paths-anchor-with-import-meta-url",
          "constraint": "`.tsx` widget paths in `ui.template: { file }` are anchored via `fileURLToPath(new URL(...))`, never bare relative.",
          "severity": "required"
        },
        {
          "name": "widget-resource-mode-host-detect",
          "constraint": "Leave `ui.resourceMode` unset — the framework host-detects (`inline` for Claude, `cdn` for others).",
          "severity": "recommended"
        }
      ]
    },
    {
      "name": "frontmcp-auth-ui",
      "category": "config",
      "description": "Use when customizing, branding, or replacing the built-in FrontMCP OAuth pages (the login, consent, federated-select, incremental-authorization, and error pages) with your own React components. Covers the auth.ui slot-to-file map and auth.extras name-to-handler map on the auth config (no decorator, no class); the @frontmcp/ui/auth React hooks, the AuthPageWrapper component, and mountAuthPage (client-rendered via an esm.sh import-map plus a per-file server-side transform, with no bundling and no SSR); and the framework-owned CSRF and CSP. Triggers: custom login page, brand the consent screen, replace the OAuth UI, custom authorization UI, style the auth pages, multi-step login. The skill for CUSTOM AUTHORIZATION UI (distinct from auth config in frontmcp-config and permissions in frontmcp-authorities).",
      "path": "frontmcp-auth-ui",
      "targets": ["all"],
      "hasResources": true,
      "tags": ["auth", "auth-ui", "login", "consent", "custom-ui", "react", "oauth", "guide"],
      "bundle": ["full"],
      "priority": 5,
      "references": [
        {
          "name": "custom-auth-ui",
          "description": "Replace FrontMCP's built-in OAuth pages with custom React components using the auth.ui slot→file map and auth.extras name→handler map (no decorator, no class) plus the @frontmcp/ui/auth hooks.",
          "examples": [
            {
              "name": "login-slot",
              "description": "Replace the built-in login page with a custom React component via auth.ui: { login: './login.tsx' } and useAuthFlow, while the framework keeps owning CSRF and CSP.",
              "level": "intermediate",
              "tags": ["auth", "auth-ui", "login", "custom-ui", "react", "client-rendered"],
              "features": [
                "Mapping a slot to a `.tsx` file with `auth.ui: { login: './login.tsx' }` (the supported render path)",
                "Using a RELATIVE path auto-anchored to the config file — no `fileURLToPath`, no decorator, no class",
                "Reading the injected `AuthFlowState` via `useAuthFlow()` and submitting with `<form onSubmit={submitFinish}>`",
                "Letting `<AuthPageWrapper>` render the enclosing finish `<form>` with the `pending_auth_id` + `csrf` hidden fields",
                "The SDK transpiling the `.tsx` server-side and inlining it as an ES module (deps from esm.sh via an import-map) + appending the `mountAuthPage` call automatically"
              ]
            },
            {
              "name": "multi-step-auth-extra",
              "description": "Add a server-validated multi-step field to a custom login page with auth.extras: { 'envs:add': fn }, useExtraField, and useAddedItems — accepted rows accumulate server-side and reflect back without a reload.",
              "level": "advanced",
              "tags": ["auth", "auth-ui", "auth-extras", "useExtraField", "useAddedItems", "multi-step", "react"],
              "features": [
                "Declaring a server-validated field as an `auth.extras['envs:add']` handler fn returning `{ ok, error?, addedItems? }`",
                "Rejecting bad input and duplicates using `ctx.current` (the items already accepted for this extra in this flow)",
                "Binding the add-row form to `useExtraField('envs:add').onSubmit` (POSTs to `/oauth/ui/extra` with `pending_auth_id` + `csrf` attached)",
                "Reflecting the server-side accumulator reactively with `useAddedItems('envs:add')` after each successful add",
                "Declaring both the `auth.ui` slot and the `auth.extras` handler under `auth`: `@FrontMcp({ auth: { mode, ui, extras } })`"
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "frontmcp-authorities",
      "category": "development",
      "description": "Use when implementing authorization and access control for FrontMCP tools, resources, prompts, or skills, deciding who may invoke what. Covers the RBAC, ABAC, and ReBAC models and when to choose each; JWT claims mapping per identity provider (Auth0, Keycloak, Okta, Cognito, Frontegg); reusable named authority profiles; and custom authority evaluators for domain-specific policy. This is about who-can-do-what (permissions, roles, scopes), distinct from configuring auth modes and login (see frontmcp-config) and custom login UI (see frontmcp-auth-ui). Triggers: authorization, access control, RBAC, ABAC, ReBAC, permissions, roles, scopes, policy enforcement, JWT claims, restrict who can call a tool.",
      "path": "frontmcp-authorities",
      "targets": ["all"],
      "hasResources": true,
      "tags": [
        "authorization",
        "rbac",
        "abac",
        "rebac",
        "security",
        "permissions",
        "roles",
        "access-control",
        "authorities",
        "jwt"
      ],
      "bundle": ["full"],
      "priority": 9,
      "references": [
        {
          "name": "authority-profiles",
          "description": "Registering, composing, and using named authority profiles for reusable authorization policies",
          "examples": []
        },
        {
          "name": "claims-mapping",
          "description": "JWT claims mapping configuration per identity provider (Auth0, Keycloak, Okta, Cognito, Frontegg) for the authorities system",
          "examples": []
        },
        {
          "name": "custom-evaluators",
          "description": "Creating and registering custom authority evaluators for domain-specific authorization logic beyond RBAC, ABAC, and ReBAC",
          "examples": []
        },
        {
          "name": "rbac-abac-rebac",
          "description": "Comparison of RBAC, ABAC, and ReBAC authorization models with when to use each, policy syntax, and examples",
          "examples": []
        }
      ]
    },
    {
      "name": "frontmcp-channels",
      "category": "development",
      "description": "Use when pushing real-time notifications or events into Claude Code (or another MCP client) sessions, or building two-way chat bridges. Covers channel source types: incoming webhooks (such as GitHub), app error events, agent-completion and job-completion alerts, service connectors, file watchers, and replay buffers; plus two-way conversational bridges connecting WhatsApp, Telegram, Slack, and Discord to a Claude Code session. Triggers: push notifications, real-time alerts, webhook channel, chat bridge, WhatsApp / Telegram / Slack / Discord, agent completion alert, job status notification, error forwarding, server-to-client messaging. The skill for CHANNELS and NOTIFICATIONS.",
      "path": "frontmcp-channels",
      "targets": ["all"],
      "hasResources": true,
      "tags": [
        "channels",
        "notifications",
        "claude-code",
        "webhooks",
        "messaging",
        "real-time",
        "two-way",
        "whatsapp",
        "telegram",
        "slack",
        "chat-bridge"
      ],
      "bundle": ["full"],
      "priority": 8,
      "references": [
        {
          "name": "channel-sources",
          "description": "Configure different channel source types - webhooks, app events, agent/job completion, service connectors, file watchers, and manual push",
          "examples": [
            {
              "name": "agent-notify",
              "description": "Notify Claude Code when AI agents complete their tasks",
              "level": "intermediate",
              "tags": ["agents", "completion", "notifications", "automation"],
              "features": [
                "Agent completion source with ID filtering",
                "Duration and output reporting",
                "Integration with agent registry emitter"
              ]
            },
            {
              "name": "app-errors",
              "description": "Forward application errors to Claude Code via the in-process event bus",
              "level": "basic",
              "tags": ["errors", "app-event", "debugging", "monitoring"],
              "features": [
                "App event source with ChannelEventBus",
                "Error severity classification",
                "Stack trace forwarding"
              ]
            },
            {
              "name": "file-watcher",
              "description": "Watch files for changes and notify Claude Code in real-time",
              "level": "intermediate",
              "tags": ["file-watcher", "filesystem", "logs", "monitoring", "real-time"],
              "features": [
                "File watcher source type with glob patterns",
                "onConnect lifecycle for starting the watcher",
                "pushIncoming for streaming file events",
                "Log file monitoring example"
              ]
            },
            {
              "name": "job-completion",
              "description": "Notify Claude Code when background jobs and workflows complete",
              "level": "intermediate",
              "tags": ["jobs", "workflows", "completion", "background", "notifications"],
              "features": [
                "Job completion source with name filtering",
                "Status-aware notification formatting",
                "Duration and output reporting"
              ]
            },
            {
              "name": "replay-buffer",
              "description": "Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline.",
              "level": "advanced",
              "tags": ["replay", "buffer", "persistence", "offline", "reconnect"],
              "features": [
                "Replay configuration with `maxEvents` cap",
                "In-memory ring buffer for event storage",
                "Where `replayBufferedEvents` actually lives (on `ChannelInstance`, not on `ChannelContext`)",
                "Persistent store pattern with `onConnect` and a user-defined Redis provider"
              ]
            },
            {
              "name": "service-connector",
              "description": "Build a persistent service connector that lets Claude send and receive messages through WhatsApp, Telegram, or any messaging API",
              "level": "advanced",
              "tags": ["service", "connector", "whatsapp", "persistent-connection", "bidirectional"],
              "features": [
                "Service source type with onConnect/onDisconnect lifecycle",
                "Channel-contributed tools for outbound messages",
                "pushIncoming() for feeding service events into the notification pipeline",
                "Bidirectional conversation flow"
              ]
            },
            {
              "name": "webhook-github",
              "description": "Forward GitHub webhook events (PRs, pushes, CI) into Claude Code",
              "level": "basic",
              "tags": ["webhook", "github", "ci", "notifications"],
              "features": [
                "Webhook source with HTTP POST endpoint",
                "GitHub event type routing",
                "Static meta for team context"
              ]
            }
          ]
        },
        {
          "name": "channel-two-way",
          "description": "Build two-way chat bridges connecting WhatsApp, Telegram, Slack, and Discord to Claude Code",
          "examples": [
            {
              "name": "whatsapp-bridge",
              "description": "Full WhatsApp Business API bridge allowing users to chat with Claude Code via WhatsApp",
              "level": "advanced",
              "tags": ["whatsapp", "chat", "two-way", "messaging", "bridge"],
              "features": [
                "Two-way channel with reply support",
                "WhatsApp Cloud API integration",
                "Sender verification and allowlisting",
                "Webhook signature validation"
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "frontmcp-config",
      "category": "config",
      "description": "Use when configuring a FrontMCP server through frontmcp.config or the @FrontMcp options. Covers auth modes (public, transparent, local, remote), OAuth plus credential vault and secureStore, CORS, HTTP port / entry-path prefix / unix socket, security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options), rate limiting / throttling / concurrency / timeout / IP filtering (GuardConfig), session storage (Redis, Vercel KV), client transport protocols (SSE, Streamable HTTP, stateless, protocol presets), elicitation, multi-target build config, and skillsConfig (HTTP catalog, caching, audit log, instruction injection). Triggers: configure auth, set up CORS, add rate limiting, throttle requests, manage sessions, choose transport, set HTTP options, configure JWT or OAuth. The skill for server CONFIGURATION.",
      "path": "frontmcp-config",
      "targets": ["all"],
      "hasResources": true,
      "tags": ["router", "config", "transport", "http", "auth", "session", "redis", "sqlite", "throttle", "guide"],
      "bundle": ["recommended", "full"],
      "priority": 10,
      "references": [
        {
          "name": "configure-auth-modes",
          "description": "Detailed comparison of public, static, transparent, local, and remote auth modes",
          "examples": [
            {
              "name": "local-behind-tunnel",
              "description": "Expose a local-mode server through a tunnel or TLS proxy by aligning the token issuer with the public URL clients actually reach.",
              "level": "intermediate",
              "tags": ["config", "auth", "local", "tunnel", "proxy", "issuer", "auth-modes"],
              "features": [
                "Relying on request-host-derived OAuth discovery, which works behind a tunnel or under an http.entryPath without extra config",
                "Setting `local.issuer` to a full public HTTPS URL so the token `iss` matches what clients reach through the proxy",
                "Knowing the issuer order: `local.issuer`, then `FRONTMCP_PUBLIC_URL`, then `FRONTMCP_PUBLIC_HOST` (host only), then the request"
              ]
            },
            {
              "name": "local-consent-enforcement",
              "description": "Enable consent in local mode to render a tool-selection screen at login and enforce the chosen tools at call time, keeping essential tools always available via excludedTools.",
              "level": "intermediate",
              "tags": ["config", "auth", "local", "consent", "tool-authorization", "auth-modes"],
              "features": [
                "Setting `consent.enabled` so login renders a tool-selection screen and the chosen tools are enforced on every tools/call",
                "Listing `excludedTools` so essential tools are never offered and are always available",
                "Honoring `requireSelection` / `defaultSelectedTools` to require a non-empty selection and pre-check tools",
                "Pinning `rememberConsent: false` to re-show the screen on every login (the default `true` reuses a prior per-(user, client) selection and only re-prompts when a NEW tool appears)"
              ]
            },
            {
              "name": "local-dcr-control",
              "description": "Lock down the built-in Dynamic Client Registration endpoint with the auth.dcr control surface: disable open registration, allowlist redirect URIs and client ids, and seed a pre-registered trusted client.",
              "level": "intermediate",
              "tags": ["config", "auth", "local", "dcr", "dynamic-client-registration", "security", "auth-modes"],
              "features": [
                "Setting `dcr.enabled: false` so `POST /oauth/register` returns 404 and `registration_endpoint` is dropped from AS metadata",
                "Constraining `dcr.allowedRedirectUris` (exact or `*` glob) so unlisted redirect URIs are rejected at both register and authorize",
                "Constraining `dcr.allowedClientIds` so only known client ids may use `/oauth/authorize`",
                "Seeding `dcr.clients` so a trusted client is accepted without any DCR round-trip"
              ]
            },
            {
              "name": "local-minimal",
              "description": "Stand up the built-in local OAuth 2.1 server with the minimum configuration: HS256 signing via JWT_SECRET and in-memory token storage.",
              "level": "basic",
              "tags": ["config", "auth", "local", "hs256", "auth-modes", "modes"],
              "features": [
                "Using `mode: 'local'` with no other auth options to run the built-in OAuth 2.1 server",
                "Relying on `JWT_SECRET` for HS256 token signing (symmetric secret, no key pair)",
                "Accepting the default in-memory `tokenStorage` for local development (state is lost on restart)"
              ]
            },
            {
              "name": "local-multi-provider-orchestration",
              "description": "Orchestrate multiple upstream OAuth providers (GitHub + Slack) in local mode, gate the JWT until they are linked, and read downstream tokens in tools via this.orchestration.",
              "level": "advanced",
              "tags": [
                "config",
                "auth",
                "local",
                "orchestration",
                "federated",
                "providers",
                "multi-provider",
                "auth-modes"
              ],
              "features": [
                "Declaring an `auth.providers` array so FrontMCP federates GitHub + Slack at /oauth/authorize and stores their tokens encrypted server-side",
                "Using `authorizeUrl`/`tokenUrl` aliases and letting the per-provider callback URL be auto-computed as ${issuer}/oauth/provider/${id}/callback",
                "Gating JWT issuance with `federatedAuth.minProviders` / `requiredProviders` so no token is minted until the linked-provider threshold is met",
                "Reading downstream provider tokens in a tool via `this.orchestration.getToken(id)` / `tryGetToken(id)` without exposing them to the LLM"
              ]
            },
            {
              "name": "local-self-signed-tokens",
              "description": "Configure a local-mode server that signs its own HS256 JWTs and persists auth state across restarts with SQLite or Redis.",
              "level": "intermediate",
              "tags": ["config", "auth", "local", "sqlite", "redis", "auth-modes", "modes"],
              "features": [
                "Using `mode: 'local'` so the server signs its own HS256 JWTs (symmetric `JWT_SECRET`, no key pair)",
                "Setting `local.issuer` and `expectedAudience` to control token claims",
                "Persisting authorization codes and refresh tokens with `tokenStorage: { sqlite: { path } }` so they survive restart",
                "Switching the same `tokenStorage` to `{ redis }` for multi-instance deployments",
                "Enabling `consent` so login renders a tool-selection screen and the chosen tools are enforced at call time"
              ]
            },
            {
              "name": "local-single-operator",
              "description": "Run local mode for a single operator (e.g. Claude Code) by skipping the email prompt and minting a stable anonymous subject.",
              "level": "basic",
              "tags": ["config", "auth", "local", "single-operator", "claude-code", "auth-modes"],
              "features": [
                "Setting `requireEmail: false` so the login callback mints a code without prompting for an email",
                "Setting `anonymousSubject` so the single operator gets a stable `sub` across logins",
                "Persisting tokens with SQLite so the operator stays logged in across restarts"
              ]
            },
            {
              "name": "remote-enterprise-oauth",
              "description": "Proxy authentication to one mandatory upstream IdP, mint a FrontMCP session, and read the upstream token in tools.",
              "level": "advanced",
              "tags": ["config", "oauth", "auth", "redis", "remote", "auth-modes"],
              "features": [
                "Using `mode: 'remote'` to proxy authentication to a single mandatory upstream IdP",
                "Loading `clientId` and `clientSecret` from environment variables (never hardcoded)",
                "Configuring Redis-backed token storage for production persistence",
                "`GET /oauth/authorize` redirects straight to the upstream IdP (no in-tree login page)",
                "Session identity (sub/email/name) is derived from the upstream user",
                "Tools read the upstream token via `this.orchestration.getToken(providerId)`"
              ]
            },
            {
              "name": "transparent-jwt-validation",
              "description": "Validate externally-issued JWTs without managing token lifecycle on the server.",
              "level": "basic",
              "tags": ["config", "auth", "transparent", "auth-modes", "modes", "jwt"],
              "features": [
                "Using `mode: 'transparent'` to validate tokens from an external identity provider",
                "Setting `expectedAudience` to restrict which tokens are accepted",
                "The server fetches JWKS from `{provider}/.well-known/jwks.json` automatically",
                "Issuer (`iss`) is validated against `provider` by default; opt out or extend with `providerConfig.verifyIssuer` / `additionalIssuers`"
              ]
            }
          ]
        },
        {
          "name": "configure-auth",
          "description": "Set up authentication modes, credential vault, and OAuth flows for FrontMCP servers",
          "examples": [
            {
              "name": "local-credential-vault",
              "description": "Persist a per-session credential from a local authenticate() verifier into the built-in encrypted vault and read it from a tool via this.credentials.",
              "level": "intermediate",
              "tags": ["config", "auth", "local", "vault", "credentials", "this-credentials"],
              "features": [
                "Returning `credentials: [{ key, secret, metadata? }]` from `authenticate()` so FrontMCP persists them encrypted, keyed by the minted `sub`",
                "Reading a per-session credential from a tool via `this.credentials.get(key)` (no `this.authProviders` wiring needed)",
                "Prompting the agent to connect a missing credential mid-session with `this.credentials.requireConnect({ key })` (framework-signed `/oauth/connect` URL)",
                "Understanding per-session rotation: a reconnect yields an empty vault and old ciphertext is undecryptable"
              ]
            },
            {
              "name": "local-secure-store",
              "description": "Configure the general session secure-secret store (this.secureStore) with a pluggable backing (memory / sqlite / redis / custom OS-keychain) and read/write user-typed secrets from a tool.",
              "level": "intermediate",
              "tags": ["config", "auth", "local", "secure-store", "secrets", "this-secure-store", "keychain"],
              "features": [
                "Selecting the secure-store backing via `auth.secureStore` (memory / sqlite / redis / custom backend) plus a namespace `scope`",
                "Reading/writing arbitrary user-typed secrets from a tool via `this.secureStore.set/get/list/delete` (JSON-serialized, scoped to the session/subject)",
                "Backing the store with an OS keychain by supplying a `SecureStoreBackend` — no native dependency is bundled by the framework",
                "Understanding scope: `user` (keyed by sub, default), `session` (keyed by sessionId), `global` (server-wide)"
              ]
            },
            {
              "name": "multi-app-auth",
              "description": "Configure a single FrontMCP server with multiple apps, each using a different auth mode -- public for open endpoints and remote for admin endpoints.",
              "level": "advanced",
              "tags": ["config", "auth", "security", "multi-app", "remote", "multi"],
              "features": [
                "Hosting multiple `@App` instances on a single FrontMCP server with different auth modes",
                "Using `public` mode for open-access endpoints alongside `remote` mode for admin-only endpoints",
                "Isolating tools per app so each security posture governs only its own tools"
              ]
            },
            {
              "name": "public-mode-setup",
              "description": "Set up a FrontMCP server with public (unauthenticated) access and anonymous scopes.",
              "level": "basic",
              "tags": ["config", "auth", "session", "public", "mode", "setup"],
              "features": [
                "Configuring `mode: 'public'` for unauthenticated access",
                "Setting `sessionTtl` to control the lifetime of anonymous tokens",
                "Granting `anonymousScopes` so tools can check scope-based permissions even without auth"
              ]
            },
            {
              "name": "remote-oauth-with-vault",
              "description": "Configure a FrontMCP server with local OAuth orchestration of an upstream provider and read the downstream provider token in a tool via this.orchestration.getToken.",
              "level": "intermediate",
              "tags": ["config", "oauth", "auth", "orchestration", "providers"],
              "features": [
                "Declaring an upstream provider in top-level `auth.providers` so FrontMCP orchestrates its OAuth flow",
                "Loading `clientId`/`clientSecret` from environment variables instead of hardcoding",
                "Reading the downstream provider token in a tool via `this.orchestration.getToken('github')`"
              ]
            }
          ]
        },
        {
          "name": "configure-client-profiles",
          "description": "Shape answers per MCP client with clients profiles - text, structuredContent or both, resource annotations, and skills instructions",
          "examples": [
            {
              "name": "coding-agent-profiles",
              "description": "Send coding agents one copy of each answer, and keep numbers out of one client's annotations.",
              "level": "intermediate",
              "tags": ["config", "clients", "codex", "claude-code", "structured-content", "metrics"],
              "features": [
                "Matching clients by a glob of their `clientInfo.name`, first match wins",
                "Sending Codex the text content only, with no `outputSchema` in its `tools/list`",
                "Sending Claude Code `structuredContent` with a one-line summary as the text",
                "Dropping numeric resource annotations for one client",
                "Checking the saved bytes with the answer-cost counters on `/metrics`"
              ]
            }
          ]
        },
        {
          "name": "configure-deployment-targets",
          "description": "Configure multi-target builds with frontmcp.config.ts for node, distributed, vercel, lambda, cloudflare, browser, cli, sdk, and mcpb targets",
          "examples": [
            {
              "name": "distributed-ha-config",
              "description": "Configure a distributed deployment target with HA settings for heartbeat, session takeover, and Redis-backed session persistence",
              "level": "advanced",
              "tags": ["config", "deployment", "distributed", "ha", "redis", "heartbeat", "session-takeover"],
              "features": [
                "Configuring the distributed deployment target with HA options",
                "Setting custom heartbeat intervals and TTL for pod liveness detection",
                "Combining server config (CSP, cookies) with HA config in the same target",
                "Using per-target environment variables for Redis connection"
              ]
            },
            {
              "name": "json-schema-ide-support",
              "description": "Use frontmcp.config.json with JSON Schema for VS Code and WebStorm autocomplete",
              "level": "basic",
              "tags": ["config", "deployment", "json", "schema", "ide", "autocomplete"],
              "features": [
                "Adding $schema field for IDE autocomplete in JSON config files",
                "Configuring multiple deployment targets in JSON format",
                "Using the frontmcp.schema.json for property validation and hover docs"
              ]
            },
            {
              "name": "multi-target-with-security",
              "description": "Configure a FrontMCP project with node + distributed targets, CSP headers, and HSTS",
              "level": "intermediate",
              "tags": ["config", "deployment", "csp", "security", "distributed", "hsts", "multi-target"],
              "features": [
                "Using defineConfig() for typed configuration with IDE autocomplete",
                "Multi-target deployments with per-target server settings",
                "CSP directives including value-less directives like upgrade-insecure-requests",
                "Security headers (HSTS, X-Frame-Options, X-Content-Type-Options)",
                "HA configuration for the distributed target"
              ]
            }
          ]
        },
        {
          "name": "configure-elicitation",
          "description": "Configure interactive user input during tool execution for confirmations, choices, and forms",
          "examples": [
            {
              "name": "basic-confirmation-gate",
              "description": "Request user confirmation before executing a destructive action.",
              "level": "basic",
              "tags": ["config", "elicitation", "confirmation", "gate"],
              "features": [
                "Enabling elicitation with `elicitation: { enabled: true }` in the `@FrontMcp` decorator",
                "Using `this.elicit()` to pause tool execution and request user confirmation",
                "Handling the case where the client does not support elicitation (`!confirmation`)",
                "Using a boolean `requestedSchema` for simple yes/no confirmations"
              ]
            },
            {
              "name": "distributed-elicitation-redis",
              "description": "Configure elicitation with Redis storage for multi-instance production deployments.",
              "level": "intermediate",
              "tags": ["config", "redis", "elicitation", "distributed"],
              "features": [
                "Configuring Redis-backed elicitation state for multi-instance deployments",
                "Using a `requestedSchema` with both required and optional fields",
                "Elicitation state is shared across server instances so the response can arrive at any replica",
                "Loading Redis connection details from environment variables"
              ]
            },
            {
              "name": "persistent-questions-inbox",
              "description": "Keep a question for its caller past the session, answered in the inbox or the CLI.",
              "level": "advanced",
              "tags": ["config", "elicitation", "persistent", "inbox", "people-auth"],
              "features": [
                "Turning on `elicitation.persistent` next to `http.auth.people` for the inbox routes",
                "Asking with `this.elicit(..., { ttl, persist: { key } })` so the question outlives the call",
                "Printing a sign-in link bound to the caller on the server console with `printQuestionInboxLink(this)`",
                "Answering with `frontmcp inbox --url <server>`, which reads the link from the prompt, stdin or `FRONTMCP_INBOX_LINK`, and the next call receiving the answer once"
              ]
            }
          ]
        },
        {
          "name": "configure-http",
          "description": "Configure HTTP server port, CORS policy, unix sockets, entry path prefix, request body limits, and custom HTTP routes",
          "examples": [
            {
              "name": "cors-restricted-origins",
              "description": "Configure CORS to allow only specific frontend origins with credentials.",
              "level": "basic",
              "tags": ["config", "browser", "http", "cors", "restricted", "origins"],
              "features": [
                "Naming the origins a browser may read from — omitting `cors` sends no headers at all",
                "Enabling `credentials: true` with specific origins (required -- browsers reject `*` with credentials)",
                "Setting `maxAge` to reduce preflight request overhead",
                "Reading port from an environment variable with a fallback"
              ]
            },
            {
              "name": "custom-http-routes",
              "description": "Mount first-class custom HTTP routes (download, secret-validation POST, auth-gated webhook) on the MCP listener via http.routes.",
              "level": "intermediate",
              "tags": ["config", "http", "routes", "custom", "webhook", "download", "auth"],
              "features": [
                "Registering custom HTTP endpoints with `http.routes` — no tool/resource/prompt needed",
                "A POST endpoint that validates a user-entered secret server-side (the `/connect-env` pattern)",
                "Overriding the default `application/json` Content-Type for binary/HTML delivery",
                "Gating a route behind the MCP `session:verify` flow with `auth: true`",
                "Avoiding reserved paths (`/sse`, `/message`, `/oauth/*`, `/.well-known/*`, `/health`, `/metrics`)"
              ]
            },
            {
              "name": "entry-path-reverse-proxy",
              "description": "Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.",
              "level": "intermediate",
              "tags": ["config", "nx", "http", "entry", "path", "reverse"],
              "features": [
                "Using `entryPath` to mount the server under a URL prefix (no trailing slash)",
                "All MCP endpoints are prefixed: `/api/mcp/sse`, `/api/mcp/`, etc.",
                "Using a dynamic CORS origin function to allow wildcard subdomains",
                "Suitable for running behind nginx, Caddy, or other reverse proxies"
              ]
            },
            {
              "name": "unix-socket-local",
              "description": "Bind the server to a unix socket instead of a TCP port for local-only communication.",
              "level": "intermediate",
              "tags": ["config", "unix-socket", "cli", "local", "http", "unix"],
              "features": [
                "Using `socketPath` to bind to a unix socket instead of a TCP port",
                "When `socketPath` is set, the `port` field is ignored",
                "Disabling CORS with `cors: false` since unix sockets are local-only",
                "Suitable for CLI tools, daemons, and process manager integrations"
              ]
            }
          ]
        },
        {
          "name": "configure-security-headers",
          "description": "Configure CSP, HSTS, X-Frame-Options, and X-Content-Type-Options via frontmcp.config server settings",
          "examples": [
            {
              "name": "csp-report-only",
              "description": "Test CSP policies in report-only mode to identify violations before enforcement",
              "level": "basic",
              "tags": ["config", "csp", "security", "report-only", "headers"],
              "features": [
                "Enabling CSP in report-only mode with reportUri for violation monitoring",
                "Using the object-format directives in frontmcp.config",
                "Verifying report-only header is emitted instead of enforcement header"
              ]
            },
            {
              "name": "full-production-headers",
              "description": "Complete security headers configuration for production with CSP enforcement, HSTS preload, and clickjacking protection",
              "level": "intermediate",
              "tags": ["config", "csp", "security", "hsts", "production", "headers", "frame-options"],
              "features": [
                "Full CSP enforcement with multiple directive types including value-less directives",
                "HSTS with preload and includeSubDomains for HTTPS enforcement",
                "X-Frame-Options DENY for clickjacking protection",
                "Custom headers for additional security controls"
              ]
            }
          ]
        },
        {
          "name": "configure-session",
          "description": "Set up session storage with Redis, Vercel KV, or SQLite for persistent user state across requests",
          "examples": [
            {
              "name": "multi-server-key-prefix",
              "description": "Use unique key prefixes when multiple FrontMCP servers share one Redis instance.",
              "level": "intermediate",
              "tags": ["config", "redis", "session", "multi", "key", "prefix"],
              "features": [
                "Using unique `keyPrefix` values per server to avoid session key collisions",
                "Both servers share the same Redis instance but have isolated session namespaces",
                "Tuning `defaultTtlMs` per server based on workload pattern",
                "`billing-mcp:session:` vs `analytics-mcp:session:` prevents cross-contamination"
              ]
            },
            {
              "name": "redis-session-store",
              "description": "Configure Redis-backed session storage for production deployments.",
              "level": "basic",
              "tags": ["config", "redis", "session", "store"],
              "features": [
                "Configuring Redis as the session storage provider for production persistence",
                "Using `keyPrefix` to namespace session keys and prevent collisions with other servers",
                "Setting `defaultTtlMs` to control session lifetime (1 hour for interactive use)",
                "Loading Redis connection details from environment variables"
              ]
            },
            {
              "name": "vercel-kv-session",
              "description": "Configure Vercel KV for session storage in serverless Vercel deployments.",
              "level": "intermediate",
              "tags": ["config", "vercel-kv", "vercel", "session", "transport", "serverless"],
              "features": [
                "Using `provider: 'vercel-kv'` for Vercel platform deployments",
                "Vercel automatically injects `KV_REST_API_URL` and `KV_REST_API_TOKEN` environment variables",
                "Combining with `stateless-api` transport preset for serverless execution",
                "No explicit host/port needed -- Vercel KV uses REST API under the hood"
              ]
            }
          ]
        },
        {
          "name": "configure-skills-http",
          "description": "Full reference for skillsConfig — HTTP catalog endpoints, auth, caching, instructions injection, SKILL.md resource annotations, and tamper-evident audit log.",
          "examples": [
            {
              "name": "audit-log-basic",
              "description": "Enable the skill audit log with the in-memory store and HS256 signer for development and tests.",
              "level": "basic",
              "tags": ["config", "skills", "audit", "hs256", "development"],
              "features": [
                "Bootstraps the audit subsystem via setSkillAuditFactory(...) before FrontMcp registers",
                "MemoryAuditStore keeps records in-process — perfect for tests, lost on restart",
                "A random-key Hs256AuditSigner cannot verify records after a restart: use Rs256AuditSigner in production",
                "subjectMode: 'hash' redacts user identifiers while keeping them correlatable (keyed from the signer's secret)",
                "The in-memory store is development-only: with audit enabled in production, the server refuses to start without a `store`"
              ]
            },
            {
              "name": "audit-log-redis",
              "description": "Production-grade audit log with the Redis-backed StorageAdapterAuditStore and the RS256 bundle-signing key.",
              "level": "advanced",
              "tags": ["config", "skills", "audit", "rs256", "redis", "production"],
              "features": [
                "StorageAdapterAuditStore persists records to Redis via the standard storage adapter",
                "Rs256AuditSigner reuses the bundle-signing keypair for forensic-friendly signatures",
                "Single-writer constraint: only one pod should write the chain in v1.2.0",
                "verifyChain(records, trustedKeys, defaultAuditSignatureVerifier) detects tampering"
              ]
            },
            {
              "name": "inject-instructions",
              "description": "Set a server-level instructions string and append the full skill catalog summary on every initialize response.",
              "level": "basic",
              "tags": ["config", "skills", "instructions", "injection", "initialize"],
              "features": [
                "Top-level `instructions` on `@FrontMcp` exposes a global system prompt to MCP clients",
                "`skillsConfig.injectInstructions: 'append'` adds the skill catalog summary after the user prompt",
                "The default, `'compact'`, adds one line with the skill count and the `skill://index.json` pointer instead",
                "Dynamic skills are picked up because the composer runs on every initialize request",
                "The catalog only names skills the initializing caller may see (skill authorities and the `skills:filter` flow, e.g. feature flags)",
                "Catalog summary is bounded at 16 KB with a truncation footer pointing at skill://index.json"
              ]
            }
          ]
        },
        {
          "name": "configure-throttle-guard-config",
          "description": "Complete GuardConfig interface reference for rate limiting, concurrency, and IP filtering",
          "examples": [
            {
              "name": "full-guard-config",
              "description": "Complete GuardConfig using every available field for maximum protection.",
              "level": "advanced",
              "tags": ["config", "redis", "session", "throttle", "guard", "full"],
              "features": [
                "Every field in the `GuardConfig` interface used together",
                "Priority order: IP filter -> global rate limit -> global concurrency -> per-tool limits",
                "Redis `storage` for shared counters across instances",
                "`keyPrefix` to namespace guard keys in shared Redis",
                "Mixed `partitionBy` strategies: `'ip'` for global, `'session'` for per-tool",
                "`queueTimeoutMs` to briefly queue excess requests instead of rejecting"
              ]
            },
            {
              "name": "minimal-guard-config",
              "description": "Enable throttle with just a global rate limit and default timeout.",
              "level": "basic",
              "tags": ["config", "throttle", "guard", "minimal"],
              "features": [
                "The minimum fields needed to enable the guard: `enabled`, `global`, and `defaultTimeout`",
                "`partitionBy: 'global'` shares one counter across all clients",
                "`windowMs` defaults to 60000 (1 minute) if omitted",
                "Other fields (`globalConcurrency`, `ipFilter`, `storage`) are optional"
              ]
            }
          ]
        },
        {
          "name": "configure-throttle",
          "description": "Protect servers with rate limiting, concurrency control, execution timeouts, and IP filtering",
          "examples": [
            {
              "name": "distributed-redis-throttle",
              "description": "Configure Redis-backed rate limiting for multi-instance deployments behind a load balancer.",
              "level": "advanced",
              "tags": ["config", "redis", "session", "throttle", "distributed"],
              "features": [
                "Configuring `storage: { type: 'redis' }` so rate limit counters are shared across instances",
                "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'`"
              ]
            },
            {
              "name": "per-tool-rate-limit",
              "description": "Override server defaults with per-tool rate limits and concurrency caps.",
              "level": "intermediate",
              "tags": ["config", "session", "throttle", "per", "tool", "rate"],
              "features": [
                "Setting per-tool `rateLimit`, `concurrency`, and `timeout` on the `@Tool` decorator",
                "Using `partitionBy: 'session'` for per-user fairness on expensive tools",
                "Setting `queueTimeoutMs` to briefly queue excess requests instead of rejecting immediately",
                "Tools without overrides (`QuickLookupTool`) inherit server defaults"
              ]
            },
            {
              "name": "server-level-rate-limit",
              "description": "Configure global rate limits and IP filtering at the server level.",
              "level": "basic",
              "tags": ["config", "throttle", "level", "rate", "limit"],
              "features": [
                "Enabling throttle with `throttle: { enabled: true }`",
                "Setting `global` rate limit shared across all clients",
                "Configuring `globalConcurrency` to cap simultaneous executions",
                "Setting `defaultTimeout` to prevent runaway tool executions",
                "Using `ipFilter` with deny-by-default posture and an explicit allow list"
              ]
            }
          ]
        },
        {
          "name": "configure-transport-protocol-presets",
          "description": "Reference for legacy, modern, stateless, and minimal transport protocol presets",
          "examples": [
            {
              "name": "legacy-preset-nodejs",
              "description": "Use the default legacy preset for maximum compatibility with all MCP clients.",
              "level": "basic",
              "tags": ["config", "anthropic", "session", "transport", "node", "protocol"],
              "features": [
                "The `'legacy'` preset is the default and can be omitted",
                "Enables SSE, Streamable HTTP, and Legacy SSE for maximum client compatibility",
                "`strictSession: true` requires `mcp-session-id` header for streamable HTTP",
                "Best for single-instance Node.js deployments (Claude Desktop, etc.)"
              ]
            },
            {
              "name": "stateless-api-serverless",
              "description": "Use the stateless-api preset for Vercel, Lambda, or Cloudflare Workers.",
              "level": "intermediate",
              "tags": ["config", "vercel", "lambda", "cloudflare", "session", "transport"],
              "features": [
                "The `'stateless-api'` preset disables SSE, streaming, and sessions entirely",
                "Each request is standalone with no server-side state",
                "No `sessionMode` needed: sessions follow the protocol preset",
                "Required for Vercel, Lambda, Cloudflare Workers where persistent connections are not allowed"
              ]
            }
          ]
        },
        {
          "name": "configure-transport",
          "description": "Configure client transport protocols including SSE, Streamable HTTP, and stateless API modes",
          "examples": [
            {
              "name": "custom-protocol-flags",
              "description": "Override individual protocol flags instead of using a preset for fine-grained control.",
              "level": "advanced",
              "tags": ["config", "redis", "session", "transport", "custom", "protocol"],
              "features": [
                "Passing an object to `protocol` instead of a preset string for fine-grained control",
                "Enabling SSE, streamable HTTP, and JSON-only modes simultaneously",
                "Setting `strictSession: true` to require `mcp-session-id` header on streamable HTTP",
                "Using `distributedMode: 'auto'` to auto-detect based on whether Redis is configured",
                "Disabling `legacy` SSE while keeping modern SSE support"
              ]
            },
            {
              "name": "distributed-sessions-redis",
              "description": "Configure transport with Redis persistence for multi-instance load-balanced deployments.",
              "level": "intermediate",
              "tags": ["config", "redis", "session", "transport", "distributed", "sessions"],
              "features": [
                "Using `distributedMode: true` for load-balanced multi-instance deployments",
                "Redis `persistence` so sessions survive restarts and are shared across instances",
                "Setting `defaultTtlMs` to prevent sessions from accumulating indefinitely",
                "Redis-backed `eventStore` for SSE resumability across instances",
                "Using the `'modern'` preset (drops legacy SSE but keeps streamable HTTP)"
              ]
            },
            {
              "name": "stateless-serverless",
              "description": "Configure stateless transport for Vercel, Lambda, or Cloudflare deployments.",
              "level": "basic",
              "tags": ["config", "vercel", "lambda", "cloudflare", "session", "transport"],
              "features": [
                "Serving without sessions: whether the server keeps sessions follows `transport.protocol` (`sessionMode` has no effect)",
                "Using the `'stateless-api'` preset: no SSE, no streaming, pure request/response",
                "Each request is standalone with no server-side state between invocations",
                "Required for serverless targets (Vercel, Lambda, Cloudflare Workers)"
              ]
            }
          ]
        },
        {
          "name": "setup-redis",
          "description": "Cross-reference to the full Redis configuration guide in frontmcp-setup",
          "examples": []
        },
        {
          "name": "setup-sqlite",
          "description": "Cross-reference to the full SQLite configuration guide in frontmcp-setup",
          "examples": []
        }
      ]
    },
    {
      "name": "frontmcp-deployment",
      "category": "deployment",
      "description": "Use when deploying, building for production, packaging, or shipping a FrontMCP server. Covers build targets (node, cli SEA binary, browser, embeddable SDK, mcpb archive for Claude Desktop, serverless) and deploying to Vercel (with Vercel KV), AWS Lambda (API Gateway, SAM, CDK), Cloudflare Workers (KV, D1, Durable Objects, v1.3 skills-only), and Node (multi-stage Docker, docker-compose, PM2, nginx). Also the frontmcp.deploy.yaml manifest plus GitHub Action push-resync, MCP client integration / .mcp.json for Claude Desktop, Claude Code, Cursor, and VS Code over stdio or HTTP, one shared local server for several stdio sessions (runShared), MCP protocol revisions (serving 2026-07-28 alongside 2024-11-05 through 2025-11-25), and listing a server in the MCP Registry (domain proof, SEP-2127 server card, AI Catalog). Triggers: deploy, build for production, dockerize, containerize, serverless, edge runtime, go live, ship it.",
      "path": "frontmcp-deployment",
      "targets": ["all"],
      "hasResources": true,
      "tags": [
        "router",
        "deployment",
        "node",
        "vercel",
        "lambda",
        "cloudflare",
        "cli",
        "browser",
        "sdk",
        "guide",
        "protocol",
        "mcp-20260728",
        "mcp-registry"
      ],
      "bundle": ["recommended", "minimal", "full"],
      "priority": 10,
      "references": [
        {
          "name": "build-for-browser",
          "description": "Build a FrontMCP server or client for browser environments and frontend frameworks",
          "examples": [
            {
              "name": "browser-build-with-custom-entry",
              "description": "Build a browser bundle using a dedicated client entry file that avoids Node.js-only imports. Re-export the real `@frontmcp/react` symbols (`useListTools`, `useListResources`, `useCallTool`) — `useTools`/`useResources` do not exist.",
              "level": "intermediate",
              "tags": ["deployment", "browser", "custom", "entry"],
              "features": [
                "Creating a separate browser entry point (`src/client.ts`) that re-exports only browser-safe symbols",
                "Using the real `@frontmcp/react` hook names (`useListTools`, `useListResources`, etc.)",
                "Using the `-e` and `-o` flags to customize the entry file and output directory"
              ]
            },
            {
              "name": "browser-crypto-and-storage",
              "description": "Use `@frontmcp/utils` crypto in the browser, and create the FrontMCP server with `create()` from `@frontmcp/sdk` so the React provider can consume it via the `server` prop.",
              "level": "advanced",
              "tags": ["deployment", "browser", "crypto", "react"],
              "features": [
                "Using `@frontmcp/utils` for PKCE and hashing in the browser (backed by WebCrypto, not `node:crypto`)",
                "Creating a `DirectMcpServer` with `create()` and passing it to `FrontMcpProvider` via `server={...}` (no `config={{ serverUrl }}`)",
                "Using `useListTools` (real hook) instead of the non-existent `useTools`"
              ]
            },
            {
              "name": "react-provider-setup",
              "description": "Connect a React application to a FrontMCP server using `@frontmcp/react`. `FrontMcpProvider` takes a `DirectMcpServer` instance via the `server` prop — there is no `serverUrl` option.",
              "level": "basic",
              "tags": ["deployment", "react", "browser", "provider", "setup"],
              "features": [
                "Wrapping your React app with `FrontMcpProvider` and passing a real `DirectMcpServer` via `server={...}`",
                "Using `useListTools` to fetch the tools list and `useCallTool` to invoke one",
                "Creating the server with `create()` from `@frontmcp/sdk` (in-memory direct connection)"
              ]
            }
          ]
        },
        {
          "name": "build-for-cli",
          "description": "Build a FrontMCP server as a standalone CLI binary using Node.js SEA or bundled JS",
          "examples": [
            {
              "name": "cli-binary-build",
              "description": "Build a FrontMCP server as a standalone binary using Node.js Single Executable Applications (SEA).",
              "level": "basic",
              "tags": ["deployment", "cli", "local", "node", "binary"],
              "features": [
                "Building a FrontMCP server as a self-contained binary with `--target cli`",
                "Using `socketPath` for local communication instead of a TCP port",
                "The `--js` flag to produce a bundled JS file without the native binary wrapper"
              ]
            },
            {
              "name": "unix-socket-daemon",
              "description": "Run a FrontMCP server as a local daemon accessible via Unix socket for IDE extensions and local MCP clients.",
              "level": "intermediate",
              "tags": ["deployment", "unix-socket", "cli", "transport", "local", "unix"],
              "features": [
                "Configuring a FrontMCP server for Unix socket transport instead of TCP",
                "Running the server as a background daemon with process management (`frontmcp start/stop/status`)",
                "Installing the daemon as a system service for automatic startup on reboot"
              ]
            }
          ]
        },
        {
          "name": "build-for-mcpb",
          "description": "Package a FrontMCP server as a .mcpb archive that Claude Desktop and other MCPB-aware clients install with one click",
          "examples": [
            {
              "name": "mcpb-bundle-build",
              "description": "Produce a .mcpb archive for Claude Desktop with metadata, tools, and install-time user_config.",
              "level": "basic",
              "tags": ["deployment", "mcpb", "bundle", "claude-desktop", "user-config"],
              "features": [
                "Using `frontmcp build --target mcpb` to produce a single `.mcpb` archive",
                "Passing `setup.steps` and `userConfig` answers to the server as env vars via `${user_config.KEY}`",
                "Validating the archive round-trip with `frontmcp mcpb validate`"
              ]
            }
          ]
        },
        {
          "name": "build-for-sdk",
          "description": "Build a FrontMCP server as an embeddable library with create() and connect() APIs",
          "examples": [
            {
              "name": "connect-openai",
              "description": "Use `connectOpenAI()` to get tools formatted for OpenAI's function-calling API.",
              "level": "intermediate",
              "tags": ["deployment", "sdk", "openai", "session", "connect"],
              "features": [
                "Setting `serve: false` to prevent the HTTP server from starting in library mode",
                "Using `connectOpenAI()` to get tools in OpenAI function-calling format automatically",
                "Passing session information via `ConnectOptions` for user context"
              ]
            },
            {
              "name": "create-flat-config",
              "description": "Spin up an in-memory FrontMCP server from a flat config object using `create()`.",
              "level": "basic",
              "tags": ["deployment", "sdk", "cache", "flat", "config"],
              "features": [
                "Using `create()` to spin up a server without decorators or classes",
                "Calling tools directly via `server.callTool()` with zero network overhead",
                "Using `cacheKey` to reuse the same server instance across multiple calls"
              ]
            },
            {
              "name": "multi-platform-connect",
              "description": "Connect the same FrontMCP server to multiple LLM platforms using platform-specific `connect*()` functions.",
              "level": "advanced",
              "tags": ["deployment", "sdk", "multi", "platform", "connect"],
              "features": [
                "Connecting a single FrontMCP server to four different LLM platforms with automatic schema translation",
                "Each `connect*()` function returns tools in the platform's native format",
                "All clients share the same `DirectClient` API (`listTools`, `callTool`, `close`)"
              ]
            }
          ]
        },
        {
          "name": "build-manifest",
          "description": "The frontmcp.manifest.json that frontmcp build writes for every target, its lint, and the instructionsBudget size limits",
          "examples": []
        },
        {
          "name": "deploy-manifest-yaml",
          "description": "The frontmcp.deploy.yaml v1 schema — declarative manifest the GitHub Action consumes on every push to build, sign, and hot-reload the Cloudflare Worker",
          "examples": []
        },
        {
          "name": "deploy-to-cloudflare-skills-only",
          "description": "Deploy an auto-updating FrontMCP server to Cloudflare Workers with @frontmcp/edge createEdgeMcp — managed skilled-OpenAPI bundle pulled from a SaaS endpoint, cached in KV, refreshed on a Cron Trigger",
          "examples": []
        },
        {
          "name": "deploy-to-cloudflare",
          "description": "Deploy a FrontMCP server to Cloudflare Workers with KV, D1, and Durable Objects",
          "examples": [
            {
              "name": "basic-worker-deploy",
              "description": "Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration.",
              "level": "basic",
              "tags": ["deployment", "cloudflare", "transport", "local", "worker"],
              "features": [
                "A minimal FrontMCP server configured for Cloudflare Workers with SSE transport",
                "The `wrangler.toml` configuration with `main` pointing to the build output",
                "Using `wrangler dev` for local testing before deploying with `wrangler deploy`"
              ]
            },
            {
              "name": "worker-custom-domain",
              "description": "Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment.",
              "level": "advanced",
              "tags": ["deployment", "json-rpc", "cloudflare", "worker", "custom", "domain"],
              "features": [
                "Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts",
                "Adding a custom domain with `wrangler deploy --domain` for production-ready URLs",
                "End-to-end verification of both the health check and MCP JSON-RPC endpoint"
              ]
            },
            {
              "name": "worker-with-kv-storage",
              "description": "Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage.",
              "level": "intermediate",
              "tags": ["deployment", "cloudflare", "cli", "session", "worker", "kv"],
              "features": [
                "Binding a KV namespace in `wrangler.toml` with `[[kv_namespaces]]`",
                "Using `wrangler secret put` for sensitive values instead of `[vars]` (which are visible in plaintext)",
                "Creating the KV namespace via CLI and copying the ID into the configuration"
              ]
            }
          ]
        },
        {
          "name": "deploy-to-lambda",
          "description": "Deploy a FrontMCP server to AWS Lambda with API Gateway using SAM or CDK",
          "examples": [
            {
              "name": "cdk-deployment",
              "description": "Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management.",
              "level": "advanced",
              "tags": ["deployment", "lambda", "performance", "cdk"],
              "features": [
                "Using AWS CDK instead of SAM for infrastructure-as-code deployment",
                "Provisioned concurrency via a Lambda alias to eliminate cold starts on critical endpoints",
                "Referencing secrets from SSM Parameter Store with `{{resolve:ssm:...}}` instead of hardcoding"
              ]
            },
            {
              "name": "lambda-handler-with-cors",
              "description": "CORS for a FrontMCP Lambda is configured at the API Gateway HTTP API level, not in the handler. `frontmcp build --target lambda` writes `dist/lambda/handler.cjs` — your `@FrontMcp` server is wrapped automatically with `@codegenie/serverless-express`, so CORS belongs on the gateway.",
              "level": "intermediate",
              "tags": ["deployment", "lambda", "handler", "cors"],
              "features": [
                "Configuring CORS at the API Gateway HTTP API layer (not the handler) via `CorsConfiguration`",
                "Linking the function events to the explicit API via `ApiId: !Ref`",
                "Pointing SAM `CodeUri` at `dist/lambda/` so the auto-generated `handler.cjs` is uploaded"
              ]
            },
            {
              "name": "sam-template-basic",
              "description": "Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template.",
              "level": "basic",
              "tags": ["deployment", "lambda", "performance", "sam", "template"],
              "features": [
                "A minimal SAM template with ARM64 architecture for faster cold starts and lower cost",
                "The `/{proxy+}` catch-all route that forwards all requests to FrontMCP's internal router",
                "CloudWatch log group with 14-day retention"
              ]
            }
          ]
        },
        {
          "name": "deploy-to-node-dockerfile",
          "description": "Multi-stage Dockerfile for building and running a FrontMCP server in production",
          "examples": [
            {
              "name": "basic-multistage-dockerfile",
              "description": "A minimal multi-stage Dockerfile for building and running a FrontMCP server in production.",
              "level": "basic",
              "tags": ["deployment", "dockerfile", "docker", "node", "multistage"],
              "features": [
                "Two-stage build: the first stage installs all dependencies and builds; the second copies only production artifacts",
                "Using `yarn install --production` in the production stage to exclude dev dependencies",
                "A health check that verifies the server is responding"
              ]
            },
            {
              "name": "secure-nonroot-dockerfile",
              "description": "A production Dockerfile with a non-root user, proper ownership, and security hardening.",
              "level": "advanced",
              "tags": ["deployment", "dockerfile", "docker", "security", "node", "secure"],
              "features": [
                "Creating a dedicated non-root user (`frontmcp`) and switching to it with `USER`",
                "Setting file ownership before switching users so the process can read its own files",
                "Combining the Dockerfile with runtime resource limits (`--memory`, `--cpus`)"
              ]
            }
          ]
        },
        {
          "name": "deploy-to-node",
          "description": "Deploy a FrontMCP server as a standalone Node.js app with Docker and process managers",
          "examples": [
            {
              "name": "docker-compose-with-redis",
              "description": "Deploy a FrontMCP server with Redis using Docker Compose for production.",
              "level": "basic",
              "tags": ["deployment", "docker-compose", "redis", "dockerfile", "docker", "session"],
              "features": [
                "Multi-stage Dockerfile that keeps the production image small and secure",
                "Docker Compose configuration with Redis for session storage",
                "Health checks on both the FrontMCP server and Redis, with `depends_on` ensuring Redis starts first"
              ]
            },
            {
              "name": "pm2-with-nginx",
              "description": "Deploy a FrontMCP server on bare metal using PM2 for process management and NGINX for TLS termination.",
              "level": "intermediate",
              "tags": ["deployment", "nx", "node", "pm2", "nginx"],
              "features": [
                "Using PM2 with `-i max` for multi-core clustering and automatic restarts",
                "Configuring NGINX as a reverse proxy for TLS termination in front of the FrontMCP server",
                "Setting environment variables via `.env` for production configuration"
              ]
            },
            {
              "name": "resource-limits",
              "description": "Configure resource limits, health checks, and environment variables for a production FrontMCP deployment.",
              "level": "advanced",
              "tags": ["deployment", "docker-compose", "docker", "node", "resource", "limits"],
              "features": [
                "Setting CPU and memory limits/reservations in Docker Compose to prevent OOM kills",
                "Using `NODE_OPTIONS=--max-old-space-size` to align the V8 heap limit with the container memory",
                "Configuring health checks with appropriate `start_period` to allow the server time to initialize"
              ]
            }
          ]
        },
        {
          "name": "deploy-to-vercel-config",
          "description": "Reference vercel.json configuration for deploying a FrontMCP server to Vercel",
          "examples": [
            {
              "name": "minimal-vercel-config",
              "description": "`frontmcp build --target vercel` writes this minimal `vercel.json` for you. The package manager is detected from your lockfile.",
              "level": "basic",
              "tags": ["deployment", "vercel", "serverless", "config", "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"
              ]
            },
            {
              "name": "vercel-config-with-security-headers",
              "description": "The Vercel adapter emits a minimal `vercel.json` (version + buildCommand + installCommand). You can layer extra Vercel-supported keys on top after the build — but never add `functions: { 'api/frontmcp.ts': ... }` or `rewrites` to `/api/frontmcp` (the build does not produce an `api/` directory).",
              "level": "intermediate",
              "tags": ["deployment", "vercel", "security", "config", "headers"],
              "features": [
                "Adding `regions` to constrain function placement (e.g., `iad1` for US East)",
                "Per-route `Cache-Control: no-store` on `/healthz` and `/mcp` to prevent caching",
                "Global security headers applied to all routes via the catch-all `source: \"/(.*)\"`"
              ]
            }
          ]
        },
        {
          "name": "deploy-to-vercel",
          "description": "Deploy a FrontMCP server to Vercel serverless functions with Vercel KV storage",
          "examples": [
            {
              "name": "vercel-mcp-endpoint-test",
              "description": "Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation. The CLI emits the Build Output API v3 structure — there is no `api/frontmcp.ts` to test against; the function lives at `.vercel/output/functions/index.func/handler.cjs` and is routed via `.vercel/output/config.json`.",
              "level": "advanced",
              "tags": ["deployment", "json-rpc", "vercel", "mcp", "endpoint"],
              "features": [
                "Testing the health endpoint (`/healthz`) and MCP JSON-RPC API of a deployed Vercel function",
                "Using preview deployments to validate changes before promoting to production",
                "Vercel plan limits for `maxDuration` (Hobby: 10s, Pro: 60s, Enterprise: 900s) — configure these in the Vercel dashboard, not via `functions: { 'api/frontmcp.ts': ... }`"
              ]
            },
            {
              "name": "vercel-with-kv",
              "description": "Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence. The CLI emits the full Build Output API v3 structure for you — you do **not** author `api/frontmcp.ts` and you do **not** add a `rewrites` block.",
              "level": "basic",
              "tags": ["deployment", "vercel-kv", "vercel", "session", "performance", "serverless"],
              "features": [
                "Configuring `{ provider: 'vercel-kv' }` for automatic Vercel KV session storage",
                "Letting the CLI produce the Build Output API v3 structure (no manual `api/` directory or `rewrites`)",
                "Deploying with `vercel --prod` after the build emits `.vercel/output/`"
              ]
            },
            {
              "name": "vercel-with-skills-cache",
              "description": "Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching. The CLI handles the Build Output API v3 emission for you — your job is to configure the server and provision Vercel KV.",
              "level": "intermediate",
              "tags": ["deployment", "vercel-kv", "vercel", "cache", "skills"],
              "features": [
                "Enabling skills cache backed by Vercel KV with a 60-second TTL",
                "Setting environment variables via `vercel env add` instead of hardcoding in source",
                "Letting the CLI emit the Build Output API v3 structure rather than hand-authoring `api/frontmcp.ts`"
              ]
            }
          ]
        },
        {
          "name": "list-in-mcp-registry",
          "description": "List a FrontMCP server in the MCP Registry - @FrontMcp({ registry }) serves the domain proof, the SEP-2127 server card and the AI Catalog, and frontmcp registry keygen, publish and status manage the listing",
          "examples": []
        },
        {
          "name": "mcp-client-integration",
          "description": "Configure MCP clients (Claude Desktop, Claude Code, Cursor, VS Code) to connect to a FrontMCP server via stdio, HTTP, or Unix socket",
          "examples": [
            {
              "name": "http-remote",
              "description": "Connect an MCP client to a FrontMCP server running as an HTTP server, locally or remotely.",
              "level": "basic",
              "tags": ["deployment", "http", "mcp-client", "remote", "cloud", "production"],
              "features": [
                "Connecting to a local FrontMCP dev server on a custom port",
                "Connecting to a remote production FrontMCP server with authentication",
                "Configuring HTTP transport in Claude Code and Claude Desktop",
                "Using a background daemon on a TCP port for persistent local access"
              ]
            },
            {
              "name": "stdio-binary-with-env",
              "description": "Configure a local FrontMCP CLI binary with environment variables and custom arguments in MCP client configs.",
              "level": "intermediate",
              "tags": ["deployment", "stdio", "cli", "binary", "env", "mcp-client", "configuration"],
              "features": [
                "Pointing MCP clients at a locally installed FrontMCP binary",
                "Passing database URLs, API keys, and feature flags via environment variables",
                "Using absolute paths for reliable binary resolution",
                "Configuring different environments (dev, staging) via env vars"
              ]
            },
            {
              "name": "stdio-npx",
              "description": "Publish a FrontMCP server to npm and configure MCP clients to use it with npx --stdio.",
              "level": "basic",
              "tags": ["deployment", "stdio", "npx", "npm", "mcp-client", "claude-code", "claude-desktop"],
              "features": [
                "Building a FrontMCP server as a distributable CLI bundle",
                "Configuring package.json bin field for npx execution",
                "Setting up Claude Code, Claude Desktop, and Cursor to use the server via stdio",
                "Passing environment variables from MCP client config to the server"
              ]
            }
          ]
        },
        {
          "name": "protocol-versions",
          "description": "Serve MCP protocol revision 2026-07-28 alongside every earlier revision, and connect to a 2026 server as a client",
          "examples": []
        },
        {
          "name": "shared-local-server",
          "description": "Serve every stdio session of a server on one machine from one shared local process with FrontMCP's FrontMcpInstance.runShared - one start per key, an owner-only Unix socket or loopback HTTP with a token, a server identity and version proof before the token is sent, a newer session replacing an older server under live sessions, a fallback to running in the session's own process, and exit when idle or when the checkout is removed",
          "examples": []
        }
      ]
    },
    {
      "name": "frontmcp-development",
      "category": "development",
      "description": "Use when building any FrontMCP server component other than a tool (for tools, use create-tool). Covers @Resource static resources and parameterized URI templates; @Prompt reusable prompts (RAG, multi-turn); @Provider singleton dependency-injection providers (database pools, API clients); @Agent autonomous LLM agents (Anthropic, OpenAI) and swarms; @Job background jobs (retry, progress, permissions) and @Workflow DAG pipelines; @Duty recurring work that one process of the machine or project runs under a lease; framework adapters and the OpenAPI adapter (turn OpenAPI 3.x specs into MCP tools with auth, polling, transforms); plugins, plugin lifecycle hooks (before / after / around / stage), and the official plugins; instruction-only skills and skills that reference tools; and the hierarchical decorator system from @FrontMcp down to @App. Triggers: create a resource, build a prompt, write a provider, add an agent, job, workflow, duty, plugin, adapter, or OpenAPI integration.",
      "path": "frontmcp-development",
      "targets": ["all"],
      "hasResources": true,
      "tags": ["router", "development", "tools", "resources", "prompts", "agents", "skills", "guide"],
      "bundle": ["recommended", "minimal", "full"],
      "priority": 10,
      "references": [
        {
          "name": "create-adapter",
          "description": "Build adapters that generate MCP tools and resources from external sources automatically",
          "examples": [
            {
              "name": "basic-api-adapter",
              "description": "A minimal adapter that fetches operation definitions from an external API and generates MCP tools.",
              "level": "basic",
              "tags": ["development", "adapter", "api"],
              "features": [
                "Extending `DynamicAdapter<TOptions>` with a typed options interface",
                "Declaring `__options_brand` for proper TypeScript inference on `init()`",
                "Implementing `fetch()` to return `FrontMcpAdapterResponse` with tools, resources, and prompts",
                "Registering the adapter via the static `init()` method in the `adapters` array"
              ]
            },
            {
              "name": "namespaced-adapter",
              "description": "An adapter that namespaces generated tools to avoid collisions and includes proper error handling for startup failures.",
              "level": "intermediate",
              "tags": ["development", "adapter", "namespaced"],
              "features": [
                "Namespacing tools with `name: 'adapter-name:operation-name'` to prevent collisions",
                "Throwing descriptive errors in `fetch()` so misconfigurations surface at startup",
                "Registering multiple instances of the same adapter class with different configurations",
                "Validating the external response shape before generating tool definitions"
              ]
            }
          ]
        },
        {
          "name": "create-agent-llm-config",
          "description": "Reference for supported LLM provider configurations including Anthropic and OpenAI",
          "examples": [
            {
              "name": "anthropic-config",
              "description": "Configuring an agent with the Anthropic provider and common model options.",
              "level": "basic",
              "tags": ["development", "anthropic", "llm", "agent", "config"],
              "features": [
                "Setting `provider: 'anthropic'` with a supported model (`claude-sonnet-4-20250514` or `claude-opus-4-20250514`)",
                "Using `{ env: 'ANTHROPIC_API_KEY' }` to read the API key from an environment variable",
                "Setting `maxTokens` at the LLM config level and overriding per-call via `this.completion()` options",
                "Passing `temperature` as a per-call option for controlling response creativity"
              ]
            },
            {
              "name": "openai-config",
              "description": "Configuring an agent with the OpenAI provider and different model options.",
              "level": "basic",
              "tags": ["development", "openai", "llm", "agent", "config"],
              "features": [
                "Setting `provider: 'openai'` with `gpt-4o` for general purpose or `gpt-4o-mini` for cost-effective tasks",
                "The API key pattern `{ env: 'OPENAI_API_KEY' }` works the same across all providers",
                "Combining LLM config with inner tools -- the agent uses OpenAI to reason about tool invocations",
                "Choosing the right model for the task: `gpt-4o` for complex workflows, `gpt-4o-mini` for fast classification"
              ]
            }
          ]
        },
        {
          "name": "create-agent",
          "description": "Create autonomous AI agents that use LLM reasoning to plan and invoke inner tools",
          "examples": [
            {
              "name": "basic-agent-with-tools",
              "description": "An autonomous agent that uses inner tools to review GitHub pull requests.",
              "level": "basic",
              "tags": ["development", "anthropic", "agent", "tools"],
              "features": [
                "Creating an agent with `@Agent` decorator, `llm` config, and `inputSchema`",
                "Defining inner tools in the `tools` array that the agent can invoke during its reasoning loop",
                "Using `{ env: 'ANTHROPIC_API_KEY' }` for safe API key configuration",
                "Inner tools are private to the agent and not exposed to external MCP clients",
                "The default `execute()` runs the full agent loop without needing an override"
              ]
            },
            {
              "name": "custom-multi-pass-agent",
              "description": "An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`.",
              "level": "intermediate",
              "tags": ["development", "security", "agent", "custom", "multi", "pass"],
              "features": [
                "Overriding `execute()` for custom multi-pass orchestration instead of the default agent loop",
                "Using `this.completion()` to make individual LLM calls with full control over prompts",
                "Using `this.mark(stage)` to track execution stages (security-pass, quality-pass, synthesis)",
                "Defining `outputSchema` with Zod to validate and type-check the structured return value"
              ]
            },
            {
              "name": "nested-agents-with-swarm",
              "description": "Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `invoke_<id>` tools, plus a nested sub-agent and `this.invokeAgent()`. Routing is driven by the orchestrator's LLM, not a declarative handoff table.",
              "level": "advanced",
              "tags": ["development", "agent", "nested", "agents", "swarm"],
              "features": [
                "Setting `swarm: { canSeeOtherAgents: true, visibleAgents: [...] }` on the orchestrator so peers are offered to its model as `invoke_*` tools",
                "Setting `swarm: { isVisible: true }` (the default) on specialist peers so they can be called",
                "Routing is driven by the orchestrator LLM choosing among `invoke_<peer>` tools, not by a declarative handoff table",
                "A nested sub-agent (`agents: [...]`) private to the orchestrator, called from code with `this.invokeAgent()`",
                "`swarm.maxCallDepth` bounding how deep agents may call each other",
                "Each agent has its own `llm` config, `tools`, and `systemInstructions` for specialization"
              ]
            }
          ]
        },
        {
          "name": "create-duty",
          "description": "Run recurring work in exactly one process of the machine or project with @Duty, a lease that one process holds and another takes over when the holder dies",
          "examples": []
        },
        {
          "name": "create-http-route",
          "description": "Serve pages, APIs and live SSE views for people beside the MCP endpoint with @HttpRoute classes that share the app's providers, behind people auth and a same-origin check",
          "examples": []
        },
        {
          "name": "create-job",
          "description": "Create long-running background jobs with retry policies, timeouts, cancellation, cleanup, progress tracking, permissions, and runners (inline, worker thread, or a detached process that outlives the server)",
          "examples": [
            {
              "name": "basic-report-job",
              "description": "A minimal job that generates a report with progress tracking and structured output.",
              "level": "basic",
              "tags": ["development", "job", "report"],
              "features": [
                "Defining a job with `@Job` decorator including `inputSchema`, `outputSchema`, and `timeout`",
                "Reporting progress at each stage using `this.progress(pct, total, message)`",
                "Using `this.log()` for persistent, queryable log entries"
              ]
            },
            {
              "name": "detached-export-job",
              "description": "An export job that runs in a process of its own, survives a server restart and is cancelled from any server.",
              "level": "advanced",
              "tags": ["development", "job", "detached", "worker", "sqlite", "cancel"],
              "features": [
                "`runner: 'detached'`: each run in a process of its own that outlives the server that started it",
                "A store the runner and every server share (the top-level `sqlite`), which the runs live in",
                "Reading and cancelling a run from a server started after it, and a `cleanup` the runner runs on a cancel",
                "Runs whose runner died settled as `interrupted` when the next server boots, with their cleanup",
                "`runner: 'worker'` for a CPU-heavy job that runs in a worker thread instead"
              ]
            },
            {
              "name": "durable-build-job",
              "description": "A build job on a SQLite store with a timeout, a cleanup, admission limits, cancel and a subscribed run handle.",
              "level": "advanced",
              "tags": ["development", "job", "sqlite", "cancel", "timeout"],
              "features": [
                "Keeping runs in a SQLite file with `jobs.store.sqlite`, shared by the processes on one machine",
                "A per-attempt `timeout`, and `@Job({ cleanup })` that runs on a timeout, a cancel or a shutdown",
                "Passing `this.signal` to the work so a timeout or cancel stops it",
                "`jobs.admission` with `concurrency`, `memoryMb` and `maxWaitMs`",
                "Cancelling with `cancel_job`, and following progress on `job://runs/{runId}`"
              ]
            },
            {
              "name": "job-with-permissions",
              "description": "A data export job with declarative permission controls, plus a function-style job for simple tasks.",
              "level": "advanced",
              "tags": ["development", "redis", "job", "permissions"],
              "features": [
                "Declarative `permissions` as an array of `{ action, roles, scopes, custom }` rules",
                "Using `tags` and `labels` for categorization and filtering",
                "The `job()` function builder for simple jobs that need no class, reporting through `ctx.log()` and `ctx.progress()`",
                "Full server registration with `jobs.enabled: true` and a Redis store"
              ]
            },
            {
              "name": "job-with-retry",
              "description": "A job that syncs data from an external API with automatic retry, exponential backoff, and batch progress tracking.",
              "level": "intermediate",
              "tags": ["development", "job", "retry"],
              "features": [
                "Configuring `retry` with `maxAttempts`, `backoffMs`, `backoffMultiplier`, and `maxBackoffMs`",
                "Using `this.attempt` to log retry context (1-based attempt counter)",
                "Using `this.fail()` to abort execution and trigger the retry flow",
                "Combining batch processing with `this.progress()` for granular tracking"
              ]
            }
          ]
        },
        {
          "name": "create-plugin-hooks",
          "description": "Intercept and extend FrontMCP flows using before, after, around, finally, and stage hook decorators",
          "examples": [
            {
              "name": "basic-logging-plugin",
              "description": "Demonstrates a plugin that logs tool execution using `@Will` and `@Did` hook decorators from the pre-built `ToolHook` export.",
              "level": "basic",
              "tags": ["development", "plugin-hooks", "plugin", "hooks", "logging"],
              "features": [
                "Using `ToolHook` pre-built export instead of calling `FlowHooksOf('tools:call-tool')` directly",
                "Destructuring `Will` and `Did` decorators from the hook object",
                "Setting `priority: -100` on `@Will` so the logging hook runs before the stage's other `@Will` hooks (lower runs first)",
                "Reading the tool name and arguments from `ctx.toolName` and `ctx.toolInput` and logging with `ctx.logger`",
                "Registering a plugin in the `plugins` array of `@App`"
              ]
            },
            {
              "name": "caching-with-around",
              "description": "Demonstrates wrapping tool execution with an `@Around` hook to implement result caching with TTL-based expiry.",
              "level": "intermediate",
              "tags": ["development", "cache", "plugin-hooks", "plugin", "hooks", "caching"],
              "features": [
                "Using `@Around` to wrap the `execute` stage with before-and-after logic",
                "Calling `await next()` to run the original stage, then reading its result from `toolContext.output`",
                "Short-circuiting execution by returning cached data without calling `next()`",
                "Building a cache key from the tool `name` and `arguments` in `ctx.state.required.input`"
              ]
            },
            {
              "name": "tool-level-hooks-and-stage-short-circuit",
              "description": "Demonstrates two advanced patterns: adding `@Will`/`@Did` hooks directly on a `@Tool` class (scoped to that tool only), and ending the flow from a plugin `@Stage` hook with `ctx.respond()` to mock one tool.",
              "level": "advanced",
              "tags": ["development", "plugin-hooks", "plugin", "hooks", "tool", "level"],
              "features": [
                "Placing `@Will('execute')` and `@Did('execute')` directly on a `@Tool` class so hooks fire only for that tool",
                "Using `this.fail()` in a `@Will` hook to abort execution when preconditions are not met",
                "Using `this.mark()` to record lifecycle checkpoints during hook execution",
                "A plugin `@Stage('execute')` runs alongside the tool's own `execute` step and its return value is ignored",
                "Calling `ctx.respond()` from a `@Stage` hook with a `filter` predicate to end the flow for one tool name",
                "The difference between tool-level hooks (scoped to one tool) and plugin-level hooks (fire for all tools)"
              ]
            }
          ]
        },
        {
          "name": "create-plugin",
          "description": "Build plugins with providers, context extensions, lifecycle hooks, and contributed tools",
          "examples": [
            {
              "name": "basic-plugin-with-provider",
              "description": "A minimal plugin that contributes an injectable service via the `providers` and `exports` arrays.",
              "level": "basic",
              "tags": ["development", "plugin", "provider"],
              "features": [
                "Creating a plugin with `@Plugin` decorator that bundles a `@Provider` class",
                "Listing providers in both `providers` (for DI registration) and `exports` (for external access)",
                "Registering a plugin in the `plugins` array of `@FrontMcp`"
              ]
            },
            {
              "name": "configurable-dynamic-plugin",
              "description": "A plugin that accepts runtime configuration via `DynamicPlugin` and extends decorator metadata with custom fields.",
              "level": "advanced",
              "tags": ["development", "plugin", "configurable", "dynamic"],
              "features": [
                "Extending `DynamicPlugin<TOptions, TInput>` for runtime-configurable plugins",
                "Implementing `static dynamicProviders()` to return a named factory provider built from the input options",
                "Using `TInput` with optional fields and resolving defaults in one helper shared by the constructor and `dynamicProviders()`",
                "Extending decorator metadata via `declare global { interface ExtendFrontMcpToolMetadata }`",
                "Reading the custom metadata in a `@ToolHook.Did` hook that receives the flow context (`FlowCtxOf`)",
                "Augmenting both `ExecutionContextBase` and `PromptContext` for full context extension coverage",
                "Registering the plugin with `MyPlugin.init({ ... })` in the `plugins` array"
              ]
            },
            {
              "name": "plugin-with-context-extension",
              "description": "A plugin that adds a `this.auditLog` property to all execution contexts using context extensions and module augmentation.",
              "level": "intermediate",
              "tags": ["development", "sdk", "plugin", "context", "extension"],
              "features": [
                "Defining a typed DI token with `Token<T> = Symbol('...')` in a dedicated symbols file",
                "Binding the token with a named factory provider and listing that same definition in `providers` and `exports`",
                "Module augmentation via `declare module '@frontmcp/sdk'` to add `readonly auditLog` to `ExecutionContextBase` and `PromptContext`",
                "Registering `contextExtensions` in `@Plugin` metadata with `property`, `token`, and `errorMessage`",
                "Side-effect import of the context extension file in both the plugin and the barrel export",
                "Accessing the extended property (`this.auditLog`) in a tool, with the caller identity from `this.auth.user.sub`"
              ]
            }
          ]
        },
        {
          "name": "create-prompt",
          "description": "Define reusable AI interaction patterns that produce structured message sequences",
          "examples": [
            {
              "name": "basic-prompt",
              "description": "A simple prompt that generates a structured code review message from user-provided arguments.",
              "level": "basic",
              "tags": ["development", "prompt", "create-prompt"],
              "features": [
                "Extending `PromptContext` and implementing `execute(args)` returning `GetPromptResult`",
                "Declaring prompt `arguments` with `required: true` for mandatory parameters",
                "Framework validates required arguments before `execute()` runs",
                "Registering the prompt in the `prompts` array of `@App`"
              ]
            },
            {
              "name": "dynamic-rag-prompt",
              "description": "A prompt that queries a knowledge base via DI to build context-aware messages at runtime.",
              "level": "advanced",
              "tags": ["development", "prompt", "dynamic", "rag"],
              "features": [
                "Performing async operations (knowledge base search) inside `execute()` to generate context-aware prompts",
                "Resolving a DI provider via `this.get(KNOWLEDGE_BASE)` for service access",
                "Using `this.mark(stage)` for execution stage tracking in complex prompt generation",
                "Building dynamic message content from external data sources at runtime"
              ]
            },
            {
              "name": "multi-turn-debug-session",
              "description": "A prompt that uses alternating user/assistant messages to guide a structured debugging conversation.",
              "level": "intermediate",
              "tags": ["development", "session", "prompt", "multi", "turn", "debug"],
              "features": [
                "Using `assistant` role messages to prime expected response patterns and guide LLM behavior",
                "Alternating `user` and `assistant` roles to create a structured multi-turn conversation",
                "Optional arguments that conditionally add content to the prompt",
                "The assistant message establishes a systematic debugging approach the LLM will follow"
              ]
            }
          ]
        },
        {
          "name": "create-provider",
          "description": "Create singleton DI providers for database pools, API clients, and shared services",
          "examples": [
            {
              "name": "basic-database-provider",
              "description": "A provider that manages a database connection pool, bound through `AsyncProvider({ useFactory })` so the pool is opened before any tool runs, and closed in `onShutdown()`.",
              "level": "basic",
              "tags": ["development", "database", "provider"],
              "features": [
                "Defining a typed token with `Token<T>` using a `Symbol` for DI identification",
                "Using `AsyncProvider({ provide, name, scope, useFactory })` so async setup completes before tool execution",
                "Closing the pool in `onShutdown()`, which runs after the requests in flight finish",
                "Consuming the provider in a tool via `this.get(DB_TOKEN)` with full type safety",
                "Registering the factory in the `providers` array so tools can resolve it"
              ]
            },
            {
              "name": "config-and-api-providers",
              "description": "A configuration provider and an HTTP API client provider, organized as one folder per provider with co-located specs and barrels.",
              "level": "intermediate",
              "tags": ["development", "provider", "config", "api", "providers"],
              "features": [
                "A configuration provider using `readonly` properties from environment variables (sync construction)",
                "An API client provider that reads credentials in the constructor, so a missing one fails startup",
                "Folder-per-provider layout (`src/apps/main/providers/<slug>/`) with a barrel `index.ts` and a co-located `.provider.spec.ts`",
                "Top-level `src/apps/main/providers/index.ts` barrel re-exporting each provider folder",
                "Registering providers at `@FrontMcp` level for server-wide sharing across all apps",
                "Separating token definitions from provider implementations for clean dependency boundaries"
              ]
            }
          ]
        },
        {
          "name": "create-resource",
          "description": "Expose data to AI clients via URI-based static resources and parameterized templates",
          "examples": [
            {
              "name": "basic-static-resource",
              "description": "A static resource that exposes application configuration at a fixed URI.",
              "level": "basic",
              "tags": ["development", "resource", "static"],
              "features": [
                "Using `@Resource` with a fixed URI that follows RFC 3986 (has a valid scheme)",
                "Returning a `ReadResourceResult` with `contents` array containing `uri`, `mimeType`, and `text`",
                "Setting `mimeType` to indicate the content type of the resource",
                "Registering the resource in the `resources` array of `@App`"
              ]
            },
            {
              "name": "binary-and-multi-content",
              "description": "A resource serving binary blob data and a resource returning multiple content items.",
              "level": "advanced",
              "tags": ["development", "cli", "resource", "binary", "multi", "content"],
              "features": [
                "Returning binary data as base64-encoded `blob` (not `text`) for images and other binary assets",
                "Using `@frontmcp/utils` for file system operations (`readFileBuffer`) instead of `fs` directly",
                "Returning multiple content items from a single resource using fragment URIs (`#metrics`, `#charts`)",
                "Each content item has its own `uri`, `mimeType`, and `text` or `blob` field"
              ]
            },
            {
              "name": "materialized-resource",
              "description": "A resource serving a stored value that another process updates, with live updates.",
              "level": "intermediate",
              "tags": ["development", "resource", "materialized", "subscribe", "sqlite"],
              "features": [
                "Declaring a `resourceStore()` on SQLite once, in a module the server and the writers import",
                "Serving a key with `@Resource({ from })` and `MaterializedResourceContext`",
                "Writing atomically with `set()` and `update()` from a tool and from another process",
                "Subscribers get `notifications/resources/updated` after a revision change, and read the latest value"
              ]
            },
            {
              "name": "parameterized-template",
              "description": "A resource template with typed URI parameters and argument autocompletion.",
              "level": "intermediate",
              "tags": ["development", "resource", "parameterized", "template"],
              "features": [
                "Using `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders",
                "Typing the `ResourceContext` generic parameter for compile-time parameter checking",
                "Implementing a convention-based completer (`userIdCompleter`) for argument autocompletion",
                "Accessing DI providers via `this.get()` in both `execute()` and completer methods"
              ]
            }
          ]
        },
        {
          "name": "create-skill-with-tools",
          "description": "Create skills that combine structured instructions with MCP tool references for orchestration",
          "examples": [
            {
              "name": "basic-tool-orchestration",
              "description": "A skill that guides an AI client through a deploy workflow using referenced MCP tools.",
              "level": "basic",
              "tags": ["development", "skill", "tools", "tool", "orchestration"],
              "features": [
                "Referencing tools by class (`BuildProjectTool`) and by string name (`'health_check'`)",
                "Mixing class references and string names in a single `tools` array",
                "Writing step-by-step instructions that guide the AI to use specific tools",
                "The `skill()` function builder for tool-referencing skills that need no class"
              ]
            },
            {
              "name": "directory-skill-with-tools",
              "description": "A directory-based skill loaded with `skillDir()`, plus a class-based skill using Agent Skills spec metadata fields.",
              "level": "advanced",
              "tags": ["development", "skill", "tools", "directory"],
              "features": [
                "Loading a directory-based skill with `skillDir()` including SKILL.md frontmatter with tool entries",
                "Mixing all three tool reference styles in one `tools` array: class, string, and object",
                "Agent Skills spec fields: `priority`, `license`, `compatibility`, `allowedTools`, `specMetadata`",
                "Bundled resource directories: `scripts`, `references`, `assets`",
                "File-based instructions with `{ file: './docs/codebase-audit.md' }`"
              ]
            },
            {
              "name": "incident-response-skill",
              "description": "A skill that uses object-style tool references with purpose descriptions and required flags, plus strict validation.",
              "level": "intermediate",
              "tags": ["development", "skill", "tools", "incident", "response"],
              "features": [
                "Object-style tool references with `name`, `purpose`, and `required` fields",
                "Using `toolValidation: 'strict'` to fail at startup if any referenced tool is missing",
                "Combining tool references with `parameters` and `examples` for full skill metadata",
                "Setting `visibility: 'mcp'` to restrict discovery to MCP protocol only",
                "Registering both skills and their referenced tools in the same `@App`"
              ]
            }
          ]
        },
        {
          "name": "create-skill",
          "description": "Create instruction-only skills that package knowledge and workflow guides for AI clients",
          "examples": [
            {
              "name": "basic-inline-skill",
              "description": "A minimal instruction-only skill with inline content and the function builder alternative.",
              "level": "basic",
              "tags": ["development", "skill", "inline"],
              "features": [
                "Creating a class-based instruction-only skill with `@Skill` and `SkillContext`",
                "Using inline string instructions for short, self-contained guides",
                "The `skill()` function builder as a lighter alternative when no `build()` override is needed",
                "Setting `visibility` to control where the skill is discoverable"
              ]
            },
            {
              "name": "directory-based-skill",
              "description": "A skill loaded from a directory structure with SKILL.md frontmatter, plus file-based and URL-based instruction sources.",
              "level": "advanced",
              "tags": ["development", "remote", "skill", "directory", "based"],
              "features": [
                "Loading a skill from a directory with `skillDir()` including SKILL.md frontmatter and bundled resources",
                "The SKILL.md YAML frontmatter format for metadata (name, description, tags, parameters, examples)",
                "File-based instructions with `{ file: './path.md' }` resolved relative to the skill file",
                "URL-based instructions with `{ url: '...' }` fetched at build time"
              ]
            },
            {
              "name": "parameterized-skill",
              "description": "A skill with customizable parameters, usage examples for AI guidance, and controlled visibility.",
              "level": "intermediate",
              "tags": ["development", "skill", "parameterized"],
              "features": [
                "Defining `parameters` to let callers customize skill behavior at invocation time",
                "Providing `examples` with `scenario` and `expectedOutcome` to guide AI application",
                "Using `tags` for skill categorization and filtering",
                "Controlling discovery with `visibility: 'mcp'` (MCP-only) vs `visibility: 'both'` (default)",
                "Using `hideFromDiscovery: true` to register a skill that is invocable by name but not listed"
              ]
            }
          ]
        },
        {
          "name": "create-workflow",
          "description": "Connect multiple jobs into managed DAG pipelines with dependencies, conditions, and triggers",
          "examples": [
            {
              "name": "basic-deploy-pipeline",
              "description": "A linear workflow that builds, tests, and deploys a service with step dependencies and dynamic input.",
              "level": "basic",
              "tags": ["development", "workflow", "pipeline"],
              "features": [
                "Defining a workflow with `@Workflow` decorator and sequential `steps`",
                "Using `dependsOn` to establish step execution order",
                "Passing dynamic input from a previous step using the callback form `(steps) => ({...})`",
                "Registering both jobs and workflows in `@App` with jobs enabled"
              ]
            },
            {
              "name": "parallel-validation-pipeline",
              "description": "A workflow that validates multiple datasets in parallel, then conditionally merges results or notifies on failure.",
              "level": "intermediate",
              "tags": ["development", "workflow", "parallel", "validation", "pipeline"],
              "features": [
                "Running steps in parallel by omitting `dependsOn` (no mutual dependencies)",
                "Using `maxConcurrency` to limit how many steps run at the same time",
                "Conditional steps with `condition` that check `.state` of previous steps",
                "Fan-out/fan-in pattern: parallel validation steps converge into a merge step",
                "Branching: separate success and failure notification paths"
              ]
            },
            {
              "name": "webhook-triggered-workflow",
              "description": "A CI/CD workflow triggered by a webhook, featuring `continueOnError`, per-step conditions, and the `workflow()` function builder.",
              "level": "advanced",
              "tags": ["development", "workflow", "webhook", "triggered"],
              "features": [
                "Webhook trigger with `trigger: 'webhook'` and `webhook: { path, secret, methods }`",
                "Using `continueOnError: true` to allow the workflow to proceed past non-critical step failures",
                "Conditional branching: separate success and failure notification steps based on prior step state",
                "Workflow-level `permissions` for access control",
                "The `workflow()` function builder as a lighter alternative to the class pattern"
              ]
            }
          ]
        },
        {
          "name": "decorators-guide",
          "description": "Complete reference for the hierarchical decorator system from @FrontMcp to @Tool",
          "examples": [
            {
              "name": "agent-skill-job-workflow",
              "description": "Demonstrates the advanced decorator types: `@Agent` for autonomous AI agents, `@Skill` for knowledge packages, `@Job` for background tasks, and `@Workflow` for multi-step orchestration.",
              "level": "advanced",
              "tags": ["development", "decorators", "agent", "skill", "job", "workflow"],
              "features": [
                "`@Agent` with LLM config, input schema, and delegated tools for autonomous task execution",
                "`@Skill` with inline instructions and tool references for reusable knowledge packages",
                "`@Job` with retry policy, timeout, and typed input/output for background processing",
                "`@Workflow` with ordered steps, `dependsOn` for sequencing, and `condition` for conditional execution",
                "Enabling jobs and skills at the server level via `jobs: { enabled: true }` and `skillsConfig: { enabled: true }`",
                "All advanced decorators registered in a single `@App` module"
              ]
            },
            {
              "name": "basic-server-with-app-and-tools",
              "description": "Demonstrates the minimal decorator hierarchy to create a working FrontMCP server with one app containing a tool and a resource.",
              "level": "basic",
              "tags": ["development", "decorators", "app", "tools"],
              "features": [
                "The `@FrontMcp` -> `@App` -> `@Tool`/`@Resource`/`@Prompt` nesting hierarchy",
                "Tool classes extend `ToolContext` and implement `execute()`",
                "Resource classes extend `ResourceContext` and implement `execute(uri, params)`",
                "Prompt classes extend `PromptContext` and implement `execute(args: Record<string, string>)`",
                "Apps group related tools, resources, and prompts into logical modules"
              ]
            },
            {
              "name": "multi-app-with-plugins-and-providers",
              "description": "Demonstrates a server with multiple `@App` modules, a `@Provider` for dependency injection, and a `@Plugin` for cross-cutting concerns.",
              "level": "intermediate",
              "tags": ["development", "database", "multi-app", "decorators", "multi", "app"],
              "features": [
                "Organizing a server into multiple `@App` modules (`analytics` and `admin`)",
                "Decorating a service class with `@Provider({ name, scope })` so it acts as its own DI token (the strict schema rejects `useFactory`/`useClass`/`provide` — use `AsyncProvider` for those)",
                "Accessing injected dependencies via `this.get(DatabaseClient)` in tools and resources",
                "Using `@ResourceTemplate` with URI parameters (`{dashboardId}`) for dynamic resources",
                "Registering a `@Plugin` at the server level so it applies across all apps",
                "Global plugins go in `@FrontMcp({ plugins })`, app-scoped providers go in `@App({ providers })`"
              ]
            }
          ]
        },
        {
          "name": "official-adapters",
          "description": "Overview of all official FrontMCP adapters that convert external definitions into MCP primitives",
          "examples": []
        },
        {
          "name": "official-plugins",
          "description": "Guide to the 8 official plugins for discovery, memory, auth, caching, flags, monitoring, WebMCP, and large answers",
          "examples": [
            {
              "name": "cache-and-feature-flags",
              "description": "Demonstrates combining the Cache plugin for tool result caching with the Feature Flags plugin for gating tools behind flags.",
              "level": "intermediate",
              "tags": ["development", "feature-flags", "cache", "plugins", "feature", "flags"],
              "features": [
                "Combining `CachePlugin` and `FeatureFlagPlugin` in the same server",
                "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"
              ]
            },
            {
              "name": "production-multi-plugin-setup",
              "description": "Demonstrates a production-ready server configuration combining CodeCall, Remember, Approval, Cache, and Feature Flags plugins with Redis storage and external flag services.",
              "level": "advanced",
              "tags": ["development", "feature-flags", "redis", "keyword-search", "cache", "approval"],
              "features": [
                "Configuring all 5 stable official plugins together in a production server",
                "CodeCall in `codecall_only` mode with TF-IDF search and synonym expansion for semantic tool discovery",
                "Remember plugin with Redis storage, encryption enabled, and LLM-accessible memory tools",
                "Approval plugin in `webhook` mode with external PKCE-secured approval flow and audit logging",
                "Cache plugin with Redis storage and 24-hour default TTL",
                "Feature Flags with LaunchDarkly integration for external flag management",
                "Per-tool `approval` metadata with risk level and scope configuration",
                "Per-tool `featureFlag` with a `defaultValue` fallback if flag evaluation fails",
                "Using `this.approval.isApproved()` and `this.remember.set()` together in a single tool"
              ]
            },
            {
              "name": "remember-plugin-session-memory",
              "description": "Demonstrates installing the Remember plugin and using `this.remember` in tools to store and retrieve session memory.",
              "level": "basic",
              "tags": ["development", "session", "plugins", "remember", "plugin", "memory"],
              "features": [
                "Installing `RememberPlugin` with `type: 'memory'` for development",
                "Enabling `tools: { enabled: true }` to expose LLM-callable memory tools (`remember_this`, `recall`, etc.), whose `scope` defaults to `session`",
                "Using `this.remember.set()` with default `session` scope and explicit `user` scope (refused for an anonymous caller)",
                "Using `this.remember.get()` with a `defaultValue` fallback",
                "Using `this.remember.knows()` to check key existence without retrieving the value"
              ]
            }
          ]
        },
        {
          "name": "offload-cpu-work",
          "description": "Run CPU-heavy work in a worker-thread pool with this.offload() and @Resource({ worker true }), so the server keeps answering",
          "examples": []
        },
        {
          "name": "openapi-adapter",
          "description": "Convert OpenAPI 3.x specifications into MCP tools with authentication, polling, transforms, format resolution, and $ref security",
          "examples": [
            {
              "name": "authenticated-adapter-with-polling",
              "description": "Demonstrates configuring authentication (API key and bearer token) and automatic spec polling for OpenAPI adapters.",
              "level": "intermediate",
              "tags": ["development", "auth", "openapi", "security", "adapters", "authenticated"],
              "features": [
                "Three authentication methods: `staticAuth.apiKey`, `staticAuth.jwt`, and dynamic `securityResolver`",
                "Using `securityResolver` for per-request dynamic authentication based on the calling context",
                "Enabling `polling` to automatically refresh tool definitions when the upstream spec changes",
                "Loading secrets from environment variables instead of hardcoding them",
                "Each adapter has a unique `name` to avoid tool naming collisions"
              ]
            },
            {
              "name": "basic-openapi-adapter",
              "description": "Demonstrates converting an OpenAPI specification into MCP tools automatically using `OpenapiAdapter` with minimal configuration.",
              "level": "basic",
              "tags": ["development", "openapi", "adapters", "adapter"],
              "features": [
                "Using `OpenapiAdapter.init()` with just `name` and `url` to auto-generate MCP tools",
                "Each OpenAPI operation becomes a tool named `<adapter-name>:<operationId>`",
                "The adapter is registered in the `adapters` array of `@App`, not in `plugins`",
                "The `name` field serves as the namespace prefix to prevent tool name collisions"
              ]
            },
            {
              "name": "format-resolution-and-custom-resolvers",
              "description": "Demonstrates using built-in and custom format resolvers to enrich tool input schemas with concrete constraints from OpenAPI format values.",
              "level": "intermediate",
              "tags": ["development", "openapi", "adapters", "format", "schema", "validation"],
              "features": [
                "Enabling built-in format resolvers with `resolveFormats: true` for uuid, date-time, email, int32, etc.",
                "Adding custom format resolvers for domain-specific formats (phone, currency)",
                "Merging custom resolvers with built-ins where custom takes precedence",
                "Using custom-only resolvers without built-ins for full control"
              ]
            },
            {
              "name": "multi-api-hub-with-inline-spec",
              "description": "Demonstrates registering multiple OpenAPI adapters from different APIs in a single app, including one with an inline spec definition instead of a remote URL.",
              "level": "advanced",
              "tags": ["development", "openapi", "remote", "adapters", "multi", "api"],
              "features": [
                "Registering multiple adapters in a single `@App` with unique names for tool namespacing",
                "Using `additionalHeaders` for header-based authentication (GitHub token)",
                "Providing an inline `spec` object instead of a remote `url` for APIs without hosted specs",
                "Each adapter's tools are namespaced: `github:*`, `jira:*`, `internal:*`",
                "Only one of `url` or `spec` should be provided per adapter; `spec` takes precedence"
              ]
            },
            {
              "name": "ref-security-and-filtering",
              "description": "Demonstrates configuring $ref / spec-URL resolution security to prevent SSRF attacks (GHSA-65h7-9wrw-629c) and filtering which API operations become MCP tools.",
              "level": "intermediate",
              "tags": ["development", "openapi", "adapters", "security", "ssrf", "filtering"],
              "features": [
                "Secure defaults: external `$ref` resolution off, spec-URL redirects not followed, internal/private targets blocked (DNS-resolved) — on `mcp-from-openapi` >= 2.5.0",
                "Opting back into external refs with `allowedProtocols`, and restricting the spec URL + `$ref`s with `allowedHosts`",
                "Using `allowInternalIPs` for trusted internal/local targets (governs the spec URL and `$ref`s)",
                "Filtering operations with `readOnlyOnly`, `includeTags`, `includePaths`, `excludeMethods`, `includeOperations`, `excludeOperations`, and `filterFn`",
                "Combining security hardening with operation filtering for a production-ready setup"
              ]
            }
          ]
        },
        {
          "name": "result-handles-plugin",
          "description": "Fold large tool answers into a preview, a shape and a handle, and let the model read slices with result_query",
          "examples": []
        }
      ]
    },
    {
      "name": "frontmcp-extensibility",
      "category": "extensibility",
      "description": "Use when extending FrontMCP beyond the core SDK by integrating external npm packages, libraries, or third-party services into providers and tools. Covers VectoriaDB for in-memory semantic and vector search (ML-based embeddings or TF-IDF keyword engines, with persistence) and the tamper-evident, hash-chained skill audit log (pluggable signer and store, with chain verification). Triggers: add semantic search, vector search, embeddings, similarity search, recommendations, ML features, audit logging, or integrate an external library, database, or API beyond the built-in SDK.",
      "path": "frontmcp-extensibility",
      "targets": ["all"],
      "hasResources": true,
      "tags": ["extensibility", "vectoriadb", "search", "integration", "npm", "provider", "external-services"],
      "bundle": ["full"],
      "priority": 10,
      "references": [
        {
          "name": "skill-audit-log",
          "description": "Tamper-evident, hash-chained audit log for skill action executions — pluggable signer, pluggable store, offline verification.",
          "examples": [
            {
              "name": "custom-store",
              "description": "Implement a custom SkillAuditStore that streams records to S3 with one object per sequence.",
              "level": "advanced",
              "tags": ["extensibility", "audit", "custom", "s3", "store"],
              "features": [
                "Implements the SkillAuditStore interface (nextSequence, appendAtSequence, tail, read)",
                "One S3 object per sequence keeps individual records immutable and verifiable",
                "tail() returns the latest record so the writer can chain prevHash deterministically",
                "read({ from, limit }) supports incremental verifyChain runs in CI (pass the record before the window as `previous`)"
              ]
            },
            {
              "name": "verify-chain",
              "description": "Verify a stored chain offline using verifyChain and the bundle-signing key registry.",
              "level": "intermediate",
              "tags": ["extensibility", "audit", "verification", "chain", "rs256"],
              "features": [
                "verifyChain returns { ok: true, verified } or { ok: false, breakAt, reason } for the first detected break",
                "defaultAuditSignatureVerifier dispatches on record.signatureAlg (HS256 or RS256)",
                "Trusted keys are an AuditTrustedKey[] list; each record's signatureKeyId selects its key",
                "read() returns the chain in sequence order from any SkillAuditStore implementation",
                "verifyChain(window, keys, verifier, { previous }) verifies a window read with read({ from }) against the record before it"
              ]
            }
          ]
        },
        {
          "name": "vectoriadb",
          "description": "Use VectoriaDB for in-memory vector search with ML-based or TF-IDF engines in FrontMCP servers",
          "examples": [
            {
              "name": "product-catalog-search",
              "description": "Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog.",
              "level": "advanced",
              "tags": ["extensibility", "vectoriadb", "product", "catalog", "search"],
              "features": [
                "Typed document metadata with `ProductDoc extends DocumentMetadata`",
                "Batch operations with `db.addMany()` for efficient catalog indexing",
                "Multi-criteria filtered search combining category, price, and stock status",
                "`maxDocuments` option for DoS protection on large datasets",
                "`FileStorageAdapter` for persisting the entire product index to disk",
                "Semantic matching: \"something to block office noise\" finds \"noise-canceling headphones\""
              ]
            },
            {
              "name": "semantic-search-with-persistence",
              "description": "Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.",
              "level": "intermediate",
              "tags": ["extensibility", "vectoriadb", "semantic-search", "semantic", "search", "persistence"],
              "features": [
                "Using `VectoriaDB` with transformer models for true semantic search",
                "Configuring HNSW index (`useHNSW: true`) for fast O(log n) search on large datasets",
                "Filtered search with a callback: `filter: (m) => m.category === category`",
                "`FileStorageAdapter` for persisting vectors to disk (restored without re-embedding)",
                "Async initialization with `await db.initialize()` (downloads model on first run)",
                "Update-or-add pattern with `db.has(id)` check"
              ]
            },
            {
              "name": "tfidf-keyword-search",
              "description": "Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider. `TFIDFVectoria` indexes a single text string per document, so multi-field documents are concatenated into one searchable blob; the original fields are kept in `metadata` for use on search results.",
              "level": "basic",
              "tags": ["extensibility", "vectoriadb", "keyword-search", "tfidf", "keyword", "search"],
              "features": [
                "Using `TFIDFVectoria` for zero-dependency keyword search (no model downloads)",
                "Calling `addDocument(id, text, metadata)` with a single concatenated text string",
                "Calling `reindex()` after adding documents (required for TFIDFVectoria)",
                "Wrapping the search engine in a FrontMCP provider with `ProviderScope.GLOBAL`",
                "Injecting the provider into tools via `this.get(FAQSearchProvider)`"
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "frontmcp-guides",
      "category": "guides",
      "description": "Tutorials, end-to-end walkthroughs, and complete reference projects for FrontMCP. Use when you want a getting-started guide, a full worked example, or to learn best practices by following a step-by-step build rather than a single API reference. Includes a beginner weather-API server (tool plus static resource, Zod schemas, E2E tests), an authenticated task manager (CRUD tools, Redis storage, OAuth, Vercel deploy, authenticated E2E tests), and a multi-app knowledge base (vector search, semantic resources, an AI research agent, audit logging). Triggers: tutorial, walkthrough, how do I build, getting started, end-to-end example, sample project, learn FrontMCP, full app example.",
      "path": "frontmcp-guides",
      "targets": ["all"],
      "hasResources": true,
      "tags": ["guides", "examples", "best-practices", "architecture", "walkthrough", "end-to-end"],
      "bundle": ["recommended", "full"],
      "priority": 10,
      "references": [
        {
          "name": "example-knowledge-base",
          "description": "Multi-app knowledge base with vector storage, semantic search, AI research agent, and audit plugin",
          "examples": [
            {
              "name": "agent-and-plugin",
              "description": "Shows an autonomous research agent with inner tools and a real `ToolHook`-based plugin that hooks into the `tools:call-tool` flow for audit logging.",
              "level": "advanced",
              "tags": ["guides", "knowledge-base", "knowledge", "base", "agent", "plugin"],
              "features": [
                "Agent with `@Agent` decorator, LLM config, inner tools, and system instructions",
                "Configuring the inner-loop limit via `@Agent({ execution: { maxIterations } })` (framework drives iteration; no `this.run(...)`)",
                "Plugin built on a real `ToolHook` decorator: one `@ToolHook.Around(\"execute\")` hook that sees the start, the end and any error",
                "Keeping the start time in a local variable across `await next()` (the flow state accepts only its declared keys)",
                "Using `flowCtx.state.required.toolContext` to read tool metadata and authInfo inside hooks",
                "Non-blocking audit logging (`.catch()` prevents audit failures from breaking tools)"
              ]
            },
            {
              "name": "multi-app-composition",
              "description": "Shows how to compose multiple apps (Ingestion, Search, Research) into a single server with shared providers, plugins, and agent registration.",
              "level": "basic",
              "tags": ["guides", "multi-app", "knowledge-base", "knowledge", "base", "multi"],
              "features": [
                "Composing three apps into one server: Ingestion (tools + providers), Search (tools + resources), Research (agents)",
                "Sharing providers across apps (VectorStoreProvider used by both Ingestion and Search)",
                "Registering plugins at the server level (AuditLogPlugin applies to all tools)",
                "Registering agents in a dedicated app for AI-powered features"
              ]
            },
            {
              "name": "vector-search-and-resources",
              "description": "Shows a semantic search tool with embedding generation and a resource template for retrieving documents by ID using URI parameters.",
              "level": "intermediate",
              "tags": ["guides", "vectoriadb", "semantic-search", "knowledge-base", "knowledge", "base"],
              "features": [
                "Semantic search tool that delegates embedding generation to VectoriaDB via `store.search(query, topK)`",
                "Using `this.mark()` for execution phase tracing",
                "Resource template with `uriTemplate: 'kb://documents/{documentId}'` for parameterized URIs",
                "Typed params via `ResourceContext<{ documentId: string }>` for type-safe URI parameters",
                "Returning `ReadResourceResult` with proper MCP protocol structure"
              ]
            }
          ]
        },
        {
          "name": "example-task-manager",
          "description": "Authenticated task management server with CRUD tools, Redis storage, OAuth, and Vercel deployment",
          "examples": [
            {
              "name": "auth-and-crud-tools",
              "description": "Shows how to create CRUD tools with authentication, using `this.auth?.user.sub` (the FrontMcpAuthContext exposed on every execution context) for user isolation and `this.get()` for dependency injection.",
              "level": "basic",
              "tags": ["guides", "auth", "session", "task-manager", "task", "manager"],
              "features": [
                "Using `this.auth?.user.sub` (FrontMcpAuthContext) for per-user data isolation",
                "Using `this.get(TaskStoreProvider)` for dependency injection of providers (class-as-token)",
                "Enforcing authentication with `this.fail()` when no authenticated user is present in `this.auth`",
                "Optional input fields with `.optional()` for filtering",
                "`outputSchema` with nested `z.array(z.object(...))` for structured responses"
              ]
            },
            {
              "name": "authenticated-e2e-tests",
              "description": "Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.",
              "level": "advanced",
              "tags": ["guides", "auth", "session", "e2e", "unit-test", "task-manager"],
              "features": [
                "Using `TestTokenFactory` to create JWT tokens for authenticated E2E tests",
                "Chaining `.withToken(token).buildAndConnect()` for authenticated clients",
                "Unit testing tools by mocking `this.get(TaskStoreProvider)` and the `auth` getter",
                "Stubbing the `auth` getter (FrontMcpAuthContext) with `Object.defineProperty(tool, 'auth', { value: { user: { sub } } })` for auth-dependent tools",
                "Testing the unauthenticated error path (no `auth` / anonymous user)"
              ]
            },
            {
              "name": "redis-provider-with-di",
              "description": "Shows how to create a Redis-backed provider using the class-as-token DI pattern (`@Provider({ name, scope })`) plus an `AsyncProvider` factory that runs the async Redis setup before any tool is invoked.",
              "level": "intermediate",
              "tags": ["guides", "redis", "node", "task-manager", "task", "manager"],
              "features": [
                "Class-as-token DI: `@Provider({ name, scope })` and inject via `this.get(TaskStoreProvider)`",
                "Building the singleton with `AsyncProvider({ provide, name, scope, useFactory })` for async setup",
                "Cleanup: `onShutdown()` quits the Redis client at shutdown, after the requests in flight finish",
                "Using `@frontmcp/utils` for `randomUUID()` instead of `node:crypto`",
                "Per-user data isolation using Redis hash keys (`tasks:${userId}`)"
              ]
            }
          ]
        },
        {
          "name": "example-weather-api",
          "description": "Beginner MCP server with a weather lookup tool, static resource, Zod schemas, and E2E tests",
          "examples": [
            {
              "name": "server-and-app-setup",
              "description": "Shows the server entry point, app registration, and static resource for a beginner FrontMCP weather API server.",
              "level": "basic",
              "tags": ["guides", "weather", "api", "app", "setup"],
              "features": [
                "Server entry point with `@FrontMcp` decorator and `info` configuration",
                "App registration with `@App` grouping tools and resources together",
                "Static resource that returns JSON data via `execute(uri)` and `ReadResourceResult`",
                "Clean separation between server, app, tools, and resources"
              ]
            },
            {
              "name": "unit-and-e2e-tests",
              "description": "Shows how to write unit tests for tools by mocking context methods, and E2E tests using `McpTestClient` and `TestServer`.",
              "level": "intermediate",
              "tags": ["guides", "e2e", "unit-test", "weather", "api", "unit"],
              "features": [
                "Unit testing tools by mocking `this.fetch()`, `this.fail()`, and other context methods",
                "Creating the tool with `Object.create(GetWeatherTool.prototype)` and injecting mock context methods with `Object.assign(tool, ctx)`",
                "E2E testing with `TestServer.start()` and `McpTestClient.create()`",
                "Asserting tool presence via `expect(tools.map((t) => t.name)).toContain(...)` and parsing resource JSON via `result.json<T>()`",
                "Proper cleanup with `client.disconnect()` and `server.stop()` in `afterAll`"
              ]
            },
            {
              "name": "weather-tool-with-schemas",
              "description": "Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`.",
              "level": "basic",
              "tags": ["guides", "weather", "api", "tool", "schemas"],
              "features": [
                "Defining Zod `inputSchema` with validation (`.min(1)`, `.enum()`, `.default()`)",
                "Defining `outputSchema` to prevent data leaks and ensure type safety",
                "Using `this.fetch()` for HTTP calls within tools",
                "Using `this.fail()` for business-logic error handling",
                "Using `.describe()` on schema fields for LLM-friendly tool descriptions"
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "frontmcp-observability",
      "category": "observability",
      "description": "Use when adding tracing, structured logging, metrics, or monitoring to a FrontMCP server. Covers zero-config OpenTelemetry distributed tracing across all flows; the this.telemetry API for custom spans, events, and attributes in tools, plugins, agents, and skills; structured JSON logging with trace correlation and configurable sinks (Winston, Pino, stdout); the off-by-default /metrics endpoint (process and framework metrics, Prometheus-compatible); event-loop stall detection that names the calls in flight; vendor integrations (Coralogix, Datadog, Logz.io, Grafana Cloud, or any OTLP backend); and testing spans, log correlation, and instrumentation. Triggers: observability, telemetry, tracing, logging, monitoring, OpenTelemetry, OTel, spans, metrics, Prometheus, event loop stall, blocked event loop, Datadog, Coralogix, Logz.io, Grafana, Winston, Pino.",
      "path": "frontmcp-observability",
      "targets": ["all"],
      "hasResources": true,
      "tags": [
        "router",
        "observability",
        "telemetry",
        "tracing",
        "logging",
        "monitoring",
        "opentelemetry",
        "otel",
        "spans"
      ],
      "bundle": ["recommended", "full"],
      "priority": 10,
      "references": [
        {
          "name": "metrics-endpoint",
          "description": "Configure the off-by-default /metrics endpoint that exposes process metrics and framework counters in Prometheus text format",
          "examples": [
            {
              "name": "enable-metrics-endpoint",
              "description": "Turn on the /metrics endpoint with defaults and scrape it with curl.",
              "level": "basic",
              "tags": ["observability", "metrics", "prometheus"],
              "features": [
                "Setting `metrics: { enabled: true }` on `@FrontMcp` to register `GET /metrics`",
                "Verifying the Prometheus text-exposition response with `curl`",
                "Reading process metrics + framework counters from a single scrape"
              ]
            }
          ]
        },
        {
          "name": "stall-detection",
          "description": "Find what blocks the event loop - a warning naming the calls in flight during each stall, a stall-seconds counter per entry, and GC pauses counted apart",
          "examples": [
            {
              "name": "find-a-blocking-tool",
              "description": "Turn on stall detection and see the warning name a tool that blocks the event loop.",
              "level": "basic",
              "tags": ["observability", "stalls", "event-loop", "metrics"],
              "features": [
                "Setting `observability: { stalls: { thresholdMs } }` on `@FrontMcp`",
                "Reading the `Event loop stalled for` warning that names the call in flight",
                "Scraping `frontmcp_event_loop_stall_seconds_total` per entry from `/metrics`"
              ]
            }
          ]
        },
        {
          "name": "structured-logging",
          "description": "Add structured JSON logging with trace correlation and configurable sinks (stdout, winston, pino, OTLP).",
          "examples": [
            {
              "name": "stdout-logging",
              "description": "Enable NDJSON structured logging to stdout with automatic trace correlation and field redaction.",
              "level": "basic",
              "tags": ["logging", "stdout", "ndjson", "redaction", "basic"],
              "features": [
                "NDJSON format for stdout (Docker/K8s log collection)",
                "Automatic trace context enrichment (trace_id, span_id)",
                "Sensitive field redaction (token → [REDACTED])"
              ]
            },
            {
              "name": "winston-integration",
              "description": "Forward FrontMCP structured log entries to your existing winston logger. Each entry includes trace_id and span_id as metadata.",
              "level": "intermediate",
              "tags": ["logging", "winston", "integration", "intermediate"],
              "features": [
                "WinstonSink forwarding structured entries with trace metadata",
                "Multiple sinks running simultaneously (stdout + winston)",
                "Winston transports handle file logging, remote forwarding, etc."
              ]
            }
          ]
        },
        {
          "name": "telemetry-api",
          "description": "Use this.telemetry in tools, plugins, and agents to create custom spans, events, and attributes.",
          "examples": [
            {
              "name": "agent-nested-tracing",
              "description": "Trace an agent's execution lifecycle including its nested tool calls. Every span shares the same trace ID.",
              "level": "advanced",
              "tags": ["telemetry", "agent", "nested", "tools", "trace-id"],
              "features": [
                "Agent span wraps the entire execution (including LLM loop)",
                "Nested tool calls automatically get their own spans",
                "All spans share the same trace ID for end-to-end visibility",
                "this.telemetry works identically in agents and tools"
              ]
            },
            {
              "name": "plugin-telemetry",
              "description": "Add telemetry events from a custom plugin's hooks. Events appear on the tool execution span, giving you visibility into plugin behavior within the trace.",
              "level": "intermediate",
              "tags": ["telemetry", "plugin", "hooks", "cache", "audit"],
              "features": [
                "Plugin hooks can access toolCtx.telemetry to add events to the active span",
                "Events from plugins appear in the same trace as the tool execution",
                "One `@ToolHook.Around('execute')` hook records success and failure while the execute span is open: a `Did` hook runs only after a successful execute",
                "Graceful degradation when observability is not enabled"
              ]
            },
            {
              "name": "skill-counters",
              "description": "Read built-in skill counters from the in-memory snapshot for tests and wire an OTel MeterProvider so counters export to OTLP in production.",
              "level": "intermediate",
              "tags": ["telemetry", "counters", "metrics", "skills", "otel", "meter-provider"],
              "features": [
                "this.telemetry.createCounter(name, description) creates a custom counter",
                "counter.inc(by, attrs) increments with bounded label cardinality",
                "getMetricSnapshot() reads framework counters in tests without a MeterProvider",
                "metrics.setGlobalMeterProvider() wires counters into OTLP for production"
              ]
            },
            {
              "name": "tool-custom-spans",
              "description": "Create child spans, events, and attributes inside a tool's execute method using this.telemetry.",
              "level": "basic",
              "tags": ["telemetry", "tool", "spans", "events", "attributes"],
              "features": [
                "`import type {} from '@frontmcp/observability'` brings in the `this.telemetry` type (a module augmentation of `ExecutionContextBase`)",
                "this.telemetry.withSpan() creates auto-managed child spans",
                "this.telemetry.addEvent() adds events to the parent tool span",
                "this.telemetry.setAttributes() adds metadata to the parent tool span",
                "Child spans inherit the trace ID automatically"
              ]
            }
          ]
        },
        {
          "name": "testing-observability",
          "description": "Test that your spans, log entries, and telemetry instrumentation work correctly.",
          "examples": [
            {
              "name": "test-custom-spans",
              "description": "Verify that your tool creates the expected child spans with correct attributes.",
              "level": "basic",
              "tags": ["testing", "spans", "assertions", "jest", "basic"],
              "features": [
                "createTestTracer() provides isolated OTel setup (no global pollution)",
                "assertSpanExists() throws helpful errors when spans are missing",
                "assertSpanAttribute() verifies span attributes",
                "findSpansByAttribute() queries spans by attribute value"
              ]
            },
            {
              "name": "test-log-correlation",
              "description": "Verify that structured log entries include trace context fields for correlation with spans.",
              "level": "intermediate",
              "tags": ["testing", "logging", "correlation", "trace-id", "intermediate"],
              "features": [
                "CallbackSink captures log entries for test assertions",
                "StructuredLogTransport with mock context accessor provides trace fields",
                "Verifying trace_id, span_id, request_id are present",
                "Testing field redaction behavior"
              ]
            }
          ]
        },
        {
          "name": "tracing-setup",
          "description": "Enable OpenTelemetry distributed tracing for all FrontMCP flows with zero configuration.",
          "examples": [
            {
              "name": "basic-tracing",
              "description": "Enable auto-tracing and see spans printed to your terminal.",
              "level": "basic",
              "tags": ["tracing", "setup", "console", "basic"],
              "features": [
                "Zero-config tracing via observability: true",
                "Console exporter for local development",
                "Single trace ID shared across all spans in a request"
              ]
            },
            {
              "name": "production-tracing",
              "description": "Full production observability — traces to OTLP, structured logs to stdout, per-request log collection.",
              "level": "intermediate",
              "tags": ["tracing", "production", "otlp", "logging", "request-logs"],
              "features": [
                "OTLP exporter with env var configuration",
                "Structured logging with sensitive field redaction",
                "Request log collection with error alerting",
                "Full tracing across all SDK flows"
              ]
            }
          ]
        },
        {
          "name": "vendor-integrations",
          "description": "Connect FrontMCP observability to Coralogix, Datadog, Logz.io, Grafana Cloud, or any OTLP backend.",
          "examples": [
            {
              "name": "coralogix-setup",
              "description": "Send both traces and structured logs to Coralogix. Logs include trace_id so Coralogix links them to traces automatically.",
              "level": "intermediate",
              "tags": ["coralogix", "otlp", "vendor", "integration", "production"],
              "features": [
                "Traces and logs both sent to Coralogix via OTLP",
                "Automatic trace_id correlation — click a trace, see its logs",
                "Environment variable configuration for production"
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "frontmcp-production-readiness",
      "category": "production",
      "description": "Pre-production audit, hardening, and go-live checklists for FrontMCP servers. Use before shipping to verify security hardening, performance, reliability, and observability, and for target-specific production checklists: Node server (Docker, graceful shutdown, Redis session scaling), Vercel and edge (cold-start, stateless design), AWS Lambda (cold start, scaling, monitoring), Cloudflare Workers (KV, Durable Objects, runtime limits), CLI binary and local daemon (stdio and socket transport), browser SDK bundle, and embedded npm SDK. Also configuring /healthz and /readyz health and readiness endpoints with custom probes, and distributed high-availability (multi-pod heartbeat, session takeover, notification relay). Triggers: production ready, security audit, hardening, performance check, production checklist, go live, pre-launch review.",
      "path": "frontmcp-production-readiness",
      "targets": ["all"],
      "hasResources": true,
      "tags": ["production", "security", "performance", "reliability", "observability", "audit", "best-practices"],
      "bundle": ["recommended", "full"],
      "priority": 10,
      "references": [
        {
          "name": "common-checklist",
          "description": "Security, performance, reliability, and observability checks for all deployment targets",
          "examples": [
            {
              "name": "caching-and-performance",
              "description": "Shows how to configure caching with the real `CachePlugin.init(...)` API and how to size connection pools so the server does not exhaust downstream resources.",
              "level": "advanced",
              "tags": ["production", "redis", "cache", "session", "performance", "checklist"],
              "features": [
                "Using the real `CachePlugin.init({ type, defaultTTL, toolPatterns })` shape (NOT `new CachePlugin({ ttl: { ... } })`)",
                "Setting per-tool TTL via `@Tool({ cache: { ttl } })` metadata in seconds",
                "Using Redis-backed cache for multi-instance consistency",
                "Configuring connection pool limits and timeouts to prevent resource exhaustion",
                "The pool is created in the constructor and drained in `onShutdown()`, which framework shutdown runs"
              ]
            },
            {
              "name": "observability-setup",
              "description": "Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production.",
              "level": "intermediate",
              "tags": ["production", "observability", "checklist", "setup"],
              "features": [
                "Using `this.mark()` to annotate execution phases for tracing",
                "Using `this.fail()` for business-logic errors without exposing internals",
                "Setting timeouts on all external calls via `AbortSignal.timeout()`",
                "Implementing health check providers that verify downstream dependencies"
              ]
            },
            {
              "name": "security-hardening",
              "description": "Shows how to configure authentication, CORS, input validation, rate limiting, audit logging, and observability counters for a production FrontMCP server.",
              "level": "basic",
              "tags": ["production", "redis", "session", "security", "throttle", "audit", "observability", "checklist"],
              "features": [
                "Restricting CORS origins to known domains instead of using `'*'`",
                "Configuring rate limiting via the `throttle` option",
                "Using Redis for session storage in multi-instance deployments",
                "Defining both `inputSchema` and `outputSchema` on tools to prevent data leaks",
                "Enabling the tamper-evident skill audit log with RS256 + a persistent store and a CI verifier",
                "Wiring an OTel MeterProvider so framework counters (bundle pulls, signature failures, replay rejects, audit write failures and drops) are exported",
                "Keeping the auto-injected skill catalog summary inside the 16 KB initialize ceiling"
              ]
            }
          ]
        },
        {
          "name": "distributed-ha",
          "description": "Deploy FrontMCP across multiple pods with heartbeat, cross-pod request relay, session takeover, and notification relay for zero-downtime failover",
          "examples": [
            {
              "name": "ha-kubernetes-3-replicas",
              "description": "Deploy FrontMCP with 3 replicas, Redis, and automatic session failover on Kubernetes",
              "level": "intermediate",
              "tags": ["ha", "kubernetes", "redis", "distributed", "session-takeover", "heartbeat"],
              "features": [
                "Configuring @FrontMcp with Redis for distributed deployment",
                "Kubernetes Deployment YAML with 3 replicas and readiness probes",
                "Verifying heartbeat keys and session takeover via redis-cli",
                "NGINX sticky sessions for session affinity"
              ]
            }
          ]
        },
        {
          "name": "health-readiness-endpoints",
          "description": "Configure /healthz and /readyz endpoints with custom probes, runtime-aware readiness, and dependency health checks",
          "examples": [
            {
              "name": "basic-health-setup",
              "description": "Default health endpoints with Redis session store, showing /healthz and /readyz responses.",
              "level": "basic",
              "tags": ["production", "health", "readiness", "redis", "kubernetes", "docker"],
              "features": [
                "Zero-config /healthz and /readyz endpoints enabled by default",
                "Auto-discovered session-store probe via Redis persistence",
                "Catalog hash for config drift detection across instances",
                "Docker HEALTHCHECK directive using /healthz"
              ]
            },
            {
              "name": "custom-probes",
              "description": "Custom database and API probes with Kubernetes deployment configuration.",
              "level": "intermediate",
              "tags": ["production", "health", "readiness", "kubernetes", "postgres", "probes", "custom"],
              "features": [
                "Custom health probes for PostgreSQL and external API dependencies",
                "Kubernetes liveness and readiness probe configuration",
                "Production includeDetails: false to hide infrastructure topology",
                "Per-probe timeout to prevent slow dependencies from blocking readiness"
              ]
            }
          ]
        },
        {
          "name": "production-browser",
          "description": "Checklist for publishing FrontMCP as a browser-compatible SDK bundle",
          "examples": [
            {
              "name": "browser-bundle-config",
              "description": "Shows how to configure package.json for browser-compatible SDK distribution with ESM/CJS/UMD entry points, TypeScript declarations, and CDN support.",
              "level": "basic",
              "tags": ["production", "browser", "sdk", "node", "bundle", "config"],
              "features": [
                "Correct `main`, `module`, `browser`, `types`, and `exports` fields for browser distribution",
                "Using the `browser` field to point bundlers to the browser-specific build",
                "Browser-safe imports with no Node.js-only APIs",
                "CDN-friendly distribution that works via `<script type=\"module\">`"
              ]
            },
            {
              "name": "cross-platform-crypto",
              "description": "Shows how to use `@frontmcp/utils` for cross-platform crypto operations that work in both browser and Node.js, and how to avoid Node.js-only APIs.",
              "level": "intermediate",
              "tags": ["production", "browser", "node", "cross", "platform", "crypto"],
              "features": [
                "Using `@frontmcp/utils` for crypto instead of `node:crypto` (wraps Web Crypto API)",
                "Using Fetch API for HTTP calls instead of Node.js `http`/`https`",
                "Using `crypto.randomUUID()` from the Web Crypto API in browser code",
                "WebSocket connection with automatic reconnection for streaming",
                "No Node.js-only APIs (`fs`, `path`, `child_process`, `net`)"
              ]
            },
            {
              "name": "security-and-performance",
              "description": "Shows how to ensure no secrets are bundled in browser code, configure CSP headers on the server, optimize bundle size, and avoid blocking the main thread.",
              "level": "advanced",
              "tags": ["production", "auth", "browser", "security", "performance"],
              "features": [
                "No secrets (API keys, tokens) in the browser bundle -- using server-side proxy",
                "CORS configured on the server to accept specific browser origins",
                "Code splitting with dynamic `import()` for large optional features",
                "Yielding to the event loop during large data processing to avoid blocking the main thread",
                "Auth tokens obtained from the auth flow, never hardcoded"
              ]
            }
          ]
        },
        {
          "name": "production-cli-binary",
          "description": "Checklist for publishing FrontMCP as a one-shot CLI binary with stdin/stdout transport",
          "examples": [
            {
              "name": "binary-build-config",
              "description": "Shows how to configure a FrontMCP CLI binary with correct package.json `bin` field, shebang, stdio transport, and npm distribution settings.",
              "level": "basic",
              "tags": ["production", "cli", "transport", "node", "binary", "config"],
              "features": [
                "Correct `bin` field in package.json pointing to the built output",
                "Shebang line (`#!/usr/bin/env node`) for direct execution",
                "Handling `--version` and `--help` flags before server initialization",
                "Using stderr for logging (stdout is the MCP channel)",
                "`files` field excluding source, tests, and config from the published package"
              ]
            },
            {
              "name": "stdio-transport-error-handling",
              "description": "Shows how to handle stdin/stdout transport correctly, implement proper exit codes, and handle edge cases like EOF and broken pipes.",
              "level": "intermediate",
              "tags": ["production", "json-rpc", "cli", "transport", "binary", "stdio"],
              "features": [
                "Exit code conventions: 0 (success), 1 (user error), 2 (internal error)",
                "Using stderr for all logging since stdout is the MCP JSON-RPC channel",
                "Relying on the built-in shutdown when stdin ends or the parent exits, and handling a broken pipe on stdout",
                "Showing helpful error messages for unknown flags instead of stack traces",
                "Validating file paths to prevent writes to unexpected locations"
              ]
            }
          ]
        },
        {
          "name": "production-cli-daemon",
          "description": "Checklist for deploying FrontMCP as a long-running local daemon with socket transport",
          "examples": [
            {
              "name": "daemon-socket-config",
              "description": "Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage.",
              "level": "basic",
              "tags": ["production", "unix-socket", "sqlite", "cli", "transport", "performance"],
              "features": [
                "Configuring Unix socket transport for local-only communication",
                "Using SQLite with WAL mode for concurrent read/write performance",
                "Storing data in user-specific config directory (`~/.config/`)",
                "Process management with `frontmcp start/stop/restart/status/logs`",
                "System service registration for auto-start on boot"
              ]
            },
            {
              "name": "graceful-shutdown-cleanup",
              "description": "Shows how to layer daemon-specific cleanup (PID file) **on top of** the framework's built-in SIGTERM/SIGINT handler, leaving the socket file to the framework.",
              "level": "intermediate",
              "tags": ["production", "unix-socket", "cli", "database", "daemon", "graceful"],
              "features": [
                "The framework already wires SIGTERM/SIGINT — daemon cleanup attaches _additional_ listeners and does not call `process.exit()`",
                "Using `server.dispose()` (the only real method) instead of fictional `server.close()`",
                "Leaving the Unix socket file to the framework, which removes it on close and replaces a stale one at startup",
                "Cleaning up the PID file on shutdown",
                "Using `@frontmcp/utils` (`unlink`, `fileExists`, `ensureDir`) for file operations",
                "Closing the database in the provider's `onShutdown()`, which the framework's SIGTERM handler runs"
              ]
            },
            {
              "name": "security-and-permissions",
              "description": "Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.",
              "level": "advanced",
              "tags": ["production", "cli", "transport", "security", "local", "node"],
              "features": [
                "XDG Base Directory compliance for config and data storage",
                "Restrictive file permissions: config at `700`, secrets at `600`",
                "Verifying secret file permissions before reading (fail if insecure)",
                "Socket-only transport with no TCP network exposure",
                "Using `@frontmcp/utils` for file operations instead of `node:fs`"
              ]
            }
          ]
        },
        {
          "name": "production-cloudflare",
          "description": "Checklist for deploying FrontMCP to Cloudflare Workers with KV and Durable Objects",
          "examples": [
            {
              "name": "durable-objects-state",
              "description": "Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage.",
              "level": "advanced",
              "tags": ["production", "cloudflare", "cache", "throttle", "durable", "objects"],
              "features": [
                "Using Durable Objects for stateful coordination (rate limiting) in an ephemeral Workers runtime",
                "Using R2 for blob/file storage since Workers have no filesystem",
                "Combining KV (cache), R2 (files), and Durable Objects (state) in one deployment",
                "Wrangler configuration with all three binding types"
              ]
            },
            {
              "name": "workers-runtime-constraints",
              "description": "Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.",
              "level": "intermediate",
              "tags": ["production", "cloudflare", "node", "workers", "runtime", "constraints"],
              "features": [
                "Using `@frontmcp/utils` for crypto instead of `node:crypto` (Workers use V8 isolates, not Node)",
                "All I/O is async (no synchronous blocking operations allowed in Workers)",
                "No `eval()` or dynamic `Function()` (prohibited in Workers)",
                "No filesystem access (Workers have no filesystem)",
                "Using Fetch API via `this.fetch()` instead of Node.js `http`/`https`"
              ]
            },
            {
              "name": "wrangler-config",
              "description": "Checklist for verifying the `wrangler.toml` produced by `frontmcp build --target cloudflare` is production-ready. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-cloudflare.md`; this file is checklist-only.",
              "level": "basic",
              "tags": ["production", "cloudflare", "cache", "session", "wrangler", "checklist"],
              "features": [
                "Verify `main = \"dist/cloudflare/index.js\"` (the build adapter writes this — never override)",
                "Verify KV bindings for sessions and cache exist",
                "Verify staging / production environment configs are separated",
                "Verify secrets are NOT in `wrangler.toml` — use `wrangler secret put`"
              ]
            }
          ]
        },
        {
          "name": "production-lambda",
          "description": "Checklist for deploying FrontMCP to AWS Lambda with SAM, API Gateway, and DynamoDB",
          "examples": [
            {
              "name": "cold-start-connection-reuse",
              "description": "Shows how to minimize Lambda cold starts with lazy initialization on first call and the module-scope connection-reuse pattern for external services.",
              "level": "intermediate",
              "tags": ["production", "lambda", "performance", "cold", "start", "connection"],
              "features": [
                "Connection reuse pattern: caching the connection promise in module scope so it survives Lambda freeze/thaw",
                "Lazy-loading heavy dependencies (`pg`) via dynamic `import()` on first use, not at module load",
                "Not closing connections on shutdown for Lambda (they survive freeze/thaw, and a serverless handler never runs `onShutdown()`)",
                "Keeping module scope lightweight with no heavy initialization"
              ]
            },
            {
              "name": "sam-template",
              "description": "Checklist for verifying the SAM template pairs correctly with the bundle produced by `frontmcp build --target lambda`. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-lambda.md`; this file is checklist-only.",
              "level": "basic",
              "tags": ["production", "lambda", "session", "sam", "checklist"],
              "features": [
                "Verify `Handler: handler.handler` with `CodeUri: dist/lambda/` (the build emits `dist/lambda/handler.cjs`)",
                "No hand-written `src/lambda.ts` with a fictional `createLambdaHandler` import",
                "DynamoDB session table has TTL enabled for automatic cleanup",
                "IAM policies are scoped (no `*` resources / actions)",
                "API Gateway proxy route forwards to the function"
              ]
            },
            {
              "name": "scaling-and-monitoring",
              "description": "Shows how to configure concurrency limits, dead letter queues, provisioned concurrency, and CloudWatch alarms for a production Lambda deployment.",
              "level": "advanced",
              "tags": ["production", "lambda", "performance", "scaling", "monitoring"],
              "features": [
                "Reserved concurrency to prevent downstream service overload",
                "Provisioned concurrency for latency-sensitive endpoints (reduces cold starts)",
                "Dead letter queue (DLQ) for capturing failed invocations",
                "CloudWatch alarms for error rate and throttling detection",
                "Loading secrets from AWS SSM Parameter Store instead of environment variables"
              ]
            }
          ]
        },
        {
          "name": "production-node-sdk",
          "description": "Checklist for publishing FrontMCP as an embedded npm package used as a direct client SDK",
          "examples": [
            {
              "name": "basic-sdk-lifecycle",
              "description": "Shows the complete lifecycle of a FrontMCP SDK package used as an embedded client: initialization, tool invocation, and proper cleanup.",
              "level": "basic",
              "tags": ["production", "sdk", "node", "lifecycle"],
              "features": [
                "Exporting a `create()` function as the public API surface",
                "No port binding in SDK mode (embedded, not standalone server)",
                "The full lifecycle: `create()` -> `connect()` -> `callTool()` -> `close()` -> `dispose()`",
                "Proper cleanup to prevent memory and connection leaks"
              ]
            },
            {
              "name": "multi-instance-cleanup",
              "description": "Shows how multiple SDK instances can coexist without conflicts, and how a provider cleans up its timers and listeners: it starts them in `onReady()` and stops them in `onShutdown()`, which `server.dispose()` runs for the providers of that instance only.",
              "level": "advanced",
              "tags": ["production", "sdk", "node", "multi", "instance", "cleanup"],
              "features": [
                "A provider that starts its timer in `onReady()` and stops it in `onShutdown()`, so each `server.dispose()` stops only the timer of its own instance",
                "Ensuring multiple instances coexist without sharing global state",
                "Testing that dispose removes all event listeners (no leaks)",
                "Verifying one instance still works after another is disposed"
              ]
            },
            {
              "name": "package-json-config",
              "description": "Shows the correct package.json configuration for publishing a FrontMCP SDK package with CJS + ESM entry points, peer dependencies, and proper file inclusions.",
              "level": "intermediate",
              "tags": ["production", "sdk", "readme", "node", "package", "json"],
              "features": [
                "Correct `main`, `module`, `types`, and `exports` fields for CJS + ESM",
                "Using `files` to include only `dist/`, `README.md`, and `LICENSE` in the published package",
                "Declaring `zod` as a `peerDependency` for shared packages",
                "The `prepublishOnly` script ensuring build and tests pass before publishing",
                "Integration test verifying the full lifecycle with proper cleanup"
              ]
            }
          ]
        },
        {
          "name": "production-node-server",
          "description": "Checklist for deploying FrontMCP as a long-running Node.js server with Docker",
          "examples": [
            {
              "name": "docker-multi-stage",
              "description": "Shows a production-ready Dockerfile with multi-stage build, non-root user, and container health check for a FrontMCP Node.js server.",
              "level": "basic",
              "tags": ["production", "dockerfile", "docker", "security", "node", "multi"],
              "features": [
                "Multi-stage Docker build separating build dependencies from runtime",
                "Using `node:24-slim` as a minimal base image",
                "Running as non-root user (`USER node`) for security",
                "Container health check for orchestrator-aware restarts",
                "Resource limits (memory, CPU) in docker-compose"
              ]
            },
            {
              "name": "graceful-shutdown",
              "description": "Shows how to expose load-balancer drain state without overriding the FrontMCP framework's built-in SIGTERM / SIGINT graceful shutdown.",
              "level": "intermediate",
              "tags": ["production", "redis", "database", "node", "graceful", "shutdown"],
              "features": [
                "The framework already handles SIGTERM/SIGINT — never call `server.close()` (no such method) or `process.exit()` on top of it",
                "Use `server.dispose()` if you need explicit cleanup in non-server (SDK) contexts",
                "Add a _drain probe_ on `/healthz` so load balancers stop sending traffic during the framework's drain window",
                "Avoid handler conflicts: registering a second SIGTERM that calls `process.exit(0)` races the framework's own exit path"
              ]
            },
            {
              "name": "redis-session-scaling",
              "description": "Shows how to configure Redis-backed session storage, connection pooling, and stateless server design for horizontal scaling behind a load balancer.",
              "level": "advanced",
              "tags": ["production", "redis", "session", "node", "scaling"],
              "features": [
                "Configuring Redis for session storage so all instances share state",
                "Using key prefixes to namespace Redis keys and avoid collisions",
                "Setting session TTL to prevent unbounded storage growth",
                "Configuring Redis-backed job store for multi-instance job processing",
                "Validating required environment variables at startup (fail fast)"
              ]
            }
          ]
        },
        {
          "name": "production-vercel",
          "description": "Checklist for deploying FrontMCP to Vercel serverless or edge functions with Vercel KV",
          "examples": [
            {
              "name": "cold-start-optimization",
              "description": "Shows how to minimize cold start time by lazy-loading dependencies on first use, avoiding heavy initialization at module scope, and caching expensive operations across warm invocations.",
              "level": "intermediate",
              "tags": ["production", "vercel", "openapi", "performance", "cold", "start"],
              "features": [
                "Lazy-loading heavy SDKs via dynamic `import()` on **first use**, not at module scope or in `onBootstrap()`, which both run during the cold start",
                "Caching expensive fetches (e.g., OpenAPI specs) across warm invocations",
                "Keeping the module scope lightweight with no side effects",
                "No `top-level await` and no heavy global initialization or network calls at import time (lightweight module-scope caching of cheap synchronous values like `cachedSpec` is fine)"
              ]
            },
            {
              "name": "stateless-serverless-design",
              "description": "Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto.",
              "level": "advanced",
              "tags": ["production", "vercel", "serverless", "node", "stateless", "design"],
              "features": [
                "Using `@frontmcp/utils` (`sha256Hex`, `randomUUID`) instead of `node:crypto` for edge compatibility",
                "Fully stateless design with no in-memory state between invocations",
                "Using `this.fetch()` instead of Node.js `http`/`https` modules",
                "No file system access (serverless is ephemeral)"
              ]
            },
            {
              "name": "vercel-edge-config",
              "description": "Checklist for verifying the Vercel Build Output API v3 artifact and edge config produced by `frontmcp build --target vercel`. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-vercel.md`; this file is checklist-only.",
              "level": "basic",
              "tags": ["production", "vercel-kv", "vercel", "session", "serverless", "checklist"],
              "features": [
                "Verify `frontmcp build --target vercel` produced `.vercel/output/functions/index.func/handler.cjs`",
                "No hand-written `vercel.json` `builds`/`routes` — the build adapter uses Build Output API v3",
                "Verify Vercel KV (`provider: 'vercel-kv'`) is configured for session/cache state",
                "Verify CORS origins include `VERCEL_URL` and any custom production domain"
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "frontmcp-setup",
      "category": "setup",
      "description": "Use when starting, scaffolding, or organizing a FrontMCP project. Covers creating a new project (CLI scaffold or manual) for Node, Vercel, and other targets; standalone versus Nx-monorepo layout, naming conventions, generators, and dependency rules; composing multiple @App classes, ESM packages, and remote MCP servers into one server; provisioning session and storage backends (Redis, Vercel KV, SQLite with WAL and optional encryption); generating deployment-target-aware README files; and searching, installing, and managing the FrontMCP skill catalog for AI agents (Claude Code, Codex). Triggers: create a new project, how do I start, scaffold, project layout, folder structure, Nx monorepo, add Redis, set up SQLite or a database, compose apps, create a new app, manage skills.",
      "path": "frontmcp-setup",
      "targets": ["all"],
      "hasResources": true,
      "tags": ["router", "setup", "scaffold", "project", "nx", "redis", "sqlite", "structure", "guide"],
      "bundle": ["recommended", "minimal", "full"],
      "priority": 10,
      "references": [
        {
          "name": "frontmcp-skills-usage",
          "description": "Search, install, and manage FrontMCP skill catalog for AI agents (Claude Code, Codex)",
          "examples": [
            {
              "name": "bundle-presets-scaffolding",
              "description": "Use `--skills` flag during project creation to install a skill bundle preset.",
              "level": "intermediate",
              "tags": ["setup", "skills", "usage", "bundle", "presets", "scaffolding"],
              "features": [
                "`--skills` flag accepts `recommended`, `minimal`, `full`, or `none` presets",
                "Static installs are snapshots; re-run `install` to update to the latest catalog version",
                "Hybrid approach: install core skills statically, search the rest on demand",
                "Fewer static installs reduce token usage in AI agent context"
              ]
            },
            {
              "name": "install-and-search-skills",
              "description": "Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery.",
              "level": "basic",
              "tags": ["setup", "cli", "anthropic", "skills", "usage", "install", "bulk", "export"],
              "features": [
                "`frontmcp skills list` and `search` for discovering available skills",
                "`frontmcp skills read` for viewing skill content and references on demand",
                "`frontmcp skills install --provider claude` for static installation to `.claude/skills/`",
                "`frontmcp skills install --all` / `--category` / `--tag` for bulk install in one command",
                "`frontmcp skills export` to ship a skill to Cursor / Windsurf / Copilot rule files",
                "Installed skills are auto-loaded by Claude Code in its system prompt context"
              ]
            }
          ]
        },
        {
          "name": "multi-app-composition",
          "description": "Compose multiple @App classes, lazy apps imported on their first call, ESM packages, and remote MCP servers into a single FrontMCP gateway",
          "examples": [
            {
              "name": "lazy-apps-from-the-manifest",
              "description": "Import apps on their first call, listed from `frontmcp.manifest.json` until then.",
              "level": "intermediate",
              "tags": ["setup", "multi-app", "lazy", "manifest", "build", "startup"],
              "features": [
                "`{ name, lazy: () => import(...) }` in `apps` imports the app on its first call, once for concurrent calls",
                "`frontmcp build` writes `frontmcp.manifest.json`, which lists the app until then; the server reads it next to its entry",
                "The lazy app's `enabled` refuses its entries with `FEATURE_OFF` while it is off, and keeps it unimported once the manifest lists it",
                "Without a manifest, development imports lazy apps at startup (an app whose `enabled` source is off too; only `enabled: false` is skipped) and production refuses to start"
              ]
            },
            {
              "name": "local-apps-with-shared-tools",
              "description": "Compose multiple local `@App` classes into a server with shared tools available to all apps.",
              "level": "basic",
              "tags": ["setup", "multi-app", "local", "multi", "app", "composition"],
              "features": [
                "Multiple `@App` classes with unique `id` fields, which prefix their tools when two tools share a name (`billing:charge`)",
                "Server-level `tools` array for shared tools every app serves under their own name (`server:<name>` when an app tool has the same name)",
                "Each app is self-contained with its own tools array",
                "The `id` field on `@App` is the prefix of its tools when names collide"
              ]
            },
            {
              "name": "per-app-auth-and-isolation",
              "description": "Configure mixed authentication modes and scope isolation for different apps in a single server.",
              "level": "advanced",
              "tags": ["setup", "oauth", "auth", "multi-app", "remote", "multi"],
              "features": [
                "Per-app `auth` overrides the server-level auth (public vs remote OAuth per app)",
                "`standalone: true` fully isolates the Admin app (not visible in parent tool listing)",
                "`standalone: 'includeInParent'` gives Analytics its own scope but keeps tools visible",
                "Per-app `plugins` (BillingAuditPlugin) are scoped to that app only",
                "Server-level `plugins` (TracingPlugin, PiiRedactionPlugin) apply to all apps"
              ]
            },
            {
              "name": "remote-and-esm-apps",
              "description": "Compose local, ESM (npm package), and remote (external MCP server) apps into a single gateway.",
              "level": "intermediate",
              "tags": ["setup", "oauth", "auth", "transport", "multi-app", "remote"],
              "features": [
                "`app.esm()` loads an `@App` class from an npm package with namespace and auto-update",
                "`app.remote()` proxies tools from external MCP servers with configurable auth modes",
                "`remoteAuth` supports `'static'` (fixed credentials), `'forward'` (pass gateway user token), `'mapped'` (credentials from a per-caller mapper), and `'oauth'` (no gateway credentials)",
                "`namespace` prevents tool name collisions between apps (`crm:tool_name`, `slack:tool_name`)",
                "`transportOptions` configure timeout, retries, and SSE fallback for remote connections"
              ]
            }
          ]
        },
        {
          "name": "nx-workflow",
          "description": "Scaffold, build, test, and deploy FrontMCP projects using the @frontmcp/nx plugin in a monorepo",
          "examples": [
            {
              "name": "build-test-affected",
              "description": "Use Nx commands for efficient building, testing, and CI with affected-only execution.",
              "level": "intermediate",
              "tags": ["setup", "nx", "workflow", "affected"],
              "features": [
                "`nx build <server>` resolves the dependency graph and builds with caching",
                "`nx affected -t test` only runs tests for changed projects, saving CI time",
                "`nx run-many -t build,test,lint` parallelizes multiple targets across all projects",
                "`nx graph` visualizes project dependencies to detect circular imports"
              ]
            },
            {
              "name": "multi-server-deployment",
              "description": "Generate multiple servers in an Nx workspace, each composing different apps for different deployment targets.",
              "level": "advanced",
              "tags": ["setup", "vercel", "nx", "node", "workflow", "multi"],
              "features": [
                "Multiple servers composing different combinations of apps from the same workspace",
                "Each server has its own deployment target (`node` vs `vercel`) and storage configuration",
                "Apps are reusable across servers via Nx path aliases",
                "`nx build <server>` builds the server and all its app and lib dependencies"
              ]
            },
            {
              "name": "scaffold-and-generate",
              "description": "Initialize an Nx workspace and use generators to scaffold an app with tools, resources, and a server.",
              "level": "basic",
              "tags": ["setup", "nx", "workflow", "scaffold", "generate"],
              "features": [
                "`@frontmcp/nx:workspace` initializes the Nx monorepo structure with `apps/`, `libs/`, `servers/`",
                "All primitive generators require `--project=<app-name>` to target the correct app",
                "Each generator creates an implementation file, a `.spec.ts` test file, and updates barrel exports",
                "`@frontmcp/nx:server` with `--apps` and `--deploymentTarget` creates the deployment entry point"
              ]
            }
          ]
        },
        {
          "name": "project-structure-nx",
          "description": "Canonical directory layout, generators, and dependency rules for FrontMCP Nx monorepos",
          "examples": [
            {
              "name": "nx-generator-scaffolding",
              "description": "Use `@frontmcp/nx` generators to scaffold tools, resources, and providers within an app, with automatic barrel export updates.",
              "level": "basic",
              "tags": ["setup", "nx", "structure", "generator", "scaffolding"],
              "features": [
                "All primitive generators require `--project=<app-name>` to target the correct app",
                "Each generator creates the implementation file and a `.spec.ts` test file",
                "Barrel exports (`index.ts`) are updated automatically after each generator run",
                "Files follow the `<name>.<type>.ts` naming convention"
              ]
            },
            {
              "name": "nx-workspace-with-apps",
              "description": "Scaffold an Nx monorepo with two apps and a server that composes them into a single gateway.",
              "level": "basic",
              "tags": ["setup", "nx", "structure", "workspace", "apps"],
              "features": [
                "`apps/` directory holding self-contained `@App` classes with their tools and resources",
                "`servers/` directory holding `@FrontMcp` entry points that compose apps",
                "Nx path aliases (`@my-workspace/billing`) for clean imports across the monorepo",
                "Apps are independently testable and do not import from each other"
              ]
            },
            {
              "name": "shared-library-usage",
              "description": "Create a shared library in an Nx monorepo and use it from multiple apps to avoid cross-app imports.",
              "level": "intermediate",
              "tags": ["setup", "nx", "database", "structure", "shared", "library"],
              "features": [
                "Shared libraries live in `libs/` with barrel `index.ts` exports",
                "Both apps import `DatabaseProvider` from the shared library, not from each other",
                "Nx dependency graph: `servers/ --> apps/ --> libs/` (apps never import other apps)",
                "Path aliases configured in `tsconfig.base.json` keep imports clean (`@my-workspace/shared-utils`)"
              ]
            }
          ]
        },
        {
          "name": "project-structure-standalone",
          "description": "File layout, naming conventions, and dev workflow for standalone FrontMCP projects",
          "examples": [
            {
              "name": "dev-workflow-commands",
              "description": "Run the standard development workflow for a standalone FrontMCP project: dev server, build, and tests.",
              "level": "basic",
              "tags": ["setup", "e2e", "structure", "standalone", "dev", "workflow"],
              "features": [
                "`frontmcp dev` for hot-reloading development server",
                "`frontmcp build --target <target>` for production builds targeting different runtimes",
                "Test files use `.spec.ts` extension (not `.test.ts`) per FrontMCP convention",
                "E2E tests live in the `e2e/` directory with `*.e2e.spec.ts` naming"
              ]
            },
            {
              "name": "feature-folder-organization",
              "description": "Organize a growing standalone project into domain-specific feature folders instead of flat type-based directories.",
              "level": "intermediate",
              "tags": ["setup", "structure", "standalone", "feature", "folder", "organization"],
              "features": [
                "Feature folders (`src/billing/`) grouping related tools, resources, and providers by domain",
                "Each entity still follows the `<name>.<type>.ts` naming convention inside its feature folder",
                "One class per file across tools, resources, and providers",
                "Feature folders scale better than flat `src/tools/` directories for larger projects"
              ]
            },
            {
              "name": "minimal-standalone-layout",
              "description": "Set up the canonical file structure for a standalone FrontMCP project with one app, one tool, and the required entry point.",
              "level": "basic",
              "tags": ["setup", "structure", "standalone", "minimal", "layout"],
              "features": [
                "`<name>.<type>.ts` file naming convention (`fetch-weather.tool.ts`, `my-app.app.ts`)",
                "`main.ts` with a default-exported `@FrontMcp` server class",
                "One class per file pattern",
                "`@App` grouping tools and registered in the server `apps` array"
              ]
            }
          ]
        },
        {
          "name": "readme-guide",
          "description": "Generate deployment-target-aware README.md files for FrontMCP MCP servers",
          "examples": [
            {
              "name": "node-server-readme",
              "description": "Generate a README for a FrontMCP server deployed as a Docker/Node.js service with tools and resources.",
              "level": "basic",
              "tags": ["setup", "docker", "readme", "node"],
              "features": [
                "Standard README sections: Features, Quick Start, Tools table, Resources table, Environment Variables",
                "Docker-specific deployment section with build and run commands",
                "Development commands using `frontmcp dev`, `frontmcp test`, `frontmcp inspector`",
                "Tool and resource tables generated from source code decorators"
              ]
            },
            {
              "name": "vercel-deployment-readme",
              "description": "Generate a README for a FrontMCP server deployed to Vercel with Vercel KV storage.",
              "level": "intermediate",
              "tags": ["setup", "vercel-kv", "vercel", "readme", "deployment"],
              "features": [
                "Vercel-specific deployment instructions with `frontmcp build --target vercel` and `vercel deploy`",
                "Vercel KV environment variables (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) noted as auto-injected",
                "`vercel.json` configuration reference for route setup",
                "Consistent README structure adapted to the Vercel deployment target"
              ]
            }
          ]
        },
        {
          "name": "setup-project",
          "description": "Scaffold a new FrontMCP project with CLI or manual setup, decorators, apps, and deployment config",
          "examples": [
            {
              "name": "basic-node-server",
              "description": "Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js with HTTP transport.",
              "level": "basic",
              "tags": ["setup", "transport", "node"],
              "features": [
                "Minimal `@FrontMcp` server with `info` and `apps` fields",
                "`@App` decorator grouping a single tool",
                "`@Tool` decorator with Zod input/output schemas extending `ToolContext`",
                "Required tsconfig flags: `experimentalDecorators` and `emitDecoratorMetadata`",
                "`reflect-metadata` imported as the first line of the entry point"
              ]
            },
            {
              "name": "cli-scaffold-with-flags",
              "description": "Use the `frontmcp create` CLI to scaffold a complete project non-interactively with explicit flags for deployment target, Redis, and package manager.",
              "level": "basic",
              "tags": ["setup", "redis", "cli", "nx", "scaffold", "flags"],
              "features": [
                "Non-interactive scaffolding with `--yes` to accept all defaults",
                "Explicit `--target`, `--redis`, `--pm`, `--skills`, and `--cicd` flags",
                "Nx monorepo scaffolding with `--nx`",
                "Verifying the server responds to MCP `initialize` requests after startup"
              ]
            },
            {
              "name": "vercel-serverless-server",
              "description": "Configure a FrontMCP server for Vercel deployment with Vercel KV storage and modern transport protocol.",
              "level": "intermediate",
              "tags": ["setup", "vercel-kv", "redis", "vercel", "session", "transport"],
              "features": [
                "`transport: { protocol: 'modern' }` for streamable HTTP with strict sessions on Vercel",
                "`redis: { provider: 'vercel-kv' }` for managed Redis-compatible storage without external provisioning",
                "Building with `frontmcp build --target vercel` for serverless output",
                "Vercel KV credentials are auto-injected via environment variables"
              ]
            }
          ]
        },
        {
          "name": "setup-redis",
          "description": "Provision and configure Redis or Vercel KV for session storage and distributed state",
          "examples": [
            {
              "name": "docker-redis-local-dev",
              "description": "Provision Redis with Docker Compose and connect a FrontMCP server for local session storage.",
              "level": "basic",
              "tags": ["setup", "docker-compose", "redis", "docker", "session", "local"],
              "features": [
                "Docker Compose with Redis 7 Alpine, AOF persistence, and health checks",
                "`redis` config in `@FrontMcp` with `provider: 'redis'` and environment variable fallbacks",
                "`--appendonly yes` preserves data across container restarts",
                "`keyPrefix: 'mcp:'` namespaces all session keys"
              ]
            },
            {
              "name": "hybrid-vercel-kv-with-pubsub",
              "description": "Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions in distributed multi-instance deployments.",
              "level": "advanced",
              "tags": ["setup", "vercel-kv", "redis", "vercel", "session", "hybrid"],
              "features": [
                "Vercel KV handles sessions (`redis` config) while a real Redis handles pub/sub (`pubsub` config)",
                "Vercel KV does not support pub/sub operations, so a separate Redis instance is required for distributed setups",
                "Resource subscriptions across multiple server instances rely on the `pubsub` config for cross-instance notifications (single-instance servers use in-memory subscriptions automatically)",
                "The `pubsub` field accepts `provider: 'redis'` only (no Vercel KV support)"
              ]
            },
            {
              "name": "vercel-kv-serverless",
              "description": "Configure a FrontMCP server with Vercel KV as the session store for serverless deployment.",
              "level": "intermediate",
              "tags": ["setup", "vercel-kv", "redis", "vercel", "session", "transport"],
              "features": [
                "`provider: 'vercel-kv'` for managed Redis-compatible storage on Vercel",
                "`transport: { protocol: 'modern' }` required for Streamable HTTP on serverless",
                "Vercel auto-injects `KV_REST_API_URL` and `KV_REST_API_TOKEN` in production",
                "Explicit `url` and `token` fields for local testing outside Vercel"
              ]
            }
          ]
        },
        {
          "name": "setup-sqlite",
          "description": "Configure SQLite for local deployments, shared by the processes on one machine, with WAL mode and optional encryption",
          "examples": [
            {
              "name": "basic-sqlite-setup",
              "description": "Configure a FrontMCP server with SQLite for local session storage with WAL mode enabled.",
              "level": "basic",
              "tags": ["setup", "sqlite", "session", "database", "local"],
              "features": [
                "`@frontmcp/storage-sqlite` and `better-sqlite3` as required dependencies",
                "`sqlite` config in `@FrontMcp` with `path` and `walMode`",
                "WAL mode creates three files (`.sqlite`, `.sqlite-wal`, `.sqlite-shm`)",
                "Tilde-prefixed paths for stable storage across working directories"
              ]
            },
            {
              "name": "encrypted-sqlite-storage",
              "description": "Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLite.",
              "level": "intermediate",
              "tags": ["setup", "sqlite", "session", "database", "encrypted", "storage"],
              "features": [
                "`encryption.secret` enables AES-256-GCM encryption with HKDF-SHA256 key derivation",
                "The secret must be at least 32 characters and sourced from environment variables",
                "The same secret must be used across server restarts to decrypt existing data",
                "Never hardcode the encryption secret in source code"
              ]
            },
            {
              "name": "multi-process-storage",
              "description": "Share counters and a lock between several local processes through one SQLite file.",
              "level": "intermediate",
              "tags": ["setup", "sqlite", "storage", "multi-process", "lock", "local"],
              "features": [
                "`sqliteStorageProvider()` registers a SQLite-backed storage that tools read with `this.get(SqliteStorageToken)`",
                "`incr` stays exact and an `ifNotExists` lock has one holder across processes on the same file",
                "`createStorage({ type: 'sqlite' })` gives scripts and `throttle.storage` the same file",
                "Waiting for another process's lock does not block the event loop"
              ]
            },
            {
              "name": "unix-socket-daemon",
              "description": "Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for persistent storage.",
              "level": "advanced",
              "tags": ["setup", "unix-socket", "sqlite", "session", "transport", "database"],
              "features": [
                "`http.unixSocket` for unix socket transport instead of TCP port",
                "`transport: { protocol: 'modern' }` for Streamable HTTP with strict sessions",
                "`ttlCleanupIntervalMs: 15000` for more aggressive cleanup on high-throughput daemons",
                "Absolute path for the database file in system-level storage (`/var/lib/`)"
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "frontmcp-testing",
      "category": "testing",
      "description": "Use for anything about testing FrontMCP servers: writing or running unit, integration, and E2E tests and reaching the 95%+ coverage bar. Covers Jest setup and coverage gating; unit-testing a ToolContext execute() with mock context, inputs, and Zod schema validation; testing resources and prompts; in-memory testing via create() and connectOpenAI / connectClaude (no HTTP); full MCP-protocol E2E over HTTP with McpTestClient and TestServer; authenticated tests with TestTokenFactory, MockOAuthServer, and role-based access; browser-bundle validation with Playwright; and CLI-binary / SEA startup tests. Triggers: write tests, run tests, add e2e tests, improve coverage, test a tool / resource / prompt, mock auth, jest config. The skill for ALL testing needs.",
      "path": "frontmcp-testing",
      "targets": ["all"],
      "hasResources": true,
      "tags": ["router", "testing", "jest", "e2e", "coverage", "quality", "guide"],
      "bundle": ["recommended", "full"],
      "priority": 10,
      "references": [
        {
          "name": "replay-calls",
          "description": "Record the calls clients make with CallRecorderPlugin, then replay them against a new build with replaySession() or frontmcp test --replay",
          "examples": [
            {
              "name": "record-and-replay",
              "description": "Record calls against one version of a server with `CallRecorderPlugin`, replay them against the next with `replaySession()`, and assert on what changed.",
              "level": "intermediate",
              "tags": ["testing", "replay", "regression", "e2e"],
              "features": [
                "Turning on `CallRecorderPlugin` from an env var, so only a recording run writes the JSONL file",
                "Recording through a real `McpTestClient`, and stopping the server so the last lines are written",
                "Replaying with `replaySession()` and ignoring volatile fields with `**.` globs",
                "Asserting on `report.differences` and failing a spec with `toMatchRecording()`"
              ]
            }
          ]
        },
        {
          "name": "setup-testing",
          "description": "Configure Jest, write unit and E2E tests, and enforce 95%+ coverage for FrontMCP applications",
          "examples": [
            {
              "name": "fixture-based-e2e-test",
              "description": "Write E2E tests using the fixture API from `@frontmcp/testing` that manages server lifecycle automatically and uses MCP-specific custom matchers.",
              "level": "advanced",
              "tags": ["testing", "jest", "e2e", "setup", "fixture", "based"],
              "features": [
                "Using `test.use()` to configure server path and port for automatic lifecycle management",
                "Importing `test` and `expect` from `@frontmcp/testing` (not from Jest) to access MCP-specific matchers",
                "Custom matchers: `toContainTool()`, `toBeSuccessful()`, `toHaveTextContent()` for MCP assertions",
                "Testing all three MCP primitives (tools, resources, prompts) in a single E2E suite"
              ]
            },
            {
              "name": "jest-config-with-coverage",
              "description": "Set up a Jest configuration file that enforces 95%+ coverage across all metrics for a FrontMCP library.",
              "level": "basic",
              "tags": ["testing", "jest", "setup", "config", "coverage"],
              "features": [
                "How to configure Jest with `ts-jest` for TypeScript test files",
                "Setting 95%+ coverage thresholds required by FrontMCP standards",
                "Proper `tsconfig.spec.json` that extends the base config and includes `.spec.ts` files"
              ]
            },
            {
              "name": "unit-test-tool-resource-prompt",
              "description": "Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes.",
              "level": "intermediate",
              "tags": ["testing", "jest", "unit-test", "setup", "unit", "tool"],
              "features": [
                "Testing tool `execute()` on an instance from `Object.create(MyTool.prototype)`, with mock context methods assigned via `Object.assign`",
                "Verifying resource `execute(uri, params)` output matches the MCP `ReadResourceResult` shape",
                "Verifying prompt `execute()` output matches the MCP `GetPromptResult` shape",
                "Using Jest matchers like `expect.stringContaining` and `expect.objectContaining` for flexible assertions"
              ]
            }
          ]
        },
        {
          "name": "test-auth",
          "description": "Test authenticated MCP servers with TestTokenFactory, MockOAuthServer, and role-based access",
          "examples": [
            {
              "name": "oauth-flow-test",
              "description": "Use `MockOAuthServer` to simulate an OAuth/OIDC identity provider. The server publishes a JWKS endpoint backed by your `TestTokenFactory`, so any token created by that factory is valid against the mock IDP.",
              "level": "advanced",
              "tags": ["testing", "oauth", "auth", "flow"],
              "features": [
                "Constructing `MockOAuthServer` with a `TestTokenFactory` and starting it with `.start()`",
                "Reading server info from `mockOAuth.info.baseUrl` / `mockOAuth.info.jwksUrl` after start",
                "Issuing tokens via the same `TestTokenFactory` so the mock JWKS can verify them",
                "Cleaning up with `mockOAuth.stop()` in `afterAll`"
              ]
            },
            {
              "name": "role-based-access-test",
              "description": "Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints.",
              "level": "intermediate",
              "tags": ["testing", "auth", "role-based-access"],
              "features": [
                "Putting roles inside `claims` (the `CreateTokenOptions` shape has no top-level `roles` field)",
                "Testing that admin-only tools accept admin tokens and reject user tokens",
                "Verifying that user-level tools remain accessible to users with the correct role",
                "Each test creates and disconnects its own client for proper isolation"
              ]
            },
            {
              "name": "token-factory-test",
              "description": "Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests.",
              "level": "basic",
              "tags": ["testing", "auth", "token-factory"],
              "features": [
                "Creating a `TestTokenFactory` with issuer and audience configuration",
                "Generating test tokens with specific subjects and scopes via `createTestToken()`",
                "Building authenticated clients with `McpTestClient.create(...).withToken(token)`",
                "Using `.withPublicMode()` to suppress the anonymous token request and test unauthenticated rejection"
              ]
            }
          ]
        },
        {
          "name": "test-browser-build",
          "description": "Validate browser build output for Node.js-free bundles and test with Playwright",
          "examples": [
            {
              "name": "browser-bundle-validation",
              "description": "Verify that the browser build produces a valid bundle without Node.js-only module references.",
              "level": "basic",
              "tags": ["testing", "browser", "node", "bundle", "validation"],
              "features": [
                "Checking that the browser build output directory contains `.js` files",
                "Scanning the bundle for Node.js-only `require()` calls that would break in browsers",
                "Using dynamic `import()` to verify the bundle is loadable",
                "Targeting the `dist/browser/` directory where `frontmcp build --target browser` places output"
              ]
            },
            {
              "name": "playwright-browser-test",
              "description": "Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server.",
              "level": "advanced",
              "tags": ["testing", "browser", "playwright", "e2e"],
              "features": [
                "Using Playwright's `test` and `expect` from `@playwright/test` for browser E2E testing",
                "Waiting for DOM elements with `waitForSelector` before asserting tool list counts",
                "Filling form inputs and clicking buttons to simulate tool calls in the browser",
                "Asserting tool results via `textContent` on result elements",
                "Using the `.pw.spec.ts` file suffix required by FrontMCP naming conventions"
              ]
            }
          ]
        },
        {
          "name": "test-cli-binary",
          "description": "Test CLI binary and SEA build for startup, health check, and JS bundle import",
          "examples": [
            {
              "name": "binary-startup-test",
              "description": "Verify that a compiled CLI binary starts correctly and responds to health checks.",
              "level": "basic",
              "tags": ["testing", "cli", "binary", "startup"],
              "features": [
                "Using `execSync` to test that `--help` flag exits with code 0 and prints usage info",
                "Spawning the binary as a child process with `PORT=0` for dynamic port assignment",
                "Waiting for the \"listening\" log message before sending requests",
                "Testing the `/health` endpoint for server readiness",
                "Cleaning up the child process with `child.kill()`"
              ]
            },
            {
              "name": "js-bundle-import-test",
              "description": "Verify that the compiled JS bundle can be imported and exports the expected modules after a `frontmcp build` step.",
              "level": "intermediate",
              "tags": ["testing", "cli", "binary", "js", "bundle", "import"],
              "features": [
                "Using dynamic `import()` to test that the built JS bundle is importable",
                "Verifying the bundle has a default export (server class or factory)",
                "Testing CommonJS `require()` compatibility to ensure the bundle works in CJS environments",
                "Pointing to the `dist/` output directory where `frontmcp build` places artifacts"
              ]
            }
          ]
        },
        {
          "name": "test-direct-client",
          "description": "In-memory testing with create() and connectOpenAI/connectClaude without HTTP overhead",
          "examples": [
            {
              "name": "basic-create-test",
              "description": "Test tools in-memory without any HTTP overhead using the `create()` function from `@frontmcp/sdk`.",
              "level": "basic",
              "tags": ["testing", "sdk", "direct-client"],
              "features": [
                "Using `create()` to spin up an in-memory `DirectMcpServer` with no HTTP transport",
                "Defining tools as classes with the `@Tool` decorator and Zod schemas",
                "Calling tools directly via `server.callTool()` and checking the structured output",
                "Proper cleanup with `server.dispose()` in each test"
              ]
            },
            {
              "name": "openai-claude-format-test",
              "description": "Verify that tools are returned in the correct format for OpenAI and Claude clients using `connectOpenAI` and `connectClaude`.",
              "level": "intermediate",
              "tags": ["testing", "openai", "anthropic", "direct-client"],
              "features": [
                "Using `connectOpenAI(ServerConfig)` to get an in-memory `DirectClient` (no HTTP server is started)",
                "Verifying OpenAI tool format: `{ type: 'function', function: { name, parameters } }`",
                "Using `connectClaude(ServerConfig)` to verify Claude format: `{ name, description, input_schema }`",
                "Proper cleanup with `client.close()` after each test"
              ]
            }
          ]
        },
        {
          "name": "test-e2e-handler",
          "description": "Full MCP protocol E2E tests over HTTP with McpTestClient and TestServer",
          "examples": [
            {
              "name": "basic-e2e-test",
              "description": "Set up a basic E2E test that starts a server, connects a client, and verifies tools are listed.",
              "level": "basic",
              "tags": ["testing", "e2e", "handler"],
              "features": [
                "Using `TestServer.start({ command, port })` to spawn the server as a child process",
                "Building a client with `McpTestClient.create(...).withTransport(...).buildAndConnect()`",
                "Calling the namespaced public API: `client.tools.list()`, `client.resources.list()`, `client.prompts.get(...)`",
                "Cleaning up with `client.disconnect()` and `server.stop()`"
              ]
            },
            {
              "name": "manual-client-with-transport",
              "description": "Use `McpTestClient.create()` with explicit transport settings for fine-grained control over E2E tests.",
              "level": "advanced",
              "tags": ["testing", "session", "transport", "e2e", "handler", "manual"],
              "features": [
                "Using `TestServer.start()` with an explicit command and port for process-based server startup",
                "Building a client with `McpTestClient.create().withTransport('streamable-http').buildAndConnect()`",
                "Using `server.info.baseUrl` to wire the client to the correct address",
                "Separate `disconnect()` / `stop()` calls for client and server teardown",
                "The `toBeError()` and `toHaveTextContent()` custom matchers"
              ]
            },
            {
              "name": "tool-call-and-error-e2e",
              "description": "Test successful tool calls and verify that invalid inputs produce proper error responses over the full MCP protocol.",
              "level": "intermediate",
              "tags": ["testing", "e2e", "handler", "tool-call", "error"],
              "features": [
                "Calling tools via `client.tools.call(name, args)` and asserting success with `toBeSuccessful()`",
                "Asserting text content with the `toHaveTextContent()` matcher",
                "Asserting error results with `toBeError()` for invalid input and unknown tools",
                "Matching the tool error code: invalid input is an `isError` result with `_meta.code: \"INVALID_INPUT\"`, so `toBeError('INVALID_INPUT')` matches it (a numeric code matches JSON-RPC errors only)",
                "Testing edge cases like zero values"
              ]
            }
          ]
        },
        {
          "name": "test-tool-unit",
          "description": "Unit test a ToolContext execute method with mock context, inputs, and Zod schema validation",
          "examples": [
            {
              "name": "basic-tool-test",
              "description": "Test a simple tool's `execute()` method with mock context and verify the output.",
              "level": "basic",
              "tags": ["testing", "tool", "unit"],
              "features": [
                "Creating the tool with `Object.create(AddTool.prototype)`, since its constructor needs the request context the server builds",
                "Assigning mocks of the context methods it calls (`get`, `tryGet`, `fail`, `mark`, `fetch`, `notify`) via `Object.assign`",
                "Testing multiple input scenarios including edge cases (negatives, zero)"
              ]
            },
            {
              "name": "schema-validation-test",
              "description": "Validate that a tool's Zod input schema rejects invalid data before `execute()` is called.",
              "level": "intermediate",
              "tags": ["testing", "tool", "unit", "schema", "validation"],
              "features": [
                "Testing the Zod input schema separately from the `execute()` method",
                "Using `safeParse()` to check validation results without throwing",
                "Covering rejection of wrong types, missing fields, and empty input",
                "Combining schema validation with execution to test the full flow"
              ]
            },
            {
              "name": "tool-error-handling-test",
              "description": "Test that a tool throws the correct MCP error classes with proper error codes and JSON-RPC error shapes.",
              "level": "advanced",
              "tags": ["testing", "json-rpc", "tool", "unit", "error", "handling"],
              "features": [
                "Verifying specific error classes with `toBeInstanceOf` instead of just checking that something threw",
                "Asserting MCP error codes from `MCP_ERROR_CODES` constants",
                "Validating the JSON-RPC error shape returned by `toJsonRpcError()`",
                "Testing both success and failure paths in the same suite"
              ]
            }
          ]
        }
      ]
    }
  ]
}