@cyanheads/mcp-ts-core 0.9.7 → 0.9.9

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. |

package/skills/api-workers/SKILL.md

@@ -59,7 +59,7 @@ Fresh scaffolds register definitions directly in the entry point as shown above.
 
 - **Per-request `McpServer` factory**: a new server instance is created for each request. Required by SDK security advisory GHSA-345p-7cg4-v4c7.
 - **Env bindings refreshed per-request**: Cloudflare may rotate binding object references between requests; the handler re-injects them on every call.
-- **`ctx.waitUntil()` is documented but not yet called by the framework**: the `ExecutionContext` is received and passed through to `app.fetch` and `onScheduled`, but the framework does not currently call `ctx.waitUntil()` for telemetry flush. Spans complete synchronously within the request lifecycle.
+- **OTel NodeSDK is disabled in Workers** — `canUseNodeSDK()` returns `false` for V8 isolates, so no OTLP spans or metrics are emitted. Structured logs via `ctx.log` still work. `OTEL_ENABLED=true` has no effect in Workers. `ctx.waitUntil()` is received and passed through to `app.fetch` and `onScheduled` but not called by the framework (nothing to flush asynchronously).
 - **Singleton app promise with retry-on-failure**: the framework init runs once; if it fails, the next request retries rather than leaving the Worker in a permanently broken state.
 
 ---
@@ -130,7 +130,7 @@ In Workers, only these storage providers are allowed:
 `filesystem`, `supabase`, and unknown provider types are not on the whitelist:
 
 - **`filesystem`** and unknown types throw `ConfigurationError` in serverless environments.
-- **`supabase`** does **not** silently fall back. The framework may validate Supabase credentials first, but Worker startup still fails with `ConfigurationError` because Supabase storage is not a supported serverless provider. Do not set `STORAGE_PROVIDER_TYPE=supabase` in a Worker.
+- **`supabase`** does **not** silently fall back. The serverless provider whitelist check fires immediately at the top of `createStorageProvider()` — Supabase credentials are never validated. Worker startup fails with `ConfigurationError` because Supabase is not on the serverless whitelist. Do not set `STORAGE_PROVIDER_TYPE=supabase` in a Worker.
 
 Set `STORAGE_PROVIDER_TYPE` to one of the four whitelisted values to avoid unexpected behavior.
 
@@ -142,17 +142,24 @@ Set `STORAGE_PROVIDER_TYPE` to one of the four whitelisted values to avoid unexp
 compatibility_flags = ["nodejs_compat"]
 compatibility_date = "2025-09-01"  # must be >= 2025-09-01
 
+# Built-in storage providers require these exact binding names:
 [[kv_namespaces]]
-binding = "MY_CUSTOM_KV"
+binding = "KV_NAMESPACE"       # required for cloudflare-kv storage
 id = "..."
 
 [[r2_buckets]]
-binding = "MY_R2_BUCKET"
+binding = "R2_BUCKET"          # required for cloudflare-r2 storage
 bucket_name = "..."
