@cyanheads/mcp-ts-core 0.11.2 → 0.11.4

package/scripts/tree.ts

@@ -131,9 +131,15 @@ async function loadIgnoreHandler(
   return ig;
 }
 
-function isIgnored(entryPath: string, root: string, ig: Ignore): boolean {
+/**
+ * A directory-only pattern (`/data/`, `.claude/`) matches only when the tested
+ * path carries the trailing slash too — `ignore` has no other way to tell a
+ * directory from a file of the same name. The caller holds the `Dirent`, so the
+ * flag is free.
+ */
+function isIgnored(entryPath: string, root: string, ig: Ignore, isDirectory: boolean): boolean {
   const rel = relative(root, entryPath).split(sep).join(posix.sep);
-  return ig.ignores(rel);
+  return ig.ignores(isDirectory ? `${rel}/` : rel);
 }
 
 /**
@@ -182,7 +188,7 @@ async function generateTree(
   }
 
   const filteredEntries = entries
-    .filter((entry) => !isIgnored(join(resolvedDir, entry.name), root, ig))
+    .filter((entry) => !isIgnored(join(resolvedDir, entry.name), root, ig, entry.isDirectory()))
     .sort((a, b) => {
       if (a.isDirectory() && !b.isDirectory()) return -1;
       if (!a.isDirectory() && b.isDirectory()) return 1;

package/skills/add-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a test file for an existing tool, resource, or service. Use when the user asks to add tests, improve coverage, or when a definition exists without a matching test file.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: reference
 ---
@@ -35,7 +35,7 @@ Read the handler and identify:
 | **Happy path** | Valid input → expected output. Include at least one. |
 | **Input variations** | Optional fields omitted, defaults applied, boundary values |
 | **Error paths** | Invalid state, missing resources, service failures → correct error thrown |
-| **`ctx.state` usage** | Use `createMockContext({ tenantId: 'test' })` to enable storage |
+| **`ctx.state` usage** | Available on any mock context (tenant `'default'` unless `{ tenantId }` says otherwise). It runs the production storage path, so use storage-legal keys (`cache/v1/abc`, never `cache:v1:abc`) and assert TTL expiry with fake timers. |
 | **`ctx.elicit`** | Mock with `vi.fn()`, also test the absent case (undefined) |
 | **`ctx.progress`** | Use `createMockContext({ progress: true })` for task tools |
 | **`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`. |

package/skills/api-auth/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Authentication, authorization, and multi-tenancy patterns for `@cyanheads/mcp-ts-core`. Use when implementing auth scopes on tools/resources, configuring auth modes (none/jwt/oauth), working with JWT/OAuth env vars, or understanding how tenantId flows through ctx.state.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
@@ -175,11 +175,11 @@ A `WARNING`-level log is emitted at startup whenever the flag is active so opera
 ```ts
 handler: async (input, ctx) => {
   // Automatically scoped to ctx.tenantId — no manual prefixing
-  await ctx.state.set('item:123', { name: 'Widget', count: 42 });
-  const item = await ctx.state.get<Item>('item:123');
-  await ctx.state.delete('item:123');
+  await ctx.state.set('item/123', { name: 'Widget', count: 42 });
+  const item = await ctx.state.get<Item>('item/123');
+  await ctx.state.delete('item/123');
 
-  const page = await ctx.state.list('item:', { cursor, limit: 20 });
+  const page = await ctx.state.list('item/', { cursor, limit: 20 });
   // page: { items: Array<{ key, value }>, cursor?: string }
 },
 ```

package/skills/api-context/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.progress`, `ctx.enrich`, `ctx.content`), and when to use each.
 metadata:
   author: cyanheads
-  version: "1.9"
+  version: "1.11"
   audience: external
   type: reference
 ---
@@ -155,23 +155,23 @@ interface ContextState {
 
 ```ts
 // Store — accepts any serializable value, no manual JSON.stringify needed
-await ctx.state.set('item:123', { name: 'Widget', count: 42 });
-await ctx.state.set('session:xyz', token, { ttl: 3600 }); // TTL in seconds
+await ctx.state.set('item/123', { name: 'Widget', count: 42 });
+await ctx.state.set('session/xyz', token, { ttl: 3600 }); // TTL in seconds
 
 // Retrieve — generic type assertion or Zod-validated
-const item = await ctx.state.get<Item>('item:123');       // T | null (type assertion)
-const safe = await ctx.state.get('item:123', ItemSchema);  // T | null (runtime validated)
+const item = await ctx.state.get<Item>('item/123');       // T | null (type assertion)
+const safe = await ctx.state.get('item/123', ItemSchema);  // T | null (runtime validated)
 
 // Delete
-await ctx.state.delete('item:123');
+await ctx.state.delete('item/123');
 
 // Batch operations
-const values = await ctx.state.getMany<Item>(['item:1', 'item:2']); // Map<string, T>
+const values = await ctx.state.getMany<Item>(['item/1', 'item/2']); // Map<string, T>
 await ctx.state.setMany(new Map([['a', 1], ['b', 2]]));
-const deleted = await ctx.state.deleteMany(['item:1', 'item:2']);    // number
+const deleted = await ctx.state.deleteMany(['item/1', 'item/2']);    // number
 
 // List with prefix + pagination
-const page = await ctx.state.list('item:', { cursor, limit: 20 });
+const page = await ctx.state.list('item/', { cursor, limit: 20 });
 for (const { key, value } of page.items) { /* ... */ }
 if (page.cursor) { /* more pages available */ }
 ```
@@ -180,6 +180,7 @@ if (page.cursor) { /* more pages available */ }
 
 - Throws `McpError(InvalidRequest)` if `tenantId` is missing. Won't happen in stdio (any auth mode) or HTTP+`MCP_AUTH_MODE=none` — both default to `'default'`. Can happen in HTTP+`MCP_AUTH_MODE=jwt`/`oauth` when the token lacks a `tid` claim (intentional fail-closed: distinct authenticated callers must not silently share state).
 - Keys are tenant-prefixed internally; handlers never need to namespace manually.
+- **Key charset:** `^[a-zA-Z0-9_.\-/]+$`, 1024 chars max, no `..`. Slashes are the namespace separator — a colon (`item:123`) throws `McpError(ValidationError)` on every call. The rule covers `list` prefixes and every key in a batch operation. `createMockContext().state` enforces it identically, so an illegal key fails in the test rather than in a deployment.
 - **Workers persistence:** The `in-memory` provider loses data on cold starts. Use `cloudflare-kv`, `cloudflare-r2`, or `cloudflare-d1` for durable storage in Workers.
 
 ---
@@ -237,14 +238,14 @@ import { invalidRequest } from '@cyanheads/mcp-ts-core/errors';
 if (!ctx.sessionId) {
   throw invalidRequest('Session required for this operation.');
 }
-await ctx.state.set(`session:${ctx.sessionId}:${baseKey}`, value);
+await ctx.state.set(`session/${ctx.sessionId}/${baseKey}`, value);
 ```
 
 **Lax — fall back to tenant-shared key:**
 
 ```ts
 const sessionKey = ctx.sessionId
-  ? `session:${ctx.sessionId}:${baseKey}`
+  ? `session/${ctx.sessionId}/${baseKey}`
   : baseKey;
 await ctx.state.set(sessionKey, value);
 ```
