@frontmcp/skills 1.2.1 → 1.4.0

package/catalog/create-tool/examples/02-basic-function-tool.md

@@ -0,0 +1,80 @@
+---
+name: 02-basic-function-tool
+level: basic
+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.'
+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)"
+---
+
+# Basic Function Tool
+
+Function-style `tool({...})(handler)` for a tiny pure-input tool — pick this over a class only when the tool needs no DI / lifecycle / UI.
+
+For trivial pure-input tools, the `tool()` function builder is a one-liner alternative to `@Tool` + class.
+
+## Code
+
+```typescript
+// src/apps/main/tools/add-numbers.tool.ts
+import { tool, z } from '@frontmcp/sdk';
+
+export const AddNumbers = tool({
+  name: 'add_numbers',
+  description: 'Add two numbers',
+  inputSchema: {
+    a: z.number().describe('First number'),
+    b: z.number().describe('Second number'),
+  },
+  outputSchema: 'number',
+})((input) => input.a + input.b);
+```
+
+```typescript
+// src/apps/main/tools/add-numbers.e2e.spec.ts
+import { expect, test } from '@frontmcp/testing';
+
+test.use({
+  server: './src/main.ts',
+  port: 3004,
+});
+
+test('adds two numbers', async ({ mcp }) => {
+  // mcp.tools.call returns a ToolResultWrapper around the MCP CallToolResult.
+  // A primitive `outputSchema: 'number'` surfaces as text content "5" and
+  // structuredContent `{ content: 5 }` — assert on the MCP result, not on `5` directly.
+  const result = await mcp.tools.call('add_numbers', { a: 2, b: 3 });
+
+  expect(result).toBeSuccessful();
+  expect(result).toHaveTextContent('5');
+  expect(result.json()).toEqual({ content: 5 });
+});
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+import { AddNumbers } from './tools/add-numbers.tool';
+
+@App({ name: 'main', tools: [AddNumbers] })
+export class MainApp {}
+```
+
+## What This Demonstrates
+
+- 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)
+
+## When to pick function-style over class
+
+- ✅ Pure math / formatting / parsing — no DI, no lifecycle, no UI widget
+- ❌ Anything that needs `this.get(TOKEN)` — promote to class
+- ❌ Anything with a `ui:` widget — class + folder-per-tool layout is cleaner
+
+See [`references/function-style-builder.md`](../references/function-style-builder.md) for the full `tool()` surface, including `(input, ctx)` handler form with `ctx.get` / `ctx.fetch` (to fail, `throw new PublicMcpError(...)` — `ctx.fail` is class-tool only).

package/catalog/create-tool/examples/03-tool-with-zod-shape-output.md

@@ -0,0 +1,78 @@
+---
+name: 03-tool-with-zod-shape-output
+level: basic
+description: Tool returning structured JSON declared via a Zod raw shape outputSchema — the recommended pattern for any complex output.
+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"
+---
+
+# Tool With Zod Shape Output
+
+Tool returning structured JSON declared via a Zod raw shape outputSchema — the recommended pattern for any complex output.
+
+For structured JSON, declare `outputSchema` as a Zod raw shape — the same form as `inputSchema`. The shape is the runtime contract AND the source of the TypeScript output type.
+
+## Code
+
+```typescript
+// src/apps/main/tools/order-summary.schema.ts
+import { ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+export const inputSchema = {
+  orderId: z.string().uuid().describe('Order UUID'),
+};
+
+export const outputSchema = {
+  orderId: z.string(),
+  customer: z.string(),
+  totalUsd: z.number(),
+  itemCount: z.number().int().min(0),
+  pendingCount: z.number().int().min(0),
+  status: z.enum(['pending', 'paid', 'shipped', 'delivered', 'cancelled']),
+};
+
+export type OrderSummaryInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type OrderSummaryOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+```
+
+```typescript
+// src/apps/main/tools/order-summary.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+
+import { ORDERS_REPO } from '../tokens';
+import { inputSchema, outputSchema, type OrderSummaryInput, type OrderSummaryOutput } from './order-summary.schema';
+
+@Tool({
+  name: 'order_summary',
+  description: 'Summary for an order — totals, item counts, and status.',
+  inputSchema,
+  outputSchema,
+})
+export class OrderSummaryTool extends ToolContext {
+  async execute(input: OrderSummaryInput): Promise<OrderSummaryOutput> {
+    const repo = this.get(ORDERS_REPO);
+    const order = await repo.findById(input.orderId);
+    // `order` may carry { …, internalNotes, paymentProviderRef, debug }
+    // — none of those are in outputSchema, so they're stripped before returning.
+    return {
+      orderId: order.id,
+      customer: order.customerName,
+      totalUsd: order.totalCents / 100,
+      itemCount: order.items.length,
+      pendingCount: order.items.filter((i) => i.status === 'pending').length,
+      status: order.status,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- 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

package/catalog/create-tool/examples/04-tool-with-zod-schema-output.md

@@ -0,0 +1,97 @@
+---
+name: 04-tool-with-zod-schema-output
+level: advanced
+description: 'Tool returning a discriminated union via a full `z.discriminatedUnion(...)` outputSchema — for outputs that branch on a kind field.'
+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'
+---
+
+# Tool With Zod Schema Output
+
+Tool returning a discriminated union via a full `z.discriminatedUnion(...)` outputSchema — for outputs that branch on a kind field.
+
+When the output has more than one shape (e.g. `user` vs `group`), use a full Zod schema instead of a raw shape. `z.discriminatedUnion` is the cleanest pattern.
+
+## Code
+
+```typescript
+// src/apps/main/tools/resolve-principal.schema.ts
+import { ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+export const inputSchema = {
+  handle: z.string().describe('A user or group handle, e.g. `@ada` or `#engineering`'),
+};
+
+// Full Zod schema — discriminated union on `kind`.
+export const outputSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('user'),
+    id: z.string(),
+    name: z.string(),
+    email: z.string().email(),
+  }),
+  z.object({
+    kind: z.literal('group'),
+    id: z.string(),
+    name: z.string(),
+    memberCount: z.number().int().min(0),
+  }),
+]);
+
+export type ResolvePrincipalInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type ResolvePrincipalOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+```
+
+```typescript
+// src/apps/main/tools/resolve-principal.tool.ts
+import { PublicMcpError, Tool, ToolContext } from '@frontmcp/sdk';
+
+import { PRINCIPALS } from '../tokens';
+import {
+  inputSchema,
+  outputSchema,
+  type ResolvePrincipalInput,
+  type ResolvePrincipalOutput,
+} from './resolve-principal.schema';
+
+@Tool({
+  name: 'resolve_principal',
+  description: 'Resolve a handle to a user or group',
+  inputSchema,
+  outputSchema,
+})
+export class ResolvePrincipalTool extends ToolContext {
+  async execute(input: ResolvePrincipalInput): Promise<ResolvePrincipalOutput> {
+    const svc = this.get(PRINCIPALS);
+    if (input.handle.startsWith('@')) {
+      const user = await svc.findUserByHandle(input.handle.slice(1));
+      return { kind: 'user' as const, id: user.id, name: user.name, email: user.email };
+    }
+    if (input.handle.startsWith('#')) {
+      const group = await svc.findGroupBySlug(input.handle.slice(1));
+      return { kind: 'group' as const, id: group.id, name: group.name, memberCount: group.members.length };
+    }
+    this.fail(new PublicMcpError(`Unknown handle prefix: ${input.handle[0]}`));
+  }
+}
+```
+
+## What This Demonstrates
+
+- 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
+
+## When to use a full Zod schema for output
+
+| Use raw shape                            | Use full Zod schema                                      |
+| ---------------------------------------- | -------------------------------------------------------- |
+| Single object with a fixed set of fields | Union of multiple shapes (`z.discriminatedUnion`)        |
+| All fields known statically              | Arrays of complex objects (`z.array(z.object(...))`)     |
+| No transforms / refinements needed       | Need `z.transform(...)`, `z.refine(...)`, `z.brand(...)` |
+| Default and recommended                  | When the raw shape can't express the contract            |

package/catalog/create-tool/examples/05-tool-with-primitive-output.md

@@ -0,0 +1,93 @@
+---
+name: 05-tool-with-primitive-output
+level: basic
+description: "Tool returning a single primitive — `outputSchema: 'string' | 'number' | 'boolean' | 'date'` for single-value outputs."
+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'
+---
+
+# Tool With Primitive Output
+
+Tool returning a single primitive — `outputSchema: 'string' | 'number' | 'boolean' | 'date'` for single-value outputs.
+
+For tools that return a single value, declare `outputSchema` as a primitive literal. The framework wraps the bare return in the right MCP content block.
+
+## Code
+
+```typescript
+// src/apps/main/tools/primitives.tool.ts
+import { Tool, tool, ToolContext, z } from '@frontmcp/sdk';
+
+// 1. string output
+@Tool({
+  name: 'fmt_currency',
+  description: 'Format a number as USD',
+  inputSchema: { amount: z.number() },
+  outputSchema: 'string',
+})
+export class FmtCurrencyTool extends ToolContext {
+  execute(input: { amount: number }): string {
+    return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(input.amount);
+  }
+}
+
+// 2. number output (function-style)
+export const Add = tool({
+  name: 'add',
+  description: 'Add two numbers',
+  inputSchema: { a: z.number(), b: z.number() },
+  outputSchema: 'number',
+})((input) => input.a + input.b);
+
+// 3. boolean output
+@Tool({
+  name: 'is_palindrome',
+  description: 'Check whether a string reads the same forward and backward',
+  inputSchema: { text: z.string() },
+  outputSchema: 'boolean',
+})
+export class IsPalindromeTool extends ToolContext {
+  execute(input: { text: string }): boolean {
+    const t = input.text.toLowerCase().replace(/[^a-z0-9]/g, '');
+    return t === t.split('').reverse().join('');
+  }
+}
+
+// 4. date output
+@Tool({
+  name: 'now',
+  description: 'Current server time',
+  inputSchema: {},
+  outputSchema: 'date',
+})
+export class NowTool extends ToolContext {
+  execute(): Date {
+    return new Date();
+  }
+}
+```
+
+## What This Demonstrates
+
+- 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
+
+## When to pick primitive literals over a Zod shape
+
+```typescript
+// ✅ primitive literal — clean
+outputSchema: 'number',
+execute() { return 42; }
+
+// ❌ one-field Zod shape — unnecessarily nested
+outputSchema: { value: z.number() },
+execute() { return { value: 42 }; }
+```
+
+The primitive form returns the bare value; the shape form wraps it in `{ value }`. Pick primitive when you literally want one value back.

package/catalog/create-tool/examples/06-tool-with-media-output.md

@@ -0,0 +1,109 @@
+---
+name: 06-tool-with-media-output
+level: intermediate
+description: "Tool returning binary content (image / audio) or a multi-content array of `[text, image]` — for outputs that aren't plain JSON."
+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)"
+---
+
+# Tool With Media Output
+
+Tool returning binary content (image / audio) or a multi-content array of `[text, image]` — for outputs that aren't plain JSON.
+
+Media outputs use the literal forms: `'image'`, `'audio'`, `'resource'`, `'resource_link'`, or a mixed array like `['string', 'image']`.
+
+## Code
+
+```typescript
+// src/apps/main/tools/render-chart.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+// 1. Image output — base64-encoded
+@Tool({
+  name: 'render_chart',
+  description: 'Render a bar chart as PNG',
+  inputSchema: {
+    labels: z.array(z.string()),
+    values: z.array(z.number()),
+  },
+  outputSchema: 'image',
+})
+export class RenderChartTool extends ToolContext {
+  async execute(input: { labels: string[]; values: number[] }) {
+    const pngBuffer = await this.renderPng(input);
+    return {
+      type: 'image' as const, // required — without it the content block is dropped
+      data: pngBuffer.toString('base64'),
+      mimeType: 'image/png' as const,
+    };
+  }
+
+  private async renderPng(_input: { labels: string[]; values: number[] }): Promise<Buffer> {
+    return Buffer.from('iVBORw0KGgo…', 'base64'); // tiny placeholder
+  }
+}
+
+// 2. Audio output
+@Tool({
+  name: 'tts',
+  description: 'Synthesize speech from text',
+  inputSchema: { text: z.string() },
+  outputSchema: 'audio',
+})
+export class TtsTool extends ToolContext {
+  async execute(input: { text: string }) {
+    const wavBuffer = await this.synthesize(input.text);
+    return {
+      type: 'audio' as const, // required — without it the content block is dropped
+      data: wavBuffer.toString('base64'),
+      mimeType: 'audio/wav' as const,
+    };
+  }
+
+  private async synthesize(_text: string): Promise<Buffer> {
+    return Buffer.alloc(0);
+  }
+}
+
+// 3. Multi-content — text summary + annotated image
+@Tool({
+  name: 'analyze_image',
+  description: 'Detect objects and return a summary + annotated image',
+  inputSchema: { imageUrl: z.string().url() },
+  outputSchema: ['string', 'image'],
+})
+export class AnalyzeImageTool extends ToolContext {
+  async execute(input: { imageUrl: string }) {
+    const detection = await this.detect(input.imageUrl);
+    const summary = `Detected: ${detection.objects.join(', ')}.`;
+    const annotated = await this.annotate(input.imageUrl, detection);
+    return [
+      summary,
+      { type: 'image' as const, data: annotated.toString('base64'), mimeType: 'image/png' as const },
+    ] as const;
+  }
+
+  private async detect(_url: string) {
+    return { objects: ['cat', 'laptop'] };
+  }
+  private async annotate(_url: string, _d: { objects: string[] }): Promise<Buffer> {
+    return Buffer.alloc(0);
+  }
+}
+```
+
+## What This Demonstrates
+
+- 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)
+
+## Media literal vs `'resource_link'`
+
+- **`'image'` / `'audio'`** — inlines the bytes (base64) in the response. Best for small payloads (< ~1 MB). Simple — the client gets the data immediately.
+- **`'resource_link'`** — returns `{ uri: 'custom://…' }`; the client calls `resources/read` to fetch. Best for large payloads or when caching matters — see [`26-tool-with-resource-link-output`](./26-tool-with-resource-link-output.md).

package/catalog/create-tool/examples/08-tool-with-provider-injection.md

@@ -0,0 +1,110 @@
+---
+name: 08-tool-with-provider-injection
+level: intermediate
+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.'
+tags: [di, provider, this.get, error-handling]
+features:
+  - "Defining a typed DI token with `Symbol('UserService')` and `Token<UserService>`"
+  - 'Implementing a `@Provider` 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)'
+---
+
+# Tool With Provider Injection
+
+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.
+
+The canonical pattern. A service lives behind a typed token, gets registered as a `@Provider` in the same `@App`, and the tool resolves it via `this.get(TOKEN)`.
+
+## Code
+
+```typescript
+// src/apps/main/tokens.ts
+import type { Token } from '@frontmcp/di';
+
+export interface UserService {
+  findById(id: string): Promise<{ id: string; name: string; email: string } | null>;
+}
+export const USER_SERVICE: Token<UserService> = Symbol('UserService');
+```
+
+```typescript
+// src/apps/main/providers/user-service.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+import { USER_SERVICE, type UserService } from '../tokens';
+
+@Provider({ provide: USER_SERVICE })
+export class UserServiceProvider implements UserService {
+  async findById(id: string) {
+    // pretend this hits a database
+    if (id === 'u_1') return { id: 'u_1', name: 'Ada', email: 'ada@example.com' };
+    return null;
+  }
+}
+```
+
+```typescript
+// src/apps/main/tools/get-user.schema.ts
+import { ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+export const inputSchema = { id: z.string().describe('User ID') };
+export const outputSchema = { id: z.string(), name: z.string(), email: z.string().email() };
+
+export type GetUserInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type GetUserOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+```
+
+```typescript
+// src/apps/main/tools/get-user.tool.ts
+import { ResourceNotFoundError, Tool, ToolContext } from '@frontmcp/sdk';
+
+import { USER_SERVICE } from '../tokens';
+import { inputSchema, outputSchema, type GetUserInput, type GetUserOutput } from './get-user.schema';
+
+@Tool({
+  name: 'get_user',
+  description: 'Get a user by ID',
+  inputSchema,
+  outputSchema,
+})
+export class GetUserTool extends ToolContext {
+  async execute(input: GetUserInput): Promise<GetUserOutput> {
+    const users = this.get(USER_SERVICE); // throws DependencyNotFoundError if not registered
+    const user = await users.findById(input.id);
+    if (!user) {
+      this.fail(new ResourceNotFoundError(`user:${input.id}`)); // never returns
+    }
+    return user; // typed as non-null because this.fail is `never`
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+import { UserServiceProvider } from './providers/user-service.provider';
+import { GetUserTool } from './tools/get-user.tool';
+
+@App({
+  name: 'main',
+  providers: [UserServiceProvider],
+  tools: [GetUserTool],
+})
+export class MainApp {}
+```
+
+> **Testing.** Tests for tools with DI use `@frontmcp/testing`'s `TestServer` with the provider replaced for the test scope. The full pattern (including the canonical `test({ mcp })` fixture and `mcpMatchers`) lives in the dedicated `testing` skill.
+
+## What This Demonstrates
+
+- Defining a typed DI token with `Symbol('UserService')` and `Token<UserService>`
+- Implementing a `@Provider` 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)
+
+## `this.get` vs `this.tryGet`
+
+- `this.get(TOKEN)` — throws `DependencyNotFoundError` if not registered. Use when the tool genuinely requires the dep.
+- `this.tryGet(TOKEN)` — returns `undefined` if not registered. Use when the tool degrades gracefully (e.g. optional cache).

package/catalog/create-tool/examples/09-tool-with-multiple-providers.md

@@ -0,0 +1,107 @@
+---
+name: 09-tool-with-multiple-providers
+level: intermediate
+description: 'Tool composing three DI services — config (env-only), cache (optional, `tryGet`), and database (required) — the realistic shape for a production tool.'
+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)
+---
+
+# Tool With Multiple Providers
+
+Tool composing three DI services — config (env-only), cache (optional, `tryGet`), and database (required) — the realistic shape for a production tool.
+
+Production tools usually compose several services: config + cache + database is the standard trio. This example wires all three.
+
+## Code
+
+```typescript
+// src/apps/main/tokens.ts
+import type { Token } from '@frontmcp/di';
+
+export interface AppConfig {
+  weatherApiKey: string;
+  cacheTtlSeconds: number;
+}
+export interface CacheService {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, ttlSeconds: number): Promise<void>;
+}
+export interface WeatherRepo {
+  loadFromDb(city: string): Promise<{ temperatureF: number; conditions: string } | null>;
+}
+
+export const CONFIG: Token<AppConfig> = Symbol('AppConfig');
+export const CACHE: Token<CacheService> = Symbol('CacheService');
+export const WEATHER_REPO: Token<WeatherRepo> = Symbol('WeatherRepo');
+```
+
+```typescript
+// src/apps/main/tools/get-weather.tool.ts
+import { ResourceNotFoundError, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+import { CACHE, CONFIG, WEATHER_REPO } from '../tokens';
+
+const inputSchema = { city: z.string().describe('City name') };
+const outputSchema = {
+  city: z.string(),
+  temperatureF: z.number(),
+  conditions: z.string(),
+  cached: z.boolean(),
+};
+
+@Tool({
+  name: 'get_weather',
+  description: 'Current weather — cache-aside, falls back to the DB',
+  inputSchema,
+  outputSchema,
+})
+export class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string }) {
+    const config = this.get(CONFIG); // required — throws if missing
+    const cache = this.tryGet(CACHE); // optional — production has it, tests skip it
+    const repo = this.get(WEATHER_REPO); // required
+
+    const cacheKey = `weather:${input.city.toLowerCase()}`;
+
+    if (cache) {
+      const cached = await cache.get<{ temperatureF: number; conditions: string }>(cacheKey);
+      if (cached) {
+        return { city: input.city, ...cached, cached: true };
+      }
+    }
+
+    const fresh = await repo.loadFromDb(input.city);
+    if (!fresh) {
+      this.fail(new ResourceNotFoundError(`weather:${input.city}`));
+    }
+
+    if (cache) {
+      await cache.set(cacheKey, fresh, config.cacheTtlSeconds);
+    }
+
+    return { city: input.city, ...fresh, cached: false };
+  }
+}
+```
+
+## What This Demonstrates
+
+- 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)
+
+## Why `tryGet` for cache
+
+- In production: the app registers a Redis-backed cache provider. `this.tryGet(CACHE)` returns it.
+- In tests: tests skip registering the cache. `tryGet(CACHE)` returns `undefined`. The tool falls through to the DB. No special test setup required.
+
+## Why `this.get(CONFIG)` instead of `process.env.WEATHER_API_KEY`
+
+- Config goes through a typed provider — tests inject a mock `{ weatherApiKey: 'test', cacheTtlSeconds: 0 }` without touching `process.env`.
+- The shape is enforced by TypeScript; renaming a config field is a compile-time error across all callers.
+- Multiple apps on the same server can have different config provider implementations.