+
+[[d1_databases]]
+binding = "DB"                 # required for cloudflare-d1 storage
+database_id = "..."
 ```
 
 `nodejs_compat` is required for Node.js API shims (e.g., `process.env`, `Buffer`, `crypto`). The minimum `compatibility_date` activates the required shim set.
 
+**Binding names for core storage are hardcoded** — the storage factory looks for `KV_NAMESPACE`, `R2_BUCKET`, and `DB` on `globalThis`. Using different binding names will cause a `ConfigurationError`. For custom (non-storage) bindings, use `extraObjectBindings` to map arbitrary binding names to `globalThis` keys.
+
 ---
 
 ## Workers-specific warnings
@@ -190,4 +197,4 @@ export function getServerConfig() {
 
 > `DuckDB canvas requires Node.js or Bun. Set CANVAS_PROVIDER_TYPE=none or omit it for Cloudflare Workers deployment.`
 
-Leave the env unset (or set to `none`) for Worker deployments. Tools that conditionally use canvas should check `if (!ctx.core.canvas) { ... }` and surface a clear "feature unavailable on this deployment" message. See `api-canvas` for the full DataCanvas reference.
+Leave the env unset (or set to `none`) for Worker deployments. Tools that conditionally use canvas should check the module-level accessor (`if (!getCanvas()) { ... }`) and surface a clear "feature unavailable on this deployment" message. See `api-canvas` for the full DataCanvas reference and setup wiring pattern.

package/skills/design-mcp-server/SKILL.md

@@ -29,6 +29,14 @@ Gather before designing. Ask the user if not obvious from context:
 
 If the domain has a public API, read its docs before designing. For internal-only servers, skip API research and go straight to user goals. Don't design from vibes either way.
 
+## Server Naming
+
+The server name (repo name, npm package, public identity) must communicate what it does at a glance. The test: can a human or agent scanning a server list tell what this server does from the name alone?
+
+- **Use the canonical platform/brand name, not abbreviations.** `libofcongress-mcp-server` not `loc-mcp-server` ("loc" reads as lines-of-code or location). `federal-reserve-mcp-server` not `fred-mcp-server` ("fred" reads as a person's name).
+- **Add a descriptive suffix when the base name is a non-obvious acronym.** Pattern: `{acronym}-{domain}-mcp-server` — e.g., `eia-energy-mcp-server`, `bls-labor-mcp-server`, `nhtsa-vehicle-safety-mcp-server`. Skip when the name is already self-descriptive (`earthquake-mcp-server`, `wikidata-mcp-server`).
+- **The name becomes the tool prefix.** Every tool is `{prefix}_{verb}_{noun}`, so the server name shows up in every tool call an agent sees. A descriptive name gives agents domain context without reading the server's instructions.
+
 ## Steps
 
 ### 1. Research External Dependencies
@@ -53,6 +61,8 @@ When research is genuinely parallelizable (multiple independent APIs, several SD
 - **Pagination behavior** — verify token format, page size limits, and what happens when results exceed one page.
 - **Error shapes** — trigger real 400/404/429 responses to see the actual error format, not just what docs claim.
 
+**Stopping condition:** at minimum, probe one list/search endpoint, one single-item GET, and one error case (force a 404 or 400). For large APIs with many resource types, add one probe per major noun. Stop when the response shapes and error envelope are confirmed.
+
 This step prevents building a service layer against assumed response shapes that don't match reality.
 
 ### 2. Map User Goals, Then Domain Operations
@@ -74,7 +84,7 @@ Then enumerate the underlying **domain operations** the system supports, grouped
 | Task | list (by project), get, create, update status, assign, comment |
 | User | list, get current |
 
-The user-goal list shapes the tool surface; the operation list fills in the gaps. Not every operation becomes a tool.
+The user-goal list shapes the tool surface; the operation list fills in the gaps. Not every operation becomes a tool — an operation stays as raw material (not its own tool) when it's already fully covered by an existing tool's output, or when the only agents who'd use it are in scenarios outside this server's stated purpose.
 
 ### 3. Classify into MCP Primitives
 
@@ -482,12 +492,12 @@ What this server does, what system it wraps, who it's for.
 
 Each step is independently testable.
 
-<!-- Optional sections for API-wrapping servers: -->
-## Domain Mapping          <!-- nouns × operations → API endpoints -->
-## Workflow Analysis        <!-- how tools chain for real tasks -->
-## Design Decisions         <!-- rationale for consolidation, naming, tradeoffs -->
-## Known Limitations        <!-- inherent API/data constraints the server can't solve -->
-## API Reference            <!-- query language, pagination, rate limits -->
+<!-- Optional sections — include when the trigger fires: -->
+## Domain Mapping          <!-- nouns × operations → API endpoints; include when ≥3 nouns each with ≥3 operations -->
+## Workflow Analysis        <!-- how tools chain for real tasks; include when any tool makes ≥3 upstream calls -->
+## Design Decisions         <!-- rationale for consolidation, naming, tradeoffs; include when a choice would otherwise be opaque -->
+## Known Limitations        <!-- inherent API/data constraints the server can't solve; include when a constraint visibly caps utility -->
+## API Reference            <!-- query language, pagination, rate limits; include when worth documenting -->
 ```
 
 Keep it concise. The design doc is a working reference, not a spec document — enough to orient a developer (or agent) implementing the server, not more.
@@ -512,7 +522,7 @@ The table surfaces design questions early: should the elicit happen before or af
 
 ### 9. Confirm and Proceed
 
-If the user has already authorized implementation (e.g., "build me a ___ server"), proceed directly to scaffolding using the design doc as the plan. Otherwise, present the design doc to the user for review before implementing.
+If the user has already authorized implementation — any message that contains both a design request and a build/implement verb in the same clause (e.g., "build me a ___ server", "design and implement a ___") — proceed directly to scaffolding using the design doc as the plan. Otherwise, present the design doc to the user for review before implementing.
 
 ## After Design
 
@@ -530,6 +540,7 @@ Execute the plan using the scaffolding skills:
 Items without an `If …:` prefix apply to every design. Conditional items only apply when the trigger fires — otherwise skip them.
 
 - [ ] External APIs/dependencies researched and verified (docs fetched, SDKs identified)
+- [ ] **If wrapping an external API:** live API probed (at minimum: one list/search, one single-item GET, one error case)
 - [ ] User goals enumerated first (3–10 outcomes agents will accomplish, scaled to domain size), then domain operations mapped as raw material
 - [ ] Each operation classified as tool, resource, prompt, or excluded
 - [ ] Catastrophically irreversible operations excluded from the tool surface (stay in vendor UI) — not just `destructiveHint`
@@ -553,6 +564,7 @@ Items without an `If …:` prefix apply to every design. Conditional items only
 - [ ] **If a parameter determines blast radius:** safe default set (e.g., `mode: 'preview'`, `dryRun: true`, `confirmCount` required)
 - [ ] **App tools default to no.** If one was proposed, verified there's a real human-in-the-loop in an MCP Apps-capable client justifying the iframe/CSP/`format()`-twin maintenance cost — otherwise dropped in favor of a standard tool
 - [ ] **If the server exposes resources:** URIs use `{param}` templates, pagination planned for large lists
+- [ ] **If the server is itself the source of truth (no external API):** state lifecycle planned — tenant-scoped vs. global, TTLs, what survives restart, storage backend chosen
 - [ ] **If the server has external deps or shared state:** service layer planned (or explicitly skipped with reasoning)
 - [ ] **If services wrap external APIs:** resilience planned (retry boundary, backoff, parse classification)
 - [ ] **If exposing a SQL/analytical workspace over tabular data is in scope:** DataCanvas considered (`api-canvas` skill) as one option before designing custom analytical state — register / query / export tools accepting an optional `canvas_id`, with `ctx.core.canvas?` reads