@cyanheads/mcp-ts-core 0.9.6 → 0.9.8

package/skills/add-test/SKILL.md

@@ -21,10 +21,10 @@ For the full `createMockContext` API and testing patterns, read:
 
 1. **Identify the target** — which tool, resource, or service needs tests
 2. **Read the source file** — understand the handler's logic, input/output schemas, error paths, and which `ctx` features it uses
-3. **Create the test file** in the repo's existing test layout
+3. **Create the test file** in the repo's existing test layout — search for existing `*.test.ts` files to confirm whether tests are colocated with source or under a root `tests/` directory
 4. **Write test cases** covering happy path, error paths, and edge cases
 5. **Run `bun run test`** to verify
-6. **Run `bun run devcheck`** to verify types
+6. **Run `bun run devcheck`** to verify lint, types, and MCP definitions
 
 ## Determining What to Test
 
@@ -41,6 +41,7 @@ Read the handler and identify:
 | **`ctx.fail` (typed contract)** | Definitions with `errors[]` need `fail` attached to the mock ctx — `createMockContext({ errors: myTool.errors })` does it for you. Assert on `data.reason` (stable per-contract entry), not just `code`. |
 | **`format` function** | Test separately if defined — it's pure, no ctx needed. Verify it renders the IDs and fields the model needs, not just a count or title. For projection-style tools, test non-default field selections. |
 | **Sparse upstream payloads** | For third-party API integrations, build a fixture with omitted fields. Assert normalized output still validates and `format()` preserves unknown values instead of inventing facts. |
+| **Form-client payloads** | If handler has optional fields: test with empty-string inner values (form clients send `""` instead of `undefined`). Assert handler doesn't break or produce invalid output. |
 | **Auth scopes** | Not tested at handler level (framework enforces) — skip |
 
 ## Templates
@@ -134,6 +135,8 @@ describe('{{RESOURCE_EXPORT}}', () => {
   //   expect(err.code).toBe(JsonRpcErrorCode.NotFound);
   //   expect(err.data.reason).toBe('no_match');
 
+  // Include this block only when the resource definition exports a `list` function.
+  // Check the source — `list` is optional on resource definitions.
   it('lists available resources', async () => {
     const listing = await {{RESOURCE_EXPORT}}.list!();
     expect(listing.resources).toBeInstanceOf(Array);
@@ -156,14 +159,16 @@ describe('{{RESOURCE_EXPORT}}', () => {
 
 import { beforeEach, describe, expect, it } from 'vitest';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+import { StorageService } from '@cyanheads/mcp-ts-core/storage';
 import { get{{ServiceClass}}, init{{ServiceClass}} } from '@/services/{{domain}}/{{domain}}-service.js';
 
-import { createInMemoryStorage } from '@cyanheads/mcp-ts-core/testing';
+// Derive the minimal mock config from src/config/server-config.ts — read
+// the server's Zod schema to see which fields init{{ServiceClass}}() needs.
+const mockConfig = { /* fields from server config schema */ } as AppConfig;
 
 describe('{{ServiceClass}}', () => {
-  beforeEach(() => {
-    // Re-initialize with fresh config/storage for each test
-    const mockStorage = createInMemoryStorage();
+  beforeEach(async () => {
+    const mockStorage = await StorageService.create({ type: 'in-memory' });
     init{{ServiceClass}}(mockConfig, mockStorage);
   });
 
@@ -206,8 +211,42 @@ it('respects cancellation', async () => {
   setTimeout(() => controller.abort(), 50);
   const result = await {{TOOL_EXPORT}}.handler(input, ctx);
 
-  // Should have stopped early
-  expect(result.finalCount).toBeGreaterThan(0);
+  // Should have returned a partial result rather than throwing on cancellation.
+  // Assert on a field from the tool's actual output schema.
+  expect(result).toBeDefined();
+});
+```
+
+### Prompt test
+
+```typescript
+/**
+ * @fileoverview Tests for {{PROMPT_NAME}} prompt.
+ * @module tests/prompts/{{PROMPT_NAME}}.prompt.test
+ */
+
+import { describe, expect, it } from 'vitest';
+import { {{PROMPT_EXPORT}} } from '@/mcp-server/prompts/definitions/{{prompt-name}}.prompt.js';
+
+describe('{{PROMPT_EXPORT}}', () => {
+  it('generates valid messages for valid args', () => {
+    const args = {{PROMPT_EXPORT}}.args!.parse({
+      // valid args matching the Zod schema
+    });
+    const messages = {{PROMPT_EXPORT}}.generate(args);
+    expect(messages).toBeInstanceOf(Array);
+    expect(messages.length).toBeGreaterThan(0);
+    for (const msg of messages) {
+      expect(msg).toHaveProperty('role');
+      expect(msg).toHaveProperty('content');
+    }
+  });
+
+  // Include only when the prompt has no required args (args is optional or all fields optional).
+  it('generates messages with no args', () => {
+    const messages = {{PROMPT_EXPORT}}.generate({});
+    expect(messages.length).toBeGreaterThan(0);
+  });
 });
 ```
 
@@ -249,6 +288,8 @@ When scaffolding tests for an existing handler, use the Zod schemas to generate
 - [ ] `format` function tested if defined
 - [ ] `createMockContext` options match handler's ctx usage (`tenantId`, `progress`, `elicit`, `sample`)
 - [ ] Service re-initialized in `beforeEach` if handler depends on a service singleton
-- [ ] If wrapping external API: sparse-payload case tested (omitted upstream fields still validate; `format()` does not invent facts)
+- [ ] If handler has optional fields: tested with empty-string inner values (form-client simulation)
+- [ ] If wrapping external API: sparse-payload case tested — fixture omits at least one optional upstream field; output still validates and `format()` renders uncertainty honestly instead of inventing values
+- [ ] If target is a prompt: `generate()` tested with valid args and (when applicable) no args
 - [ ] `bun run test` passes
 - [ ] `bun run devcheck` passes

package/skills/add-tool/SKILL.md

@@ -11,18 +11,16 @@ metadata:
 
 ## Context
 
-Tools use the `tool()` builder from `@cyanheads/mcp-ts-core`. Each tool lives in `src/mcp-server/tools/definitions/` with a `.tool.ts` suffix and is registered into `createApp()` in `src/index.ts`. Some larger repos later add `definitions/index.ts` barrels; match the pattern already used by the project you're editing.
-
-For the full `tool()` API, `Context` interface, and error codes, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
+Tools use the `tool()` builder from `@cyanheads/mcp-ts-core`. Each tool lives in `src/mcp-server/tools/definitions/` with a `.tool.ts` suffix. The standard registration pattern uses a `definitions/index.ts` barrel that collects all tools into an `allToolDefinitions` array for `createApp()`. Fresh scaffolds from `init` start with direct imports in `src/index.ts` — the barrel is introduced as definitions grow. Match the pattern already used by the project you're editing.
 
 ## Steps
 
-1. **Ask the user** for the tool's name, purpose, and input/output shape
+1. **Gather** the tool's name, purpose, and input/output shape from the user's request — ask only if genuinely absent
 2. **Determine if long-running** — if the tool involves streaming, polling, or
    multi-step async work, it should use `task: true`
 3. **Create the file** at `src/mcp-server/tools/definitions/{{tool-name}}.tool.ts`
 4. **Register** the tool in the project's existing `createApp()` tool list (directly in `src/index.ts` for fresh scaffolds, or via a barrel if the repo already has one)
-5. **Run `bun run devcheck`** to verify
+5. **Run `bun run devcheck`** to verify — if Biome reports formatting issues, run `bun run format` to auto-fix, then re-run devcheck
 6. **Smoke-test** with `bun run rebuild && bun run start:stdio` (or `start:http`)
 
 ## Naming
@@ -136,6 +134,7 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
   output: z.object({ /* ... */ }),
 
   async handler(input, ctx) {
+    // ctx.progress is guaranteed non-null when task: true — the ! assertion is safe here.
     await ctx.progress!.setTotal(totalSteps);
     for (const step of steps) {
       if (ctx.signal.aborted) break;
@@ -528,18 +527,26 @@ Large payloads burn the agent's context window. Default to curated summaries; of
 ## Checklist
 
 - [ ] File created at `src/mcp-server/tools/definitions/{{tool-name}}.tool.ts`
+- [ ] Tool name passed to `tool()` uses snake_case
+- [ ] `title` field set
+- [ ] `annotations` set correctly — `readOnlyHint: false` for write tools, `destructiveHint: true` for delete/overwrite tools
 - [ ] All Zod schema fields have `.describe()` annotations
 - [ ] Numeric `output` fields carry units in the field name (`sizeInBytes`, `durationInMs`, `priceInCents`, `latencyInMs`) — `.describe()` may be summarized away or truncated, but the field name persists into the JSON the agent reads. Exempt: dimensionless counts (`totalCount`, `itemCount`), indices (`index`, `position`)
 - [ ] Schemas use only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`)
 - [ ] JSDoc `@fileoverview` and `@module` header present
 - [ ] Optional nested objects guarded for empty inner values from form-based clients (check `?.field` truthiness, not just object presence)
-- [ ] `handler(input, ctx)` is pure — throws on failure, no try/catch
+- [ ] No `console` calls — use `ctx.log` for handler logging
+- [ ] `handler(input, ctx)` is pure — throws on failure, no try/catch (exception: batch tools with per-item isolation use try/catch inside the loop — that's intentional, don't remove it)
 - [ ] `format()` renders every field in the output schema — enforced at lint time via sentinel injection, startup fails with `format-parity` errors otherwise. Different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data. Primary fix: render the missing field in `format()` (use `z.discriminatedUnion` for list/detail variants). Escape hatch: if the output schema was over-typed for a genuinely dynamic upstream API, relax it (`z.object({}).passthrough()`) rather than maintaining aspirational typing
 - [ ] If wrapping external API: output schema and `format()` preserve uncertainty from sparse upstream payloads instead of inventing concrete values
 - [ ] `auth` scopes declared if the tool needs authorization
 - [ ] `errors: [...]` contract declared for the tool's domain-specific failure modes — or block deleted if no domain failures apply (baseline codes bubble freely)
 - [ ] Error contract declared inline on this tool — not imported from a shared module, even when other tools have near-identical entries
 - [ ] `task: true` added if the tool is long-running
+- [ ] If `task: true`: handler checks `ctx.signal.aborted` in its loop for cancellation support
+- [ ] If tool returns unbounded arrays: pagination with total count, or `spillover()` / DataCanvas for tabular working sets
+- [ ] If tool is feature-gated: evaluated whether `disabledTool()` wrapper is appropriate (present in manifest but uncallable)
 - [ ] Registered in the project's existing `createApp()` tool list (directly or via barrel)
+- [ ] Test file created via `add-test` skill, or handler tested directly with `createMockContext()`
 - [ ] `bun run devcheck` passes
 - [ ] Smoke-tested with `bun run rebuild && bun run start:stdio` (or `start:http`)

package/skills/api-auth/SKILL.md

@@ -141,7 +141,8 @@ A `WARNING`-level log is emitted at startup whenever the flag is active so opera
 | `GET /healthz` | No |
 | `GET /mcp` | No |
 | `POST /mcp` | Yes (when auth enabled) |
-| `OPTIONS /mcp` | Yes (when auth enabled) |
+| `DELETE /mcp` | Yes (when auth enabled) — session termination |
+| `OPTIONS /mcp` | No (handled by CORS middleware before auth) |
 
 **CORS:** Set `MCP_ALLOWED_ORIGINS` to a comma-separated list of allowed origins, or `*` for open access.
 
@@ -196,7 +197,7 @@ interface AuthContext {
   clientId: string;        // Required — 'cid' or 'client_id' JWT claim
   scopes: string[];        // Required — union of 'scp', 'scope', and 'mcp_tool_scopes' claims
   sub: string;             // Required — 'sub' claim; falls back to clientId when absent
-  token: string;           // Required — raw JWT or OAuth bearer token string
+  token?: string;          // Optional — raw JWT or OAuth bearer token string (present when transport provides it)
   tenantId?: string;       // Optional — 'tid' claim; present only for multi-tenant tokens
 }
 ```

package/skills/api-canvas/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 `DataCanvas` is a primitive for **storage stashes, canvas computes**. The existing `IStorageProvider` is a key/value abstraction — it can stash blobs but exposes no analytical surface. `DataCanvas` is the analytical surface: register tabular data from upstream APIs, run SQL across multiple registered tables, and export results as CSV/Parquet/JSON.
 
-**Tier 3** — `@duckdb/node-api` is an optional peer dependency. Servers that don't enable canvas pay zero install cost. Lazy-loaded on first use.
+**Tier 3** — `@duckdb/node-api` is an optional peer dependency (`bun add @duckdb/node-api`). Servers that don't enable canvas pay zero install cost. Lazy-loaded on first use.
 
 **Disabled by default.** Set `CANVAS_PROVIDER_TYPE=duckdb` to enable. Otherwise `core.canvas` is `undefined`.
 
@@ -27,7 +27,27 @@ metadata:
 import type { DataCanvas, CanvasInstance, ColumnSchema } from '@cyanheads/mcp-ts-core/canvas';
 ```
 
-The framework wires the optional service onto `CoreServices`:
+The framework wires the optional service onto `CoreServices`, accessible in the `setup()` callback — **not on `Context`**. Handlers access canvas via a module-level accessor:
+
+```ts
+// src/services/canvas-accessor.ts
+import type { DataCanvas } from '@cyanheads/mcp-ts-core/canvas';
+
+let _canvas: DataCanvas | undefined;
+export const setCanvas = (c: DataCanvas | undefined) => { _canvas = c; };
+export const getCanvas = () => _canvas;
+```
+
+```ts
+// src/index.ts — wire in setup()
+import { setCanvas } from './services/canvas-accessor.js';
+
+await createApp({
+  setup(core) {
+    setCanvas(core.canvas);
+  },
+});
+```
 
 ```ts
 interface CoreServices {
@@ -74,7 +94,11 @@ The sweeper runs as an `unref`'d `setInterval` — does not keep the event loop
 Resolves an existing canvas or creates a new one. Returns a {@link CanvasInstance} bound to `(canvasId, tenantId)`. Subsequent operations don't repeat them.
 
 ```ts
-const instance = await ctx.core.canvas!.acquire(input.canvas_id, ctx);
+import { getCanvas } from '@/services/canvas-accessor.js';
+
+const canvas = getCanvas();
+if (!canvas) throw new Error('DataCanvas is not enabled. Set CANVAS_PROVIDER_TYPE=duckdb.');
+const instance = await canvas.acquire(input.canvas_id, ctx);
 // instance.canvasId — surface to the agent
 // instance.isNew    — true on first call
 // instance.expiresAt — ISO 8601 after sliding extension
@@ -116,7 +140,7 @@ const joined = await instance.query(`
 // joined.tableName === 'g_with_obs'; joined.rows.length === 10; joined.rowCount === <full count>
 ```
 
-`registerAs` rejects with `Conflict` if the target name already exists — drop it first.
+`registerAs` rejects with `ValidationError` (`data.reason: 'register_as_clash'`) if the target name already exists — drop it first.
 
 **Read-only enforcement** (four layers):
 1. Text-level deny-list — pre-parse scan for file/HTTP-reading table functions (`read_csv*`, `read_json*`, `read_parquet*`, `read_text`, `read_blob`, `glob`, `iceberg_scan`, `delta_scan`, `postgres_scan`, `mysql_scan`, `sqlite_scan`, plus pre-staged spatial ones).
@@ -225,6 +249,7 @@ If your tool surfaces row data via `structuredContent`, the JSON-safe shape flow
 
 ```ts
 import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getCanvas } from '@/services/canvas-accessor.js';
 
 export const fetchAndStage = tool('fetch_and_stage_germplasm', {
   description: 'Fetch germplasm matching a query and stage it on a DataCanvas for follow-up SQL.',
@@ -245,7 +270,7 @@ export const fetchAndStage = tool('fetch_and_stage_germplasm', {
     expires_at: z.string().describe('ISO 8601 expiry after sliding 24h window'),
   }),
   async handler(input, ctx) {
-    const canvas = ctx.core.canvas;
+    const canvas = getCanvas();
     if (!canvas) {
       throw new Error('DataCanvas is not enabled. Set CANVAS_PROVIDER_TYPE=duckdb.');
     }
@@ -334,7 +359,7 @@ When the preview budget is small (single-digit rows) and the sniff window matter
 
 ### Out of scope
 
-- **Provenance metadata** (source URI, original query). Caller stores externally — see #112 option 3.
+- **Provenance metadata** (source URI, original query). Caller stores externally via `ctx.state` or tool output — canvas tables carry data only, not lineage.
 - **Pagination-flavored builder.** A `paginate(fetchPage) → AsyncIterable<Row>` adapter is deferred until a second non-paginated consumer surfaces.
 - **Token-accurate budget.** `previewTokens` (tokenizer-driven) is a future option; characters cover the common case.
 - **`caps.maxBytes`.** Row caps cover the common case without re-doing serialization the canvas appender skips.
@@ -363,6 +388,18 @@ When the preview budget is small (single-digit rows) and the sniff window matter
 
 ---
 
+## Checklist
+
+- [ ] `@duckdb/node-api` installed as a peer dependency (`bun add @duckdb/node-api`)
+- [ ] `CANVAS_PROVIDER_TYPE=duckdb` set in `.env`
+- [ ] Canvas accessor module created (`src/services/canvas-accessor.ts` or equivalent)
+- [ ] Accessor wired in `setup()` callback via `setCanvas(core.canvas)`
+- [ ] Handler guards for canvas availability (`if (!canvas) throw ...`)
+- [ ] `canvas_id` accepted as optional input, returned in output
+- [ ] SQL queries are read-only (enforced by the four-layer gate, but don't attempt writes)
+- [ ] Testing: mock the module-level `getCanvas()` accessor with `vi.spyOn` or a test setup that calls `setCanvas(mockCanvas)`
+- [ ] `bun run devcheck` passes
+
 ## Related skills
 
 - `add-tool` — scaffold a new MCP tool definition (use the canvas template above)

package/skills/api-config/SKILL.md

@@ -59,6 +59,10 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod from environment variable
 | `MCP_RESPONSE_VERBOSITY` | `mcpResponseVerbosity` | `standard` | `minimal` \| `standard` \| `full` |
 | `MCP_ALLOWED_ORIGINS` | `mcpAllowedOrigins` | — | Comma-separated list; omit to allow all |
 | `MCP_SERVER_RESOURCE_IDENTIFIER` | `mcpServerResourceIdentifier` | — | RFC 8707 resource indicator URL |
+| `MCP_PUBLIC_URL` | `mcpPublicUrl` | — | Public-facing origin for reverse proxies (Cloudflare Tunnel, nginx, ALB) so emitted URLs carry the correct scheme |
+| `MCP_HEARTBEAT_INTERVAL_MS` | `mcpHeartbeatIntervalMs` | `0` (disabled) | Heartbeat ping interval; 0 disables |
+| `MCP_HEARTBEAT_MISS_THRESHOLD` | `mcpHeartbeatMissThreshold` | `3` | Missed heartbeats before session is considered stale |
+| `MCP_GC_PRESSURE_INTERVAL_MS` | `mcpGcPressureIntervalMs` | `0` (disabled) | Bun-only opt-in forced GC loop for HTTP deployments with heap growth |
 
 ---
 
@@ -75,6 +79,8 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod from environment variable
 | `OAUTH_JWKS_COOLDOWN_MS` | `oauthJwksCooldownMs` | `300000` | 5 min; min time between JWKS refetches |
 | `OAUTH_JWKS_TIMEOUT_MS` | `oauthJwksTimeoutMs` | `5000` | JWKS fetch timeout (ms) |
 | `DEV_MCP_AUTH_BYPASS` | `devMcpAuthBypass` | `false` | Skip auth in development; blocked in `production` |
+| `MCP_JWT_EXPECTED_ISSUER` | `mcpJwtExpectedIssuer` | — | Optional issuer validation for JWT mode |
+| `MCP_JWT_EXPECTED_AUDIENCE` | `mcpJwtExpectedAudience` | — | Optional audience validation for JWT mode |
 | `DEV_MCP_CLIENT_ID` | `devMcpClientId` | — | Dev-only: override client ID |
 | `DEV_MCP_SCOPES` | `devMcpScopes` | — | Dev-only: comma-separated scope overrides |
 

package/skills/api-context/SKILL.md

@@ -42,9 +42,11 @@ interface Context {
   readonly elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
   readonly sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
 
-  // Resource notifications — present when transport supports them
+  // Notifications — present when transport supports them
   readonly notifyResourceListChanged?: () => void;
   readonly notifyResourceUpdated?: (uri: string) => void;
+  readonly notifyPromptListChanged?: () => void;
+  readonly notifyToolListChanged?: () => void;
 
   // Cancellation
   readonly signal: AbortSignal;
@@ -415,8 +417,10 @@ Present only when the definition declares an `errors[]` contract. Builds an `Mcp
 export const fetchItems = tool('fetch_items', {
   description: 'Fetch items by ID.',
   errors: [
-    { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No items matched' },
-    { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited, when: 'Local queue at capacity', retryable: true },
+    { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No items matched',
+      recovery: 'Broaden the query or check the spelling and try again.' },
+    { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited, when: 'Local queue at capacity', retryable: true,
+      recovery: 'Wait a few seconds before retrying or reduce batch size.' },
   ],
   input: z.object({ ids: z.array(z.string()).describe('Item IDs') }),
   output: z.object({ items: z.array(ItemSchema).describe('Resolved items') }),
@@ -534,6 +538,8 @@ The `≥5 words` lint rule on contract `recovery` (validated at lint time) makes
 | `ctx.sample` | `function \| undefined` | Client supports sampling |
 | `ctx.notifyResourceListChanged` | `function \| undefined` | Transport supports resource notifications |
 | `ctx.notifyResourceUpdated` | `function \| undefined` | Transport supports resource notifications |
+| `ctx.notifyPromptListChanged` | `function \| undefined` | Transport supports prompt notifications |
+| `ctx.notifyToolListChanged` | `function \| undefined` | Transport supports tool notifications |
 | `ctx.progress` | `ContextProgress \| undefined` | Tool defined with `task: true` |
 | `ctx.uri` | `URL \| undefined` | Resource handlers only |
 | `ctx.fail` | `(reason, msg?, data?, opts?) => McpError` | Definition declares `errors[]` contract |

package/skills/api-errors/SKILL.md

@@ -11,7 +11,7 @@ metadata:
 
 ## Overview
 
-Error handling in `@cyanheads/mcp-ts-core` follows a strict layered pattern: tool and resource handlers throw `McpError` freely (no try/catch), the handler factory catches and normalizes all errors, and services use `ErrorHandler.tryCatch` for graceful recovery.
+Error handling in `@cyanheads/mcp-ts-core` follows a strict layered pattern: tool and resource handlers throw `McpError` freely (no try/catch), the handler factory catches and normalizes all errors, and services use `ErrorHandler.tryCatch` for structured logging and wrapping.
 
 **Imports:**
 
@@ -64,7 +64,7 @@ export const fetchTool = tool('fetch_articles', {
 |:--------|:---------|
 | Compile time | `ctx.fail('typo')` is a TS error. Auto-completes declared reasons. |
 | Runtime | `ctx.fail(reason, msg?, data?, options?)` builds an `McpError(contract.code, msg, { ...data, reason }, options)` — `data.reason` is auto-populated from the contract and cannot be overridden by caller-supplied data (spread first, then `reason` written last), so observers see a stable identifier. `options` accepts `{ cause }` for ES2022 error chaining. |
-| Lint (startup) | Each `code` validated against `JsonRpcErrorCode`. Reasons validated as snake_case + unique within contract. `recovery` validated as non-empty and ≥ 5 words. |
+| Lint (devcheck) | Each `code` validated against `JsonRpcErrorCode`. Reasons validated as snake_case + unique within contract. `recovery` validated as non-empty and ≥ 5 words. Build-time only — not invoked at server startup. |
 | Lint (conformance) | If the handler `throw new McpError(JsonRpcErrorCode.X)` outside `ctx.fail`, conformance check warns when X isn't declared. |
 
 > **`recovery` is opt-in resolution, not auto-population.** The contract `recovery` is required metadata documenting the agent's next move when this failure mode fires (a forcing function for thoughtful guidance — placeholders like "Try again." get flagged by the linter). It does **not** automatically appear in runtime `data.recovery.hint` — the framework never injects it without an explicit signal at the throw site. Authors opt in by spreading `ctx.recoveryFor('reason')` into the `data` argument, the same way `ctx.fail('reason')` opts into resolving the contract `code`. What the author types at the throw site is what flows to the wire, with no hidden transformation; the resolver is just a typed lookup keyed by the same `reason` the author already typed.
@@ -126,7 +126,7 @@ throw ctx.fail('no_match', `No item ${id}`, {
 
 ### Carrying contract `reason` from services
 
-Services don't have `ctx`, so they can't call `ctx.fail`. To make a service-thrown failure carry the contract's `reason` on the wire, **pass `data: { reason: 'X' }` to the factory**. The framework's auto-classifier preserves `data` unchanged, so clients see the same `error.data.reason` they'd see from `ctx.fail`:
+Services don't receive `ctx` automatically (unlike handlers), so they can't call `ctx.fail` directly — though `ctx` can be passed as a parameter when needed. To make a service-thrown failure carry the contract's `reason` on the wire, **pass `data: { reason: 'X' }` to the factory**. The framework's auto-classifier preserves `data` unchanged, so clients see the same `error.data.reason` they'd see from `ctx.fail`:
 
 ```ts
 // my-service.ts
@@ -271,7 +271,7 @@ Use factories or `McpError` directly when the code must be exact — auto-classi
 The framework applies these steps in order — first match wins:
 
 1. **`McpError` instance** — `error.code` is preserved as-is; no classification needed.
-2. **JS constructor name** — matched against a fixed table (e.g. `TypeError` → `ValidationError`).
+2. **JS constructor name** — matched against a fixed table (e.g. `ZodError` → `ValidationError`, `SyntaxError` → `ValidationError`). Note: `TypeError` is intentionally excluded — runtime TypeErrors are programmer errors, not validation failures.
 3. **Provider-specific patterns** — HTTP status codes, AWS exception names, Supabase, OpenRouter. Checked before common patterns because they are more specific (e.g. `status code 429` beats the generic `rate limit` pattern).
 4. **Common message/name patterns** — broad keyword patterns covering auth, not-found, validation, etc. First match wins; order matters.
 5. **`AbortError` name** — `error.name === 'AbortError'` → `Timeout`.
@@ -344,7 +344,7 @@ Checked before common patterns. Cover: AWS exception names, HTTP status codes, D
 | Tool/resource handlers | Throw `McpError` — no try/catch |
 | Handler factory (tools) | Catches all errors, normalizes to `McpError`, sets `isError: true`, mirrors error across both client surfaces (see [Error-path parity](#error-path-parity)) |
 | Handler factory (resources) | Catches and re-throws to the SDK, which routes through the JSON-RPC error envelope |
-| Services/setup code | `ErrorHandler.tryCatch` for graceful recovery |
+| Services/setup code | `ErrorHandler.tryCatch` for structured logging and wrapping (always rethrows — never swallows) |
 
 ### Error-path parity
 

package/skills/api-linter/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: api-linter
 description: >
-  MCP definition linter rules reference. Use when `bun run lint:mcp`, `bun run devcheck`, or `createApp()` startup reports a lint error or warning (`format-parity`, `schema-is-object`, `name-format`, `server-json-*`, etc.) and you need to understand the rule, its severity, and how to fix it. Every rule ID the linter emits has an entry in this doc.
+  MCP definition linter rules reference. Use when `bun run lint:mcp` or `bun run devcheck` reports a lint error or warning (`format-parity`, `schema-is-object`, `name-format`, `server-json-*`, etc.) and you need to understand the rule, its severity, and how to fix it. Every rule ID the linter emits has an entry in this doc.
 metadata:
   author: cyanheads
   version: "1.3"
@@ -11,19 +11,18 @@ metadata:
 
 ## Overview
 
-The linter validates tool, resource, and prompt definitions against the MCP spec and framework conventions. It runs in three places:
+The linter validates tool, resource, and prompt definitions against the MCP spec and framework conventions. **It is build-time only — not invoked at server startup.** It runs in two places:
 
 | Entry point | When | On failure |
 |:------------|:-----|:-----------|
-| `createApp()` / `createWorkerHandler()` | Every startup | Throws `ConfigurationError`; process exits with a formatted banner. Warnings are logged and startup continues. |
 | `bun run lint:mcp` | Manual or CI | Prints errors + warnings, exits non-zero on errors. |
 | `bun run devcheck` | Pre-commit workflow | Wraps `lint:mcp` alongside typecheck, format, `bun audit`, `bun outdated`. |
 
-All three surface the same `LintReport` from `validateDefinitions()` (exported from `@cyanheads/mcp-ts-core/linter`). Each diagnostic has a stable `rule` ID — that's the anchor you land on via the `See: skills/api-linter/SKILL.md#<rule>` breadcrumb appended to every message.
+Both surface the same `LintReport` from `validateDefinitions()` (exported from `@cyanheads/mcp-ts-core/linter`). Each diagnostic has a stable `rule` ID — that's the anchor you land on via the `See: skills/api-linter/SKILL.md#<rule>` breadcrumb appended to every message.
 
 **Severity:**
-- **error** — MUST-level spec violation; blocks startup.
-- **warning** — SHOULD-level or quality issue; logged but startup continues.
+- **error** — MUST-level spec violation; blocks `devcheck`.
+- **warning** — SHOULD-level or quality issue; logged but `devcheck` continues.
 
 **Imports (if you need to run the linter programmatically):**
 
@@ -52,7 +51,7 @@ Grouped by family. Jump to any rule ID via its anchor.
 | Landing | `landing-*` (23 rules — shape, tagline, logo, links, repo, envExample, connectSnippets, theme) | [Landing config rules](#landing-config-rules) |
 | Prompts | `generate-required` | [Prompt rules](#prompt-rules) |
 | Handler body | `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error` | [Handler body rules](#handler-body-rules) |
-| Error contract (structural) | `error-contract-type`, `error-contract-empty`, `error-contract-entry-type`, `error-contract-code-type`, `error-contract-code-unknown`, `error-contract-code-unknown-error`, `error-contract-reason-required`, `error-contract-reason-format`, `error-contract-reason-unique`, `error-contract-when-required`, `error-contract-retryable-type` | [Error contract rules](#error-contract-rules) |
+| Error contract (structural) | `error-contract-type`, `error-contract-empty`, `error-contract-entry-type`, `error-contract-code-type`, `error-contract-code-unknown`, `error-contract-code-unknown-error`, `error-contract-reason-required`, `error-contract-reason-format`, `error-contract-reason-unique`, `error-contract-when-required`, `error-contract-retryable-type`, `error-contract-recovery-required`, `error-contract-recovery-empty`, `error-contract-recovery-min-words` | [Error contract rules](#error-contract-rules) |
 | Error contract (conformance) | `error-contract-conformance`, `error-contract-prefer-fail` | [Error contract rules](#error-contract-rules) |
 | server.json | ~40 rules prefixed `server-json-*` | [server.json rules](#server-json-rules) |
 
@@ -515,7 +514,9 @@ Heuristic source-text checks that scan `handler.toString()` for common error-han
 
 Fires when a handler contains `throw new Error(...)`. Plain `Error` doesn't carry a JSON-RPC code — the framework's auto-classifier degrades to `InternalError`, hiding the actual failure mode.
 
-**Fix:** use `McpError` or a factory:
+Plain `Error` is acceptable for "don't care" cases where the specific code doesn't matter (per CLAUDE.md: "plain `Error` for don't-care cases"). This rule targets domain-specific failures that deserve a concrete code — upgrade those to factories or `ctx.fail`, and accept the warning for the rest.
+
+**Fix:** use `McpError` or a factory for domain-specific failures:
 
 ```ts
 // instead of:
@@ -596,7 +597,7 @@ Fires when `errors: []` is declared. An empty contract is a no-op — nothing to
 
 **Severity:** error
 
-Fires when an entry in `errors[]` isn't an object. Each entry must be `{ code, reason, when }` (and optionally `retryable`).
+Fires when an entry in `errors[]` isn't an object. Each entry must be `{ code, reason, when, recovery }` (and optionally `retryable`).
 
 ### error-contract-code-type
 
@@ -654,6 +655,28 @@ Fires when an entry's `when` field is missing or empty. `when` is the human-read
 
 Fires when an entry's optional `retryable` field is present but isn't a boolean. Only `true` or `false` is meaningful — drop the field if you can't commit to either.
 
+### error-contract-recovery-required
+
+**Severity:** error
+
+Fires when an entry's `recovery` field is missing or not a string. `recovery` is the agent's next-move guidance when this failure fires — it flows to the wire via `ctx.recoveryFor`.
+
+### error-contract-recovery-empty
+
+**Severity:** error
+
+Fires when `recovery` is an empty string. A blank recovery is worse than none — it suggests the field was considered and deliberately left empty.
+
+**Fix:** write a concrete recovery hint (≥5 words).
+
+### error-contract-recovery-min-words
+
+**Severity:** warning
+
+Fires when `recovery` has fewer than 5 words. Short recoveries like "Try again." are too vague to guide an agent's next action.
+
+**Fix:** expand with specifics — what to try, what parameter to change, which tool to call instead.
+
 ### error-contract-conformance
 
 **Severity:** warning

package/skills/api-services/SKILL.md

@@ -11,7 +11,7 @@ metadata:
 
 ## Overview
 
-Service interfaces are deferred from core's public exports — they remain in downstream servers until shared by 2+ servers. These are documented here for core contributors and servers that use the built-in providers.
+Service providers are exported from `@cyanheads/mcp-ts-core/services`. These are documented here for servers that use the built-in providers.
 
 All services follow the **init/accessor pattern**: initialized in `setup()`, accessed at request time via lazy accessor. See the `add-service` skill for the full pattern.
 

package/skills/api-services/references/graph.md

@@ -111,7 +111,7 @@ const path = await graphService.shortestPath('user:alice', 'user:charlie', conte
   algorithm: 'bfs',
   maxLength: 4,
 });
-if (path) context.log.info(`${path.vertices.length} hops`);
+// path.vertices.length gives the hop count
 
 // Check reachability
 const connected = await graphService.pathExists('user:alice', 'user:charlie', context, 3);

package/skills/api-services/references/speech.md

@@ -24,7 +24,7 @@ The provider interface — implemented by ElevenLabs (TTS) and Whisper (STT):
 | `.getSTTProvider()` | `ISpeechProvider` | Throws `McpError(InvalidRequest)` if no STT provider configured |
 | `.hasTTS()` | `boolean` | Check if TTS is available |
 | `.hasSTT()` | `boolean` | Check if STT is available |
-| `.healthCheck()` | `Promise<{ tts: boolean; stt: boolean }>` | Checks both providers in parallel |
+| `.healthCheck()` | `Promise<{ tts: boolean; stt: boolean }>` | Checks both providers sequentially |
 
 ## Providers
 

package/skills/api-telemetry/SKILL.md

@@ -11,7 +11,7 @@ metadata:
 
 ## Overview
 
-The framework auto-instruments every tool, resource, prompt, storage, LLM, speech, and graph call — each gets its own span and the standard counters/histograms. HTTP server requests pick up spans from `HttpInstrumentation` (or `@hono/otel` on the HTTP transport). Auth checks, session lifecycle, and task lifecycle are tracked as **metrics only** — auth decorates the active HTTP span with attributes, sessions and tasks emit counters.
+The framework auto-instruments every tool, resource, prompt, storage, LLM, speech, and graph call — each gets its own span and the standard counters/histograms. HTTP server requests pick up spans from `HttpInstrumentation` (all Node.js HTTP traffic, skips `/healthz`) plus `httpInstrumentationMiddleware` from `@hono/otel` on the MCP HTTP endpoint when installed (optional Tier 3 peer — `bun add @hono/otel`). On Bun, `HttpInstrumentation` silently no-ops and `@hono/otel` is the only HTTP coverage. Auth checks, session lifecycle, and task lifecycle are tracked as **metrics only** — auth decorates the active HTTP span with attributes, sessions and tasks emit counters.
 
 `requestId`, `traceId`, and `tenantId` correlate automatically across spans, metrics, and logs. Pino logs get `trace_id`/`span_id` injected when a span is active.
 
@@ -76,7 +76,7 @@ Trace context propagates across boundaries via W3C `traceparent` headers. See `a
 
 ## Metrics
 
-All custom metrics are namespaced `mcp.*` (or `process.*` / `http.client.*` where standard semconv applies). Lazy-initialized on first emission; the universal ones are eagerly created at startup so series exist from the first export cycle.
+All custom metrics are namespaced `mcp.*` (or `process.*` / `http.client.*` where standard semconv applies). Lazy-initialized on first emission; tool, resource, prompt, `http.client.request.duration`, heartbeat, session, auth, rate-limit, and error metrics are eagerly created at startup so series exist from the first export cycle. LLM, speech, graph, and storage instruments are lazy-initialized on first use.
 
 ### Tools, resources, prompts
 
@@ -86,17 +86,17 @@ All custom metrics are namespaced `mcp.*` (or `process.*` / `http.client.*` wher
 | `mcp.tool.duration` | histogram | `ms` | `mcp.tool.name`, `mcp.tool.success` |
 | `mcp.tool.errors` | counter | `{errors}` | `mcp.tool.name`, `mcp.tool.error_category` (`upstream`/`server`/`client`) |
 | `mcp.tool.input_bytes` | histogram | `bytes` | `mcp.tool.name` |
-| `mcp.tool.output_bytes` | histogram | `bytes` | `mcp.tool.name` |
+| `mcp.tool.output_bytes` | histogram | `bytes` | `mcp.tool.name` (success only) |
 | `mcp.tool.param.usage` | counter | `{uses}` | `mcp.tool.name`, `mcp.tool.param` (top-level keys supplied by caller) |
 | `mcp.resource.reads` | counter | `{reads}` | `mcp.resource.name`, `mcp.resource.success` |
 | `mcp.resource.duration` | histogram | `ms` | `mcp.resource.name`, `mcp.resource.success` |
 | `mcp.resource.errors` | counter | `{errors}` | `mcp.resource.name` |
-| `mcp.resource.output_bytes` | histogram | `bytes` | `mcp.resource.name` |
+| `mcp.resource.output_bytes` | histogram | `bytes` | `mcp.resource.name` (success only) |
 | `mcp.prompt.generations` | counter | `{generations}` | `mcp.prompt.name`, `mcp.prompt.success` |
 | `mcp.prompt.duration` | histogram | `ms` | `mcp.prompt.name`, `mcp.prompt.success` |
 | `mcp.prompt.errors` | counter | `{errors}` | `mcp.prompt.name`, `mcp.prompt.error_category` |
 | `mcp.prompt.input_bytes` | histogram | `bytes` | `mcp.prompt.name` |
-| `mcp.prompt.output_bytes` | histogram | `bytes` | `mcp.prompt.name` |
+| `mcp.prompt.output_bytes` | histogram | `bytes` | `mcp.prompt.name` (success only) |
 | `mcp.prompt.message_count` | histogram | `{messages}` | `mcp.prompt.name` |
 | `mcp.requests.active` | up/down counter | `{requests}` | — (in-flight handler executions, all three types) |
 

package/skills/api-testing/SKILL.md

@@ -13,6 +13,8 @@ metadata:
 
 Tests target handler behavior directly — call `handler(input, ctx)`, assert on the return value or thrown error. The framework's handler factory (try/catch, formatting, telemetry) is not involved. Use `createMockContext` from `@cyanheads/mcp-ts-core/testing` to construct the `ctx` argument.
 
+**Additional exports from `/testing`:** `createMockLogger()` returns a standalone `MockContextLogger` for unit-testing code that accepts a `ContextLogger` directly (services, utilities). `createInMemoryStorage(options?)` provides a real `StorageService` backed by `InMemoryProvider` for testing services that take a `StorageService` dependency.
+
 **Philosophy:** Test behavior, not implementation. Refactors should not break tests. Match the repo's existing test layout: fresh scaffolds use `tests/`, while colocated `src/**/*.test.ts` files are also supported. Integration tests at I/O boundaries over unit tests of internals.
 
 ---
@@ -43,9 +45,12 @@ interface MockContextOptions {
   auth?: AuthContext;
   elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
   errors?: readonly ErrorContract[];
+  notifyPromptListChanged?: () => void;
   notifyResourceListChanged?: () => void;
   notifyResourceUpdated?: (uri: string) => void;
+  notifyToolListChanged?: () => void;
   progress?: boolean;
+  sessionId?: string;
   requestId?: string;
   sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
   signal?: AbortSignal;
@@ -60,8 +65,11 @@ interface MockContextOptions {
 | `auth` | Sets `ctx.auth` for scope-checking tests |
 | `elicit` | Assigns a function to `ctx.elicit` for testing elicitation calls |
 | `errors` | Attaches a typed `ctx.fail` against the contract — same wiring the production handler factory uses. Pass `myTool.errors` directly. |
+| `notifyPromptListChanged` | Assigns `ctx.notifyPromptListChanged` for prompt-list change notification tests |
 | `notifyResourceListChanged` | Assigns `ctx.notifyResourceListChanged` for resource notification tests |
 | `notifyResourceUpdated` | Assigns `ctx.notifyResourceUpdated` for resource update notification tests |
+| `notifyToolListChanged` | Assigns `ctx.notifyToolListChanged` for tool-list change notification tests |
+| `sessionId` | Sets `ctx.sessionId` for handlers that branch on session ID |
 | `progress` | Populates `ctx.progress` with real state-tracking implementation (see below) |
 | `requestId` | Overrides `ctx.requestId` (default: `'test-request-id'`) |
 | `sample` | Assigns a function to `ctx.sample` for testing sampling calls |
@@ -93,7 +101,7 @@ expect(progress._messages).toContain('step message');
 
 ### Mock logger
 
-`ctx.log` captures all log calls for inspection. The mock returns the typed `MockContextLogger` from `@cyanheads/mcp-ts-core/testing` — import that instead of hand-casting:
+`ctx.log` captures all log calls for inspection. Import `MockContextLogger` from `@cyanheads/mcp-ts-core/testing` and cast `ctx.log` to access the `.calls` array (the cast is necessary because `createMockContext` returns `Context`, which types `log` as `ContextLogger`):
 
 ```ts
 import { createMockContext, type MockContextLogger } from '@cyanheads/mcp-ts-core/testing';

package/skills/api-utils/SKILL.md

@@ -29,7 +29,7 @@ Utility exports from `@cyanheads/mcp-ts-core/utils`. Utilities with complex APIs
 
 | Export | API | Notes |
 |:-------|:----|:------|
-| `fetchWithTimeout` | `(url, timeoutMs, context: RequestContext, options?: FetchWithTimeoutOptions) -> Promise<Response>` | Wraps `fetch` with `AbortController` timeout. `FetchWithTimeoutOptions` extends `RequestInit` (minus `signal`) and adds `rejectPrivateIPs?: boolean` and `signal?: AbortSignal` (external cancellation). SSRF guard (best-effort, not hard isolation): blocks RFC 1918, loopback, link-local, CGNAT, cloud metadata. DNS validation on Node; hostname-only on Workers. Manual redirect following (max 5) with per-hop SSRF check. **DNS rebinding / TOCTOU gap** — the validation lookup and `fetch`'s own resolution are independent; pair with egress controls or a DNS-pinning fetch proxy for strong isolation. |
+| `fetchWithTimeout` | `(url, timeoutMs, context: RequestContext, options?: FetchWithTimeoutOptions) -> Promise<Response>` | Wraps `fetch` with `AbortController` timeout. `FetchWithTimeoutOptions` extends `RequestInit` (minus `signal`) and adds `rejectPrivateIPs?: boolean` and `signal?: AbortSignal` (external cancellation). SSRF guard (best-effort, not hard isolation): blocks RFC 1918, loopback, link-local, CGNAT, cloud metadata. DNS validation on Node, Bun, and Cloudflare Workers under `nodejs_compat`; hostname-only fallback otherwise. Manual redirect following (max 5) with per-hop SSRF check. **DNS rebinding / TOCTOU gap** — the validation lookup and `fetch`'s own resolution are independent; pair with egress controls or a DNS-pinning fetch proxy for strong isolation. |
 | `withRetry` | `<T>(fn: () => Promise<T>, options?: RetryOptions) -> Promise<T>` | Executes `fn` with exponential backoff. Retries on transient errors (`ServiceUnavailable`, `Timeout`, `RateLimited`); non-transient errors fail immediately. On exhaustion, enriches the final error with attempt count in message and `data.retryAttempts`. **Place the retry boundary around the full pipeline** (fetch + parse), not just the network call. `RetryOptions`: `maxRetries` (default `3`), `baseDelayMs` (default `1000`), `maxDelayMs` (default `30000`), `jitter` (default `0.25`), `operation` (log label), `context` (RequestContext), `signal` (AbortSignal), `isTransient` (custom predicate). |
 | `httpErrorFromResponse` | `(response: Response, options?: HttpErrorFromResponseOptions) -> Promise<McpError>` | Maps an HTTP `Response` to a properly classified `McpError` — full status table including 401/403/408/422/429/5xx, body capture (truncated), `retry-after` header, optional `cause`. Use this instead of hand-rolling `if (status === 429) ...` ladders. Reads the response body — `clone()` first if you need it elsewhere. `HttpErrorFromResponseOptions`: `service?` (logical name in message, e.g. `'NCBI'`), `captureBody?` (default `true`), `bodyLimit?` (default `500`), `data?` (extra fields merged into `error.data`), `cause?`, `codeOverride?` (per-status mapping override). Pairs naturally with `withRetry` — both classify codes the same way. |
 | `httpStatusToErrorCode` | `(status: number) -> JsonRpcErrorCode \| undefined` | Sync status → code lookup. Returns `undefined` for 1xx/2xx/3xx. Use when you need just the code without a `Response` object handy. |