@frontmcp/skills 1.2.1 → 1.4.0

package/catalog/create-tool/examples/17-tool-with-concurrency-and-timeout.md

@@ -0,0 +1,101 @@
+---
+name: 17-tool-with-concurrency-and-timeout
+level: advanced
+description: 'Tool with `concurrency` + `timeout` for a real bottleneck (PDF rendering) — caps simultaneous in-flight work AND hard-caps per-call duration.'
+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'
+---
+
+# Tool With Concurrency And Timeout
+
+Tool with `concurrency` + `timeout` for a real bottleneck (PDF rendering) — caps simultaneous in-flight work AND hard-caps per-call duration.
+
+For tools that hold a real bottleneck (CPU / GPU / DB write connection), `concurrency` caps simultaneous in-flight executions. Pair with `timeout` so a stuck call can't permanently block a slot.
+
+## Code
+
+```typescript
+// src/apps/main/tools/render-pdf.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+const inputSchema = {
+  template: z.enum(['invoice', 'report', 'contract']),
+  data: z.record(z.string(), z.unknown()),
+};
+const outputSchema = { data: z.string(), mimeType: z.literal('application/pdf'), byteCount: z.number().int() };
+
+@Tool({
+  name: 'render_pdf',
+  description: 'Render a PDF from a template + data — capped at 5 concurrent renders',
+  inputSchema,
+  outputSchema,
+  rateLimit: { maxRequests: 100, windowMs: 60_000 }, // outer cap — burst protection
+  concurrency: { maxConcurrent: 5 }, // inner cap — at most 5 PDFs at once
+  timeout: { executeMs: 30_000 }, // hard per-call deadline
+  annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false },
+})
+export class RenderPdfTool extends ToolContext {
+  async execute(input: { template: 'invoice' | 'report' | 'contract'; data: Record<string, unknown> }) {
+    // Pass a per-render deadline straight into the renderer. `timeout` caps the
+    // overall execute() duration at the framework level, but it does NOT hand
+    // execute() an abort signal — so bound long child work explicitly here.
+    const pdfBuffer = await this.renderPdf(input.template, input.data, { deadlineMs: 25_000 });
+
+    return {
+      data: pdfBuffer.toString('base64'),
+      mimeType: 'application/pdf' as const,
+      byteCount: pdfBuffer.byteLength,
+    };
+  }
+
+  private async renderPdf(
+    _template: string,
+    _data: Record<string, unknown>,
+    options: { deadlineMs: number },
+  ): Promise<Buffer> {
+    // pretend this is puppeteer / wkhtmltopdf / a Rust binary that honors its own deadline
+    return new Promise((resolve, reject) => {
+      // clear the deadline only once the render actually resolves
+      const done = setTimeout(() => {
+        clearTimeout(deadline);
+        resolve(Buffer.from('%PDF-1.4 …'));
+      }, 1_000);
+      const deadline = setTimeout(() => {
+        clearTimeout(done);
+        reject(new Error('render exceeded deadline'));
+      }, options.deadlineMs);
+    });
+  }
+}
+```
+
+## What This Demonstrates
+
+- 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
+
+## How they interact
+
+Per call, in order:
+
+1. `rateLimit` → reject early if over limit (no concurrency slot consumed)
+2. `concurrency` → queue until a slot opens (queue depth is unbounded by default)
+3. `timeout` → wraps `execute()` once it actually runs; on expiry, throws `ExecutionTimeoutError` (from `@frontmcp/guard`) and aborts the wrapped execution internally
+
+The three controls are **orthogonal** — each addresses a different failure mode:
+
+| Control       | Protects against                               |
+| ------------- | ---------------------------------------------- |
+| `rateLimit`   | Quota / billing overrun                        |
+| `concurrency` | Resource exhaustion (CPU, GPU, DB connections) |
+| `timeout`     | Stuck calls holding slots forever              |
+
+## Why a child-level deadline matters
+
+`timeout` aborts the wrapped `execute()` at the framework level and throws `ExecutionTimeoutError`, but it does **not** pass an abort signal into your code — there is no `this.context.abortSignal`. So if the underlying PDF renderer has no deadline of its own, it keeps going after the timeout fires, burning CPU even though the call already errored out to the client. Give long child work its own bound (as `deadlineMs` does above) so the renderer can clean up and free the concurrency slot for the next queued call.

package/catalog/create-tool/examples/18-tool-with-progress-and-notify.md

@@ -0,0 +1,96 @@
+---
+name: 18-tool-with-progress-and-notify
+level: intermediate
+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."
+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)"
+---
+
+# Tool With Progress And Notify
+
+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.
+
+Anything that takes more than a couple of seconds should emit progress. The framework's notifications API is a single line per emission; clients render progress bars / activity logs / breadcrumb timelines from it.
+
+## Code
+
+```typescript
+// src/apps/main/tools/process-items.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+const inputSchema = {
+  items: z.array(z.string()).min(1).max(1_000),
+};
+const outputSchema = {
+  processed: z.number().int(),
+  failed: z.number().int(),
+  results: z.array(z.object({ item: z.string(), status: z.enum(['ok', 'failed']) })),
+};
+
+@Tool({
+  name: 'process_items',
+  description: 'Process a batch of items, emitting progress per item',
+  inputSchema,
+  outputSchema,
+  timeout: { executeMs: 5 * 60_000 }, // 5min ceiling
+  annotations: { idempotentHint: true, openWorldHint: false },
+})
+export class ProcessItemsTool extends ToolContext {
+  async execute(input: { items: string[] }) {
+    this.mark('validation');
+    // (Zod already validated; this.mark adds a server-side breadcrumb)
+
+    this.mark('processing');
+    const results: { item: string; status: 'ok' | 'failed' }[] = [];
+
+    for (let i = 0; i < input.items.length; i++) {
+      const item = input.items[i];
+      const ok = await this.processOne(item);
+      results.push({ item, status: ok ? 'ok' : 'failed' });
+
+      // Emit progress; cheap no-op if the request didn't send a progress token
+      await this.progress(i + 1, input.items.length, `Processed ${item}`);
+    }
+
+    const failed = results.filter((r) => r.status === 'failed').length;
+    if (failed > 0) {
+      await this.notify(`${failed}/${input.items.length} items failed`, 'warning');
+    } else {
+      await this.notify(`All ${input.items.length} items processed`, 'info');
+    }
+
+    this.mark('complete');
+    return { processed: results.length, failed, results };
+  }
+
+  private async processOne(_item: string): Promise<boolean> {
+    return Math.random() > 0.05;
+  }
+}
+```
+
+> **Testing.** Tests that intercept `this.progress` / `this.notify` events live in the dedicated `testing` skill — `@frontmcp/testing` exposes the notification stream via the `TestServer` + Playwright `test`/`expect` fixture surface.
+
+## What This Demonstrates
+
+- 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)
+
+## When to use which
+
+| Use                            | For                                                                        |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| `this.progress(n, total, msg)` | Quantitative progress — clients render a progress bar                      |
+| `this.notify(msg, level?)`     | Qualitative updates — log lines, status, warnings                          |
+| `this.mark(stage)`             | Server-side only — surfaced in logs/metrics/traces, not sent to the client |
+
+## Don't
+
+- Don't call `this.progress` in a tight loop with no `total`. Without `total`, clients can't render a meaningful bar.
+- Don't push a `this.notify` per loop iteration. That's progress. Use `this.progress` for granular updates and reserve `this.notify` for events the user genuinely needs to see (failures, warnings, milestones).

package/catalog/create-tool/examples/19-tool-with-elicitation.md

@@ -0,0 +1,102 @@
+---
+name: 19-tool-with-elicitation
+level: advanced
+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.'
+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"
+---
+
+# Tool With Elicitation
+
+Tool that pauses mid-execution to ask the user for confirmation + extra input via `this.elicit(...)` — the safe pattern for destructive or expensive actions.
+
+For destructive or expensive actions, elicitation is the safe pattern. The tool starts, pauses, asks the user "are you sure? what reason?", and finishes (or cancels) based on the answer.
+
+> Requires `elicitation: { enabled: true }` on `@FrontMcp({...})`. Without it, every `this.elicit(...)` throws `ElicitationDisabledError` at runtime.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'demo', version: '1.0.0' },
+  apps: [MainApp],
+  elicitation: { enabled: true }, // ← must be enabled for this.elicit to work
+})
+export default class DemoServer {}
+```
+
+```typescript
+// src/apps/main/tools/delete-user.tool.ts
+import { PublicMcpError, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+import { USER_SERVICE } from '../tokens';
+
+const inputSchema = { userId: z.string().describe('User ID to delete') };
+const outputSchema = z.discriminatedUnion('outcome', [
+  z.object({ outcome: z.literal('deleted'), userId: z.string(), reason: z.string().optional() }),
+  z.object({ outcome: z.literal('cancelled'), userId: z.string(), reason: z.string() }),
+]);
+
+@Tool({
+  name: 'delete_user',
+  description: 'Delete a user account — requires explicit confirmation',
+  inputSchema,
+  outputSchema,
+  annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: false },
+})
+export class DeleteUserTool extends ToolContext {
+  async execute(input: { userId: string }) {
+    const users = this.get(USER_SERVICE);
+    const user = await users.findById(input.userId);
+    if (!user) this.fail(new PublicMcpError(`No such user: ${input.userId}`));
+
+    const elicited = await this.elicit(
+      `Permanently delete ${user.email}? This cannot be undone.`,
+      z.object({
+        confirm: z.boolean().describe('Set to true to confirm'),
+        reason: z.string().optional().describe('Reason for the audit log'),
+      }),
+    );
+
+    if (elicited.status === 'cancel') {
+      return { outcome: 'cancelled' as const, userId: input.userId, reason: 'User closed prompt' };
+    }
+    if (elicited.status === 'decline' || !elicited.content?.confirm) {
+      return { outcome: 'cancelled' as const, userId: input.userId, reason: 'User declined' };
+    }
+
+    await users.delete(input.userId, { reason: elicited.content.reason });
+    return { outcome: 'deleted' as const, userId: input.userId, reason: elicited.content.reason };
+  }
+}
+```
+
+## What This Demonstrates
+
+- 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
+
+## `result.status` matrix
+
+| Status      | When                                      | Always check `result.content`?                  |
+| ----------- | ----------------------------------------- | ----------------------------------------------- |
+| `'accept'`  | User filled the form and submitted        | Yes — `result.content` is typed from the schema |
+| `'decline'` | User clicked decline / no                 | No — `content` is absent                        |
+| `'cancel'`  | User closed the prompt without responding | No — `content` is absent                        |
+
+The Zod schema you pass to `this.elicit` defines the `result.content` type when status is `'accept'`.
+
+## Early returns must match `outputSchema`
+
+The `cancelled` branch returns `{ outcome: 'cancelled', userId, reason }` which matches the `z.discriminatedUnion` outputSchema. If `outputSchema` were `z.object({ deleted: z.boolean() })`, you'd return `{ deleted: false }` instead.
+
+The framework validates the return regardless of how you got there — early elicitation returns are no exception.

package/catalog/create-tool/examples/20-tool-with-annotations.md

@@ -0,0 +1,125 @@
+---
+name: 20-tool-with-annotations
+level: basic
+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.'
+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)'
+---
+
+# Tool With Annotations
+
+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.
+
+`annotations` are advisory but the client uses them to decide whether to gate, parallelize, or retry. Four canonical combinations cover most tools.
+
+## Code
+
+```typescript
+// src/apps/main/tools/annotations.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+// 1. Read-only query — safe to call freely, parallelizable, auto-retryable
+@Tool({
+  name: 'search_users',
+  description: 'Search users by name or email',
+  inputSchema: { query: z.string(), limit: z.number().int().min(1).max(100).default(10) },
+  outputSchema: { users: z.array(z.object({ id: z.string(), email: z.string().email() })) },
+  annotations: {
+    title: 'Search users',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false, // local DB only
+  },
+})
+export class SearchUsersTool extends ToolContext {
+  async execute(_input: { query: string; limit: number }) {
+    return { users: [] };
+  }
+}
+
+// 2. Destructive admin action — confirmation gated, retryable
+@Tool({
+  name: 'delete_user',
+  description: 'Permanently delete a user account',
+  inputSchema: { userId: z.string() },
+  outputSchema: { deleted: z.boolean() },
+  annotations: {
+    title: 'Delete user',
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true, // deleting twice leaves the user deleted — safe to retry
+    openWorldHint: false,
+  },
+})
+export class DeleteUserTool extends ToolContext {
+  async execute(_input: { userId: string }) {
+    return { deleted: true };
+  }
+}
+
+// 3. Send-email — side effect, NOT idempotent, external service
+@Tool({
+  name: 'send_email',
+  description: 'Send an email via SMTP',
+  inputSchema: { to: z.string().email(), subject: z.string(), body: z.string() },
+  outputSchema: { messageId: z.string() },
+  annotations: {
+    title: 'Send email',
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false, // each call sends a NEW email — don't auto-retry blindly
+    openWorldHint: true,
+  },
+})
+export class SendEmailTool extends ToolContext {
+  async execute(_input: { to: string; subject: string; body: string }) {
+    return { messageId: `<${crypto.randomUUID()}@example.com>` };
+  }
+}
+
+// 4. External-API search — read-only but talks to the open world
+@Tool({
+  name: 'web_search',
+  description: 'Search the web via an external search API',
+  inputSchema: { query: z.string() },
+  outputSchema: { results: z.array(z.object({ title: z.string(), url: z.string().url() })) },
+  annotations: {
+    title: 'Web search',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true, // calls external service
+  },
+})
+export class WebSearchTool extends ToolContext {
+  async execute(_input: { query: string }) {
+    return { results: [] };
+  }
+}
+```
+
+## What This Demonstrates
+
+- 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)
+
+## How clients use each annotation
+
+| Annotation              | Common client behavior                                  |
+| ----------------------- | ------------------------------------------------------- |
+| `readOnlyHint: true`    | May parallelize calls; doesn't gate behind confirmation |
+| `destructiveHint: true` | Shows "are you sure?" before execution                  |
+| `idempotentHint: true`  | Auto-retries on transient failures                      |
+| `openWorldHint: false`  | Hints that the tool is offline-safe                     |
+| `title`                 | Replaces the snake_case `name` in the UI                |
+
+## When to omit
+
+If the right value isn't obvious, omit. The defaults are conservative — `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false`, `openWorldHint: true`. Clients will gate and not parallelize, which is the safe wrong choice.

package/catalog/create-tool/examples/21-tool-with-availability-constraints.md

@@ -0,0 +1,107 @@
+---
+name: 21-tool-with-availability-constraints
+level: advanced
+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.'
+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'
+---
+
+# Tool With Availability Constraints
+
+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.
+
+`availableWhen` is a hard registry-level constraint. Tools that don't match are filtered out of `tools/list` AND blocked from execution. Three real-world axes:
+
+## Code
+
+```typescript
+// src/apps/main/tools/availability.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+// 1. macOS-only — uses Apple-specific APIs
+@Tool({
+  name: 'apple_notes_search',
+  description: 'Search Apple Notes via the native bridge',
+  inputSchema: { query: z.string() },
+  outputSchema: { notes: z.array(z.object({ id: z.string(), title: z.string() })) },
+  availableWhen: { os: ['darwin'] },
+})
+export class AppleNotesSearchTool extends ToolContext {
+  async execute(_input: { query: string }) {
+    return { notes: [] };
+  }
+}
+
+// 2. Production-only AND Node runtime — uses production-specific deploy infra
+@Tool({
+  name: 'deploy_to_production',
+  description: 'Deploy a service to production',
+  inputSchema: { service: z.string(), version: z.string() },
+  outputSchema: { deploymentId: z.string() },
+  availableWhen: { runtime: ['node'], env: ['production'] },
+  annotations: { destructiveHint: true, idempotentHint: false },
+})
+export class DeployToProductionTool extends ToolContext {
+  async execute(_input: { service: string; version: string }) {
+    return { deploymentId: 'd_42' };
+  }
+}
+
+// 3. Agent / job only — internal tool, blocked from direct MCP client invocation
+@Tool({
+  name: 'rotate_secrets',
+  description: 'Rotate the application signing keys',
+  inputSchema: {},
+  outputSchema: { rotated: z.boolean() },
+  availableWhen: { surface: ['agent', 'job'] }, // not 'mcp' — chat UIs can't call this directly
+  annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: false },
+})
+export class RotateSecretsTool extends ToolContext {
+  async execute() {
+    return { rotated: true };
+  }
+}
+```
+
+## What This Demonstrates
+
+- 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
+
+## Axes (recap)
+
+| Axis         | Values                                                                                          |
+| ------------ | ----------------------------------------------------------------------------------------------- |
+| `os`         | `'darwin'`, `'linux'`, `'win32'`                                                                |
+| `runtime`    | `'node'`, `'browser'`, `'edge'`, `'bun'`, `'deno'`                                              |
+| `deployment` | `'serverless'`, `'standalone'`, `'distributed'`, `'browser'`                                    |
+| `provider`   | `'bare'`, `'docker'`, `'vercel'`, `'lambda'`, `'cloudflare'`, …                                 |
+| `target`     | `'cli'`, `'node'`, `'vercel'`, `'lambda'`, `'cloudflare'`, … (set by `frontmcp build --target`) |
+| `surface`    | `'mcp'`, `'cli'`, `'agent'`, `'job'`, `'http-trigger'` — per-call axis                          |
+| `env`        | `'production'`, `'development'`, `'test'`                                                       |
+
+Multiple axes are AND-ed. Multiple values within an axis are OR-ed.
+
+## Why declarative beats imperative checks
+
+```typescript
+// ❌ imperative — tool still appears in tools/list everywhere; users see "this won't work here" only at call time
+async execute(input) {
+  if (!this.isPlatform('darwin')) this.fail(new PublicMcpError('macOS only'));
+  // …
+}
+
+// ✅ declarative — tool is filtered out of tools/list on non-macOS servers; users never see it
+@Tool({
+  availableWhen: { os: ['darwin'] },
+  // …
+})
+```
+
+The declarative form removes the tool from `tools/list` on non-matching servers — AI clients won't propose using it. Imperative checks leak the tool's existence to users who can't use it.

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

@@ -0,0 +1,93 @@
+---
+name: 22-tool-with-ui-html-template
+level: intermediate
+description: "Tool with an inline HTML function template — `ui: { template: (ctx) => '<div>…</div>' }` — for a quick widget that doesn't need a separate `.tsx` file."
+tags: [ui, ui-widgets, html-template, escapeHtml, TemplateContext]
+features:
+  - 'Adding a `ui:` block with a function template `(ctx: TemplateContext<In, Out>) => string`'
+  - 'Annotating `ctx` explicitly to dodge the TS7006 inference gap on the union `ui.template` type'
+  - "Always escaping user-controlled output with `ctx.helpers.escapeHtml(...)` so the widget can't XSS itself"
+  - 'Reading from `ctx.output` and `ctx.helpers` — the typed runtime context the template renderer hands you'
+---
+
+# Tool With Ui Html Template
+
+Tool with an inline HTML function template — `ui: { template: (ctx) => '<div>…</div>' }` — for a quick widget that doesn't need a separate `.tsx` file.
+
+For widgets that don't need React / state / interactivity, an inline function template is the simplest form. Read `ctx.output`, escape user-controlled fields, return an HTML string.
+
+## Code
+
+```typescript
+// src/apps/main/tools/show-weather-card.tool.ts
+import { Tool, ToolContext, z, type TemplateContext } from '@frontmcp/sdk';
+
+const inputSchema = { city: z.string() };
+const outputSchema = {
+  city: z.string(),
+  temperatureF: z.number(),
+  conditions: z.string(),
+};
+type In = { city: string };
+type Out = { city: string; temperatureF: number; conditions: string };
+
+@Tool({
+  name: 'show_weather_card',
+  description: 'Show current weather as a card',
+  inputSchema,
+  outputSchema,
+  ui: {
+    widgetDescription: 'Current weather card',
+    template: (ctx: TemplateContext<In, Out>) => `
+      <div style="padding:16px;font-family:system-ui;border-radius:12px;background:#f5f7fa">
+        <h2 style="margin:0 0 8px">${ctx.helpers.escapeHtml(ctx.output.city)}</h2>
+        <p style="font-size:48px;margin:0">${ctx.output.temperatureF}°F</p>
+        <p style="margin:8px 0 0">${ctx.helpers.escapeHtml(ctx.output.conditions)}</p>
+      </div>
+    `,
+  },
+})
+export class ShowWeatherCardTool extends ToolContext {
+  async execute(input: In): Promise<Out> {
+    return { city: input.city, temperatureF: 72, conditions: 'Sunny' };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Adding a `ui:` block with a function template `(ctx: TemplateContext<In, Out>) => string`
+- Annotating `ctx` explicitly to dodge the TS7006 inference gap on the union `ui.template` type
+- Always escaping user-controlled output with `ctx.helpers.escapeHtml(...)` so the widget can't XSS itself
+- Reading from `ctx.output` and `ctx.helpers` — the typed runtime context the template renderer hands you
+
+## Why annotate `ctx` explicitly
+
+`ui.template` is a union of multiple callable shapes (`TemplateBuilderFn | string | ((props: any) => any) | FileSource`). TypeScript can't pick a single contextual type for the arrow's parameter, so `template: (ctx) => …` fails under `strict` / `noImplicitAny` with TS7006:
+
+```text
+Parameter 'ctx' implicitly has an 'any' type.
+```
+
+Two ways out:
+
+- Annotate `ctx: TemplateContext<In, Out>` (this example) — fastest fix for a small inline widget.
+- Move the widget to a `.tsx` file and use the FileSource form (`{ file: widgetPath }`) — recommended for anything non-trivial. See [`23-tool-with-ui-filesource-tsx`](./23-tool-with-ui-filesource-tsx.md).
+
+## When function templates are the right choice
+
+- Tiny widget — a card, a table row, a status badge
+- No state / interactivity
+- No external CSS / fonts / scripts beyond what `escapeHtml` can produce
+
+Move to a `.tsx` FileSource widget the moment you reach for React, useState, event handlers, or anything beyond static markup.
+
+## What `ctx.helpers` includes
+
+| Helper                         | Purpose                                                     |
+| ------------------------------ | ----------------------------------------------------------- |
+| `escapeHtml(str)`              | Escape HTML entities; returns `''` for null/undefined       |
+| `formatDate(date, format?)`    | Locale-formatted date                                       |
+| `formatCurrency(amount, ccy?)` | ISO-4217 currency formatting                                |
+| `uniqueId(prefix?)`            | Deterministic unique ID for DOM elements                    |
+| `jsonEmbed(data)`              | Safely embed JSON in a `<script>` tag (escapes `</script>`) |