@@ -253,7 +254,7 @@ await ctx.state.set(sessionKey, value);
 
 ### Behavior notes
 
-- **Not a tenant boundary.** `ctx.state` is still tenant-scoped. Building session-scoped state is the consumer's responsibility — prefix with `session:${ctx.sessionId}:` as shown above.
+- **Not a tenant boundary.** `ctx.state` is still tenant-scoped. Building session-scoped state is the consumer's responsibility — prefix with `session/${ctx.sessionId}/` as shown above.
 - **Auto-task tools.** `task: true` handlers run in a detached background context with no session attachment — `ctx.sessionId` is always `undefined` regardless of mode.
 - **Worker bundle.** Workers use the same HTTP transport plumbing; session behavior matches Node HTTP.
 
@@ -603,6 +604,7 @@ ctx.enrich.truncated({ shown, cap, ceiling?, guidance? }): void
 | Service usage | Services accepting `ctx: Context` can call `ctx.enrich(...)`; the value reaches `structuredContent` exactly as if the handler had. |
 | `format-parity` | Enrichment lives outside `output`, so the `format-parity` lint never requires it in `format()`. |
 | Trailer rendering | Per field: kind-tag if set (notice/total/echo/delta), else the definition's `enrichmentTrailer.render`/`label`, else `**key:** value` (objects/arrays `JSON.stringify`'d). A structured field with no `render` errors under `enrichment-trailer-render` — supply one so it renders as markdown; `structuredContent` keeps the full value regardless. |
+| Trailer layout | One field per line. A field whose last line opens a block quote or a list item (`notice`, or a `render` ending in `>`, `-`, `*`, `1.`) gets a blank line after it, so the next field renders as its own block instead of being folded into that container by CommonMark lazy continuation. |
 
 ### `ctx.enrich.truncated()` — capped-list disclosure
 

package/skills/api-linter/SKILL.md

@@ -4,7 +4,7 @@ description: >
   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.8"
+  version: "1.9"
   audience: external
   type: reference
 ---
@@ -43,8 +43,8 @@ Grouped by family. Jump to any rule ID via its anchor.
 | Family | Rules | Section |
 |:-------|:------|:--------|
 | Definition | `definition-invalid` | [Definition rules](#definition-rules) |
-| Format parity | `format-parity`, `format-parity-threw`, `format-parity-walk-failed` | [Format parity](#format-parity) |
-| Schema | `schema-is-object`, `describe-on-fields`, `schema-serializable` | [Schema rules](#schema-rules) |
+| Format parity | `format-parity`, `format-parity-threw`, `format-parity-walk-failed`, `format-parity-depth-limit` | [Format parity](#format-parity) |
+| Schema | `schema-is-object`, `describe-on-fields`, `schema-serializable`, `schema-unsatisfiable` | [Schema rules](#schema-rules) |
 | Portability | `schema-format-portability`, `schema-anyof-needs-type`, `schema-no-discriminator-keyword`, `schema-no-defs`, `schema-dialect-tag` | [Portability rules](#portability-rules) |
 | Names | `name-required`, `name-format`, `name-unique` | [Name rules](#name-rules) |
 | Tools | `description-required`, `handler-required`, `auth-type`, `auth-scope-format`, `annotation-type`, `annotation-coherence`, `meta-ui-type`, `meta-ui-resource-uri-required`, `meta-ui-resource-uri-scheme`, `app-tool-resource-pairing`, `canvas-consumer-missing` | [Tool rules](#tool-rules) |
@@ -75,6 +75,19 @@ Fires when a `tools`, `resources`, or `prompts` array passed to `validateDefinit
 
 Why this family exists: different MCP clients forward different surfaces of a tool response to the model. Claude Code reads `structuredContent` (from your handler's return value, typed by `output`). Claude Desktop reads `content[]` (from your `format()` function). Every field must be visible on both surfaces or one class of client sees less than another. The linter enforces this by synthesizing a sample value where every leaf is a uniquely identifiable sentinel, calling `format()` once, then verifying each sentinel (or its key name, for permissive types like booleans) appears in the rendered text.
 
+**How leaves are matched.** Two strategies, picked by leaf type:
+
+| Leaf type | Sentinel | Match |
+|:--|:--|:--|
+| string | `MCPPARITY<path>` — alphanumeric only | substring, anywhere in the rendered text |
+| number / int / bigint | a large distinctive integer | substring, retried against locale digit grouping (`900,000,001` → `900000001`) |
+| boolean, enum member, literal, unrecognized type | the value the schema dictates (`true`, the first enum member, the literal) | **delimited token** — must not be flanked by another alphanumeric or `_`; falls back to the field's key name as a whole word or camelCase segment |
+
+Two consequences worth knowing when writing a `format()`:
+
+- **The string sentinel is alphanumeric so escaping does not break it.** `content[]` is markdown carrying upstream text you do not control, so escaping `_`, `*`, `` ` ``, `[`, `<` at the render boundary is correct — and it leaves an alphanumeric probe byte-identical. Markdown escaping, HTML escaping, and URL encoding all pass. You never need to carve an exception into your escape set to keep `lint:mcp` green.
+- **Schema-dictated values must render as their own token.** A required `kind: z.enum(['full', 'outline'])` that `format()` never renders is not satisfied by the letters `full` appearing inside a longer word elsewhere in the output — `case_name_full`, `inactive`, `listing`. Render the field, or render its key name as a label.
+
 ### format-parity
 
 **Severity:** error
@@ -125,7 +138,17 @@ Add narrow guards. The linter feeds a synthetic but schema-valid value; if your
 
 Fires when the linter cannot walk the output schema to build a synthetic sample (usually because the schema uses an unusual composition the walker doesn't recognize). Parity is not verified for that tool — nothing is broken at runtime, but the check is silently disabled.
 
-**Fix:** inspect the walker error message in the diagnostic. Usually caused by very deep recursion, custom Zod extensions, or mixing Zod 3 and 4 schema internals. File an issue against `@cyanheads/mcp-ts-core` with the schema shape — this is a linter gap, not user error.
+**Fix:** inspect the walker error message in the diagnostic. Usually caused by custom Zod extensions or mixing Zod 3 and 4 schema internals. File an issue against `@cyanheads/mcp-ts-core` with the schema shape — this is a linter gap, not user error.
+
+### format-parity-depth-limit
+
+**Severity:** warning
+
+Fires when an output field is nested deeper than the sentinel walker's depth limit (8). Everything at and below that path was **not evaluated** — parity for the subtree is unknown, not verified. Four array hops from the output root is enough to reach the limit, so it turns up on ordinary shapes, not just pathological ones.
+
+The bound exists because every array / union / record hop multiplies the variant set, and a self-referential schema would otherwise recurse forever. What changed is the reporting: an unevaluated subtree used to be indistinguishable from a field that resolved to nothing, so it read as a pass.
+
+**Fix:** flatten the output shape so the field sits within the limit, or verify by hand that `format()` renders it (and treat the warning as the standing reminder that the linter is not covering it).
 
 ---
 
@@ -200,6 +223,25 @@ z.string().describe('ISO 8601 timestamp, e.g., 2026-04-20T12:00:00Z')
 
 Parse the string to a `Date` inside the handler if you need one.
 
+### schema-unsatisfiable
+
+**Severity:** error
+
+Fires when a node in the emitted JSON Schema describes an **empty value set** — a field no value can ever satisfy. Nothing downstream reports this: the tool registers, the schema is forwarded to the model, and the argument simply can never be populated.
+
+Evaluated on the emitted schema rather than on the Zod schema, because the two disagree in exactly the case that matters most.
+
+| What you wrote | What is emitted |
+|:--|:--|
+| `z.enum([1, 2, 3, 4, 5])` — a numeric array handed to a string-only constructor | `{"type": "string", "enum": []}` |
+| `z.enum([])` | `{"type": "string", "enum": []}` |
+| `z.union([])` | `{"anyOf": []}` |
+| `z.never()` | `{"not": {}}` |
+
+**Fix:** for a closed set of non-string values, use a multi-value literal — `z.literal([1, 2, 3, 4, 5])` emits `{"type": "number", "enum": [1, 2, 3, 4, 5]}`. For an empty enum or union, the field has no legal values at all; drop it or give it real members.
+
+Not flagged, deliberately: `allOf: []` is vacuously true (matches everything), and empty `required` / `properties` / `prefixItems` are absent constraints rather than impossible ones.
+
 ---
 
 ## Portability rules
@@ -818,10 +860,22 @@ Fires when an `enrichmentTrailer` key doesn't match any declared `enrichment` fi
 **Severity:** warning
 
 Fires when a tool:
-1. has a depth-0 input field named `limit`, `per_page`, `page_size`, `max_results`, or `max_items` (case-insensitive; camelCase twins like `perPage`, `maxResults` match too), AND
+1. has a depth-0 input field whose name is cap-*shaped*, AND
 2. has at least one depth-0 array-typed `output` field, AND
 3. declares no truncation disclosure.
 
+Cap-shaped means, after normalizing camelCase to snake_case (so `maxRecords` and `max_records` are one case):
+
+| Shape | Examples |
+|:--|:--|
+| `limit`, `<noun>_limit` / `<noun>Limit` | `limit`, `result_limit`, `resultLimit` |
+| `max_<noun>` / `max<Noun>` | `max_results`, `maxResults`, `max_items`, `maxRecords`, `maxRows` |
+| page-size idioms | `per_page`, `perPage`, `page_size`, `pageSize` |
+
+Matched by shape rather than an enumerated list, so a new cap noun is covered on arrival instead of silently disabling the rule for that tool. Deliberately not matched: bare `count`, `size`, `n`, `rows`, `records`, and words that merely begin with the letters (`maximum`).
+
+The shape does not distinguish a cap on *how many* from an upper bound on a *value*, so a range filter written as `max_<noun>` — `max_magnitude`, `max_depth_km`, `maxLat`, `max_date` — matches too. On a tool that also returns an array and discloses nothing, that reads as a warning about truncation the tool does not perform. Disclose `totalCount` if the array is paged at all (which silences it honestly), or exempt the tool via `truncationAllowlist` / `MCP_LINT_TRUNCATION_ALLOWLIST`.
+
 **Disclosure-present (rule silent) when** any of the following is true:
 - The declared `enrichment` shape has a `truncated` or `totalCount` key (`ctx.enrich.truncated()` and `ctx.enrich.total()` satisfy this).
 - The `output` schema has a depth-0 `truncated` or `totalCount` field.

package/skills/api-testing/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Testing patterns for MCP tool/resource handlers using `createMockContext` and Vitest. Covers mock context options, handler testing, McpError assertions, format testing, Vitest config setup, and test isolation conventions.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.8"
   audience: external
   type: reference
 ---
@@ -51,7 +51,7 @@ mcpTest('stubs an upstream HTTP boundary', async ({ fetchMock }) => {
 | Fixture | Type | Per-test? | Notes |
 |:--------|:-----|:----------|:------|
 | `ctx` | `Context` | Yes | Fresh `createMockContext()` each test |
-| `session` | `MockSession` | Yes | Fresh `{ sessionId, tenantId?, ctx }` from `createMockSession()` |
+| `session` | `MockSession` | Yes | Fresh `{ sessionId, tenantId, ctx }` from `createMockSession()` |
 | `fetchMock` | `FetchMockHarness` | Yes | Strict fetch fake installed/restored around the requesting test |
 | `storage` | `StorageService` | Yes | Fresh `createInMemoryStorage()` each test |
 
@@ -131,8 +131,8 @@ Use `runToolContract(definition, input, { context })` from `/testing` when a cus
 ```ts
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
 
-createMockContext()                                           // minimal — ctx.state operations throw without tenantId
-createMockContext({ tenantId: 'test-tenant' })               // enables ctx.state (tenant-scoped in-memory storage)
+createMockContext()                                           // working ctx.state on tenant 'default'
+createMockContext({ tenantId: 'test-tenant' })               // explicit tenant scope for ctx.state
 createMockContext({ errors: myTool.errors })                 // attaches typed ctx.fail keyed by the contract reasons
 createMockContext({ elicit: vi.fn().mockResolvedValue(...) }) // with elicitation
 createMockContext({ progress: true })                        // with task progress (ctx.progress populated)
@@ -147,10 +147,10 @@ createMockContext({ uri: new URL('myscheme://item/123') })   // for resource han
 `MockContextOptions` interface:
 
 ```ts
-interface MockContextOptions {
+interface MockContextOptions<TErrors extends readonly ErrorContract[] | undefined> {
   auth?: AuthContext;
   elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
-  errors?: readonly ErrorContract[];
+  errors?: TErrors | undefined;
   notifyPromptListChanged?: () => void;
   notifyResourceListChanged?: () => void;
   notifyResourceUpdated?: (uri: string) => void;
@@ -166,10 +166,10 @@ interface MockContextOptions {
 
 | Option | Effect |
 |:-------|:-------|
-| _(none)_ | Minimal context — `ctx.state` operations throw without `tenantId`; `ctx.elicit`/`ctx.progress` are `undefined` |
+| _(none)_ | Working `ctx.state` on tenant `'default'`; `ctx.elicit`/`ctx.progress` are `undefined` |
 | `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. |
+| `errors` | Attaches a typed `ctx.fail` against the contract — same wiring the production handler factory uses. Pass `myTool.errors` directly; the return type narrows to `HandlerContext<ReasonOf<…>>`, so the context is assignable to that definition's handler parameter. |
 | `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 |
@@ -178,9 +178,28 @@ interface MockContextOptions {
 | `progress` | Populates `ctx.progress` with real state-tracking implementation (see below) |
 | `requestId` | Overrides `ctx.requestId` (default: `'test-request-id'`) |
 | `signal` | Overrides `ctx.signal` — useful for cancellation testing |
-| `tenantId` | Sets `ctx.tenantId` and enables `ctx.state` operations with in-memory storage |
+| `tenantId` | Scopes `ctx.state` to a specific tenant. Defaults to `'default'` — the value stdio (and HTTP with `MCP_AUTH_MODE=none`) resolves |
 | `uri` | Sets `ctx.uri` for resource handler testing |
 
+### Mock state
+
+`ctx.state` is a real `StorageService` over an `InMemoryProvider` — the production storage path, not a `Map`. A test therefore sees the same rules a deployed server enforces:
+
+- **Keys** match `^[a-zA-Z0-9_.\-/]+$` and may not contain `..`. Colons are rejected, so `cache:v1:abc` throws `McpError(ValidationError)` in the test exactly as it would in a deployment; use `cache/v1/abc`.
+- **TTL** is honored. An entry written with `{ ttl: 30 }` reads back as `null` once 30 seconds elapse — drive the clock with `vi.useFakeTimers()` to assert expiry.
+- **`getMany` / `setMany` / `deleteMany` / `list`** validate every key and prefix, and `list` paginates with the same opaque cursors.
+- **Cancellation** applies: once `ctx.signal` aborts, state operations reject.
+
+```ts
+const ctx = createMockContext();
+
+await ctx.state.set('cache/v1/abc', { hits: 1 }, { ttl: 30 });
+await expect(ctx.state.get('cache/v1/abc')).resolves.toEqual({ hits: 1 });
+await expect(ctx.state.set('cache:v1:abc', {})).rejects.toThrow(McpError);
+```
+
+Reach for `createInMemoryStorage()` when a service takes a `StorageService` directly — it builds the same pair.
+
 ### Mock progress
 
 When `progress: true`, `ctx.progress` is a real state-tracking object — not `vi.fn()` spies. It maintains internal state accessible via inspection properties:
@@ -396,7 +415,7 @@ describe('myTool with service', () => {
 
 - Re-init services with `initMyService()` (or equivalent) in `beforeEach` when tests share a module-level singleton.
 - Vitest runs test files in separate workers — parallel file execution is safe by default.
-- Use `createMockContext({ tenantId })` whenever the handler accesses `ctx.state` — omitting `tenantId` causes `ctx.state` to throw.
+- Pass `createMockContext({ tenantId })` when a test needs a specific tenant; omitting it scopes state to `'default'`, not to a broken state surface.
 
 ---
 
@@ -503,3 +522,5 @@ it('survives fuzz testing', async () => {
 | `adversarialArbitrary()` / `ADVERSARIAL_STRINGS` | Targeted injection sets (prototype pollution probes, control characters, oversized payloads). |
 
 `FuzzOptions`: `numRuns` (default 50), `numAdversarial` (default 30), `seed` (reproducibility), `timeout` (per-call ms, default 5000), `ctx` (`MockContextOptions` for stateful handlers).
+
+`report.leaks` looks for a stack frame or a server-side path in what a client can observe — the `code`, `message`, and `data` of the thrown `McpError`. Strings the input itself supplied are removed before that check, so naming the offending value in error data (`throw validationError(msg, { key })`) never registers as a leak: the client sent those bytes and learns nothing from seeing them again.

package/skills/api-utils/SKILL.md

@@ -4,7 +4,7 @@ description: >
   API reference for all utilities exported from `@cyanheads/mcp-ts-core/utils`. Use when looking up utility method signatures, options, peer dependencies, or usage patterns.
 metadata:
   author: cyanheads
-  version: "2.5"
+  version: "2.6"
   audience: external
   type: reference
 ---
@@ -15,6 +15,8 @@ Utility exports from `@cyanheads/mcp-ts-core/utils`. Utilities with complex APIs
 
 **Tier 3** = optional peer dependency. Install as needed (e.g., `bun add js-yaml`). All Tier 3 methods are **async** (lazy-load deps on first call).
 
+**Context parameters.** Every helper below that takes a `context` accepts the handler `Context` as well as a `RequestContext` bag — pass `ctx` straight through, no slicing.
+
 ## References
 
 | Reference | Path | Covers |
@@ -29,7 +31,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`, `expectedStatuses?: number[]` (listed non-2xx statuses logged at `debug` not `error`, still thrown), and `signal?: AbortSignal` (external cancellation). On a non-2xx, `error.data` carries `status`/`body` plus the legacy `statusCode`/`responseBody` aliases (identical values; consolidating in a future major). 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. **Error/log redaction:** URLs written into thrown errors and log lines are reduced to `origin + pathname` — the query string (where API keys commonly ride: `?api-key=…`, `?api_key=…`) never reaches the client or the logs. The actual request still uses the full URL. |
+| `fetchWithTimeout` | `(url, timeoutMs, context, options?: FetchWithTimeoutOptions) -> Promise<Response>` | Wraps `fetch` with `AbortController` timeout. `timeoutMs` bounds the **whole exchange**: on a 2xx carrying a body the returned `Response` is a passthrough wrapper that keeps the deadline armed until the body closes, errors, or is cancelled, so a stalled stream rejects the caller's `.text()`/`.json()` with the same `Timeout` error the header phase raises. `status`, `statusText`, `headers`, `url`, `redirected`, and `type` carry across the wrapper; the original body is locked by it, and bodyless/null-body responses (HEAD, 204/205/304) come back untouched. `FetchWithTimeoutOptions` extends `RequestInit` (minus `signal`) and adds `rejectPrivateIPs?: boolean`, `expectedStatuses?: number[]` (listed non-2xx statuses logged at `debug` not `error`, still thrown), `errorBodyLimit?: number` (bytes of a non-2xx body kept, default `500`), and `signal?: AbortSignal` (external cancellation). On a non-2xx, `error.data` carries `status`/`body` plus the legacy `statusCode`/`responseBody` aliases (identical values; consolidating in a future major); a body over `errorBodyLimit` is captured from both ends — 40% head, 60% tail, joined by `…[N bytes elided]…` — so a diagnostic behind a boilerplate preamble survives the cap, while a body still streaming at the 16 KiB scan ceiling stays head-only with a trailing `…`. 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. **Error/log redaction:** URLs written into thrown errors and log lines are reduced to `origin + pathname` — the query string (where API keys commonly ride: `?api-key=…`, `?api_key=…`) never reaches the client or the logs. The actual request still uses the full URL. |
 | `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. Honors an upstream `Retry-After` on `data.retryAfter` (delta-seconds or HTTP-date) over exponential backoff, capped at `maxDelayMs`; a requested wait beyond the cap fails fast rather than sleeping. 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`. `error.data` carries `status`/`body` plus the legacy `statusCode`/`responseBody` aliases (identical values), so a consumer can classify either helper's error without knowing which raised it. 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-utils/references/parsing.md

@@ -10,8 +10,9 @@ All parsers are **Tier 3** — lazy-load their peer dependency on first call. Al
 
 - Singleton instances exported alongside classes
 - `<think>...</think>` blocks at the start of input are automatically stripped and logged at `debug` level (except `dateParser` and `pdfParser`)
-- All `context?: RequestContext` parameters are optional (synthetic context created if omitted)
-- Errors throw `McpError` — never return error values
+- Every `context?` parameter is optional (synthetic context created if omitted) and accepts the handler `Context` as well as a `RequestContext` bag
+- Input budgets are opt-in: a parser is unbounded unless the caller passes `maxBytes`, which then rejects an over-budget input with `ValidationError` (`reason: 'parser_input_too_large'`). `DEFAULT_TEXT_PARSER_MAX_BYTES` (1 MiB) and `DEFAULT_BINARY_PARSER_MAX_BYTES` (25 MiB) are exported as starting points, not applied defaults
+- Errors throw `McpError` — never return error values. The message is `<summary>: <library message>`, so it carries the underlying parser's diagnostic; `data` carries only `{ reason }`, and the input sample and stack stay on `cause`
 
 ---
 

package/skills/setup/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Post-init orientation for an MCP server built on @cyanheads/mcp-ts-core. Use after running `@cyanheads/mcp-ts-core init` to understand the project structure, conventions, and skill sync model. Also use when onboarding to an existing project for the first time.
 metadata:
   author: cyanheads
-  version: "1.8"
+  version: "1.9"
   audience: external
   type: workflow
 ---
@@ -27,8 +27,8 @@ What `init` actually creates:
 CLAUDE.md                                       # Agent protocol — Claude Code
 AGENTS.md                                       # Agent protocol — other agents (Codex, Cursor, etc.)
 package.json                                    # Starter deps + scripts (placeholders substituted on init)
-tsconfig.json                                   # TypeScript config
-tsconfig.build.json                             # Build-only TS config
+tsconfig.json                                   # Typecheck config — covers src/ and tests/, emits nothing
+tsconfig.build.json                             # Build config — emits src/ to dist/, tests excluded
 vitest.config.ts                                # Test runner config
 biome.json                                      # Lint + format config
 devcheck.config.json                            # Which devcheck steps to run
@@ -57,6 +57,9 @@ tests/
   tools/echo.tool.test.ts                       # Starter tests (one per echo definition)
   resources/echo.resource.test.ts
   prompts/echo.prompt.test.ts
+  smoke/definitions.smoke.test.ts               # Every shipped definition executed once
+  integration/echo-contract.int.test.ts         # The echo tool driven through the production surfaces
+  fuzz/echo-tool.fuzz.test.ts                   # Property-based coverage, via the fast-check dev dep
 ```
 
 Add these as needed:

package/skills/techniques/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Catalog of reusable response- and data-shaping techniques for MCP servers built on `@cyanheads/mcp-ts-core` — overflow handling, payload shaping, retrieval patterns. Use when a tool's payload is too large, awkwardly shaped, or expensive to retrieve and you want a proven pattern instead of inventing one. Each technique has a self-contained reference under `references/`.
 metadata:
   author: cyanheads
-  version: "0.2"
+  version: "0.3"
   audience: external
   type: reference
 ---

package/skills/techniques/references/outline-on-overflow.md

@@ -84,7 +84,7 @@ export const getLabel = tool('get_label', {
 
 - `budget` — serialized-byte threshold (default `DEFAULT_OUTLINE_BUDGET_BYTES`). A helper argument, **not** an env var: a deploy-tunable threshold would drift a tool's output *shape* across environments.
 - `extract` — custom section extractor. Default: one section per top-level key, sized by `JSON.stringify(value).length`. Override only when "section" means something other than a top-level key.
-- `notice` — custom re-call notice builder. Default names the three largest sections as examples.
+- `notice` — custom re-call notice builder, called as `(sections, budget)`. The default's worked example names the **largest section that fits the budget**, with its byte size inline; when no single section fits it says so and points at narrowing the request instead of naming a section. Naming the largest sections would hand the agent the most expensive retrieval available — the one most likely to blow the same budget the outline exists to enforce.
 
 The flow:
 
@@ -93,6 +93,8 @@ The flow:
 3. **Over budget, ≥ 2 sections** → the outline (sections sorted largest-first). The agent re-calls with `sections: [...]`.
 4. **Over budget, < 2 sections** → `full` anyway (nothing to pick between). A single section that *alone* exceeds budget is a known limitation — sub-section outlining is out of scope.
 
+The budget bounds the **disclosure**, not the selection. `selectSections` returns whatever the agent named, so a selection over several sections — or one section larger than the budget — comes back whole. That is deliberate: the agent asked for those sections by name, and truncating the answer is the thing this technique exists to avoid. The default notice reports each example's size so the selection can be sized before it is made.
+
 ## Re-retrieval — why the selection call is stateless
 
 The re-call is **self-contained**, so nothing is stored between the outline call and the selection call:

package/templates/AGENTS.md

@@ -104,7 +104,7 @@ export const itemData = resource('inventory://{itemId}', {
   params: z.object({ itemId: z.string().describe('Item identifier') }),
   auth: ['inventory:read'],
   async handler(params, ctx) {
-    const item = await ctx.state.get(`item:${params.itemId}`);
+    const item = await ctx.state.get(`item/${params.itemId}`);
     if (!item) throw notFound(`Item ${params.itemId} not found`, { itemId: params.itemId });
     return item;
   },

package/templates/CLAUDE.md

@@ -104,7 +104,7 @@ export const itemData = resource('inventory://{itemId}', {
   params: z.object({ itemId: z.string().describe('Item identifier') }),
   auth: ['inventory:read'],
   async handler(params, ctx) {
-    const item = await ctx.state.get(`item:${params.itemId}`);
+    const item = await ctx.state.get(`item/${params.itemId}`);
     if (!item) throw notFound(`Item ${params.itemId} not found`, { itemId: params.itemId });
     return item;
   },

package/templates/Dockerfile

@@ -51,8 +51,13 @@ COPY package.json bun.lock ./
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
+# `--omit=peer` drops the framework's optional peer tiers (test runner, service
+# SDKs, parsers) that Bun would otherwise auto-install. Anything this server
+# actually imports belongs in its own `dependencies`, so nothing needed at
+# runtime is lost. The OTEL step below carries the same flag — without it, that
+# install re-resolves the graph and pulls every optional peer back in.
 RUN --mount=type=cache,target=/root/.bun/install/cache \
-    bun install --production --frozen-lockfile --ignore-scripts
+    bun install --production --omit=peer --frozen-lockfile --ignore-scripts
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # These are not bundled by default to keep the base image lean. Enable at build time
@@ -60,7 +65,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add --omit=dev --ignore-scripts @hono/otel \
+      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
         @opentelemetry/instrumentation-http \
         @opentelemetry/exporter-metrics-otlp-http \
         @opentelemetry/exporter-trace-otlp-http \

package/templates/_tsconfig.build.json

@@ -1,4 +1,9 @@
 {
   "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "noEmit": false
+  },
+  "include": ["src/**/*"],
   "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
 }

package/templates/_tsconfig.json

@@ -1,12 +1,14 @@
 {
   "extends": "@cyanheads/mcp-ts-core/tsconfig.base.json",
   "compilerOptions": {
-    "rootDir": "src",
+    "rootDir": ".",
     "outDir": "dist",
+    "noEmit": true,
+    "tsBuildInfoFile": ".tsbuildinfo",
     "paths": {
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src/**/*"],
+  "include": ["src/**/*", "tests/**/*"],
   "exclude": ["node_modules", "dist"]
 }

package/templates/package.json

@@ -70,6 +70,7 @@
     "@types/node": "26.1.1",
     "@vitest/coverage-istanbul": "4.1.10",
     "depcheck": "^1.4.7",
+    "fast-check": "^4.9.0",
     "ignore": "^7.0.6",
     "tsc-alias": "^1.9.1",
     "typescript": "^7.0.2",

package/templates/tests/prompts/echo.prompt.test.ts

@@ -7,9 +7,10 @@ import { describe, expect, it } from 'vitest';
 import { echoPrompt } from '@/mcp-server/prompts/definitions/echo.prompt.js';
 
 describe('echoPrompt', () => {
-  it('generates a user message with the echoed text', () => {
-    const args = echoPrompt.args.parse({ message: 'hello world' });
-    const messages = echoPrompt.generate(args);
+  it('generates a user message with the echoed text', async () => {
+    const args = echoPrompt.args!.parse({ message: 'hello world' });
+    // `generate` may be async — await covers both shapes.
+    const messages = await echoPrompt.generate(args);
     expect(messages).toHaveLength(1);
     expect(messages[0]).toMatchObject({
       role: 'user',

package/templates/tests/resources/echo.resource.test.ts

@@ -10,13 +10,21 @@ import { echoResource } from '@/mcp-server/resources/definitions/echo.resource.j
 describe('echoResource', () => {
   it('echoes the message from params', async () => {
     const ctx = createMockContext();
-    const params = echoResource.params.parse({ message: 'hello world' });
+    const params = echoResource.params!.parse({ message: 'hello world' });
     const result = await echoResource.handler(params, ctx);
     expect(result).toEqual({ message: 'hello world' });
   });
 
-  it('lists available resources', () => {
-    const listing = echoResource.list!();
+  it('lists available resources', async () => {
+    // `list` receives the SDK's request-handler extra, not a Context, and may be
+    // async — a minimal literal is enough for a listing that ignores it.
+    const extra = {
+      signal: new AbortController().signal,
+      requestId: 'test',
+      sendNotification: () => Promise.resolve(),
+      sendRequest: () => Promise.resolve({} as never),
+    };
+    const listing = await echoResource.list!(extra);
     expect(listing.resources).toHaveLength(1);
     expect(listing.resources[0]).toMatchObject({
       uri: 'echo://hello',