@cyanheads/mcp-ts-core 0.13.5 → 0.13.7

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.13.5
+**Version:** 0.13.7
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revisions 2026-07-28 and 2025-*)
 **Zod:** ^4.6.5
@@ -247,7 +247,7 @@ export const myTool = tool('my_tool', {
 **`format`**: Maps output to MCP `content[]`. Different clients forward different surfaces to the agent — some (Claude Code) read `structuredContent` from `output`, others (Claude Desktop) read `content[]` from `format()`. `format()` is the markdown twin of `structuredContent`, not a reduced summary.
 
 - **Parity is lint-enforced.** Every terminal field in `output` must appear in `format()`'s rendered text (via sentinel injection), or the `format-parity` rule fails `bun run lint:mcp` / `devcheck`.
-- **Primary fix:** render the missing field in `format()`. Use `z.discriminatedUnion` for list/detail variants — each branch is validated separately.
+- **Primary fix:** render the missing field in `format()`. For list/detail variants, declare one flat `z.object` with a `kind` discriminator and presence-based optional arms, rendered by independent `if` blocks — `tool()` rejects a `z.discriminatedUnion` output root.
 - **Escape hatch:** if the schema was over-typed for a genuinely dynamic upstream API, relax it (`z.object({}).passthrough()`) — passthrough still flows data to `structuredContent`.
 - **Fallback:** omit `format` for JSON stringify. Additional formatters in `/utils`: `markdown()` (builder), `diffFormatter` (async), `tableFormatter`, `treeFormatter`.
 
@@ -323,7 +323,7 @@ Opt-in domain-specific logging. Methods: `debug`, `info`, `notice`, `warning`, `
 
 ### `ctx.state`
 
-Tenant-scoped KV. Accepts any serializable value — no manual `JSON.stringify`/`JSON.parse` needed.
+Tenant-scoped KV. Accepts any JSON-serializable value — no manual `JSON.stringify`/`JSON.parse` needed — and reads return its JSON form (a `Date` comes back as its ISO string, a `Map` as `{}`), never the object that was written. A `bigint`, a cyclic reference, or a top-level `undefined`, function, or symbol rejects with `McpError(SerializationError)` before anything is written.
 
 ```ts
 await ctx.state.set('item/123', { name: 'Widget', count: 42 });
@@ -378,7 +378,7 @@ See `api-context` skill for full details.
 
 ## Error Handling
 
-**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, recovery, retryable?, severity? }]` to `tool()` / `resource()`. Handler gets `ctx.fail(reason, msg?, data?)` typed against the reason union — typos fail at compile time. Runtime auto-populates `data.reason` for observability; linter enforces conformance against the handler body. `recovery` is required (≥5 words, lint-validated) — the single source of truth for the wire hint. Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire (framework mirrors `data.recovery.hint` into `content[]` text); override with explicit `{ recovery: { hint: '...' } }` when runtime context matters. Optional `severity` (`debug`/`info`/`notice`/`warning`) logs a modeled outcome below `error` — tools only, logging only: the wire envelope, the span status, and the `mcp.tool.*` metrics are untouched.
+**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` to `tool()` / `resource()`. Handler gets `ctx.fail(reason, msg?, data?)` typed against the reason union — typos fail at compile time. Runtime auto-populates `data.reason` for observability; linter enforces conformance against the handler body. `recovery` is required (≥5 words, lint-validated) — the single source of truth for the wire hint. Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire (framework mirrors `data.recovery.hint` into `content[]` text); override with explicit `{ recovery: { hint: '...' } }` when runtime context matters. Optional `severity` (`debug`/`info`/`notice`/`warning`) logs a modeled outcome below `error` — tools only, logging only: the wire envelope, the span status, and the `mcp.tool.*` metrics are untouched. Optional `thrownBy: 'service'` marks an entry the service layer produces, so `error-contract-unthrown` skips it while still checking the handler's own reasons — lint-only metadata, nothing at runtime reads it.
 
 ```ts
 errors: [
@@ -420,7 +420,7 @@ For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { se
 
 **Error-path parity.** Tool errors: `content[]` carries `Error: <message>`, then `Recovery: <hint>` when the hint says something the message does not already contain, then a closing `(reason … · not retryable)` for whichever of `data.reason` / `data.retryable` is present; the numeric code and `data.issues` stay JSON-only. `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope. An argument rejection is one of them: `-32602` with `data.issues`, plus `data.reason: 'invalid_arguments'` and a hint synthesized from the issues and the root schema — never a tool-declared `reason`, since the handler never ran. `client_capability_missing` is the second framework-owned reason: a `ctx.requestInput` return a 2025-era connection cannot serve is refused before any wire traffic as `-32600` carrying that reason and a hint naming the capability.
 
-**Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`, `error-contract-unthrown` (a declared reason no literal `ctx.fail`/`ctx.recoveryFor` in the handler names). See `api-linter` skill.
+**Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`, `error-contract-unthrown` (a declared reason no literal `ctx.fail`/`ctx.recoveryFor` in the handler names, unless marked `thrownBy: 'service'`), `error-contract-recovery-unforwarded` (a `ctx.fail` site carrying neither `ctx.recoveryFor('<reason>')` nor its own `recovery` key, so the declared hint reaches neither client surface). See `api-linter` skill.
 
 See `api-errors` skill for the full pattern-matching table, error code reference, and detailed examples.
 
@@ -483,7 +483,7 @@ describe('myTool', () => {
 
 **`createMockContext` options:** `createMockContext()` (state included), `{ tenantId: 'test-tenant' }` (explicit tenant; defaults to `'default'`, as stdio resolves it), `{ errors: myTool.errors }` (typed `ctx.fail`), `{ inputResponses }` / `{ requestState }` (seed `ctx.inputs` to drive a multi-round-trip handler's second round directly), plus `auth`, `sessionId`, `signal`, `requestId`, `uri`, and the four `notify*` callbacks.
 
-**`ctx.state` in tests is the production path.** The mock backs it with a real `StorageService` over an `InMemoryProvider`, so key validation (`[a-zA-Z0-9_.\-/]+` — colons rejected) and TTL expiry behave exactly as they do in a deployment. Passing `errors` narrows the return type to `HandlerContext<ReasonOf<…>>`, which is what a definition declaring a contract types its handler's `ctx` as — so `definition.handler(input, ctx)` typechecks.
+**`ctx.state` in tests is the production path.** The mock backs it with a real `StorageService` over an `InMemoryProvider`, so key validation (`[a-zA-Z0-9_.\-/]+` — colons rejected), the JSON round-trip of every value, and TTL expiry behave exactly as they do in a deployment. Passing `errors` narrows the return type to `HandlerContext<ReasonOf<…>>`, which is what a definition declaring a contract types its handler's `ctx` as — so `definition.handler(input, ctx)` typechecks.
 
 **HTTP/session fixtures:** `createFetchMock(routes)` provides a strict fetch-compatible fake with ordered routes, captured `Request` objects, one-shot responses, and optional global install/restore. `createMockSession(options)` returns `{ sessionId, tenantId, ctx }` for handlers that branch on durable HTTP session identity.
 

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.13.5
+**Version:** 0.13.7
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0 (protocol revisions 2026-07-28 and 2025-*)
 **Zod:** ^4.6.5
@@ -247,7 +247,7 @@ export const myTool = tool('my_tool', {
 **`format`**: Maps output to MCP `content[]`. Different clients forward different surfaces to the agent — some (Claude Code) read `structuredContent` from `output`, others (Claude Desktop) read `content[]` from `format()`. `format()` is the markdown twin of `structuredContent`, not a reduced summary.
 
 - **Parity is lint-enforced.** Every terminal field in `output` must appear in `format()`'s rendered text (via sentinel injection), or the `format-parity` rule fails `bun run lint:mcp` / `devcheck`.
-- **Primary fix:** render the missing field in `format()`. Use `z.discriminatedUnion` for list/detail variants — each branch is validated separately.
+- **Primary fix:** render the missing field in `format()`. For list/detail variants, declare one flat `z.object` with a `kind` discriminator and presence-based optional arms, rendered by independent `if` blocks — `tool()` rejects a `z.discriminatedUnion` output root.
 - **Escape hatch:** if the schema was over-typed for a genuinely dynamic upstream API, relax it (`z.object({}).passthrough()`) — passthrough still flows data to `structuredContent`.
 - **Fallback:** omit `format` for JSON stringify. Additional formatters in `/utils`: `markdown()` (builder), `diffFormatter` (async), `tableFormatter`, `treeFormatter`.
 
@@ -323,7 +323,7 @@ Opt-in domain-specific logging. Methods: `debug`, `info`, `notice`, `warning`, `
 
 ### `ctx.state`
 
-Tenant-scoped KV. Accepts any serializable value — no manual `JSON.stringify`/`JSON.parse` needed.
+Tenant-scoped KV. Accepts any JSON-serializable value — no manual `JSON.stringify`/`JSON.parse` needed — and reads return its JSON form (a `Date` comes back as its ISO string, a `Map` as `{}`), never the object that was written. A `bigint`, a cyclic reference, or a top-level `undefined`, function, or symbol rejects with `McpError(SerializationError)` before anything is written.
 
 ```ts
 await ctx.state.set('item/123', { name: 'Widget', count: 42 });
@@ -378,7 +378,7 @@ See `api-context` skill for full details.
 
 ## Error Handling
 
-**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, recovery, retryable?, severity? }]` to `tool()` / `resource()`. Handler gets `ctx.fail(reason, msg?, data?)` typed against the reason union — typos fail at compile time. Runtime auto-populates `data.reason` for observability; linter enforces conformance against the handler body. `recovery` is required (≥5 words, lint-validated) — the single source of truth for the wire hint. Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire (framework mirrors `data.recovery.hint` into `content[]` text); override with explicit `{ recovery: { hint: '...' } }` when runtime context matters. Optional `severity` (`debug`/`info`/`notice`/`warning`) logs a modeled outcome below `error` — tools only, logging only: the wire envelope, the span status, and the `mcp.tool.*` metrics are untouched.
+**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` to `tool()` / `resource()`. Handler gets `ctx.fail(reason, msg?, data?)` typed against the reason union — typos fail at compile time. Runtime auto-populates `data.reason` for observability; linter enforces conformance against the handler body. `recovery` is required (≥5 words, lint-validated) — the single source of truth for the wire hint. Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire (framework mirrors `data.recovery.hint` into `content[]` text); override with explicit `{ recovery: { hint: '...' } }` when runtime context matters. Optional `severity` (`debug`/`info`/`notice`/`warning`) logs a modeled outcome below `error` — tools only, logging only: the wire envelope, the span status, and the `mcp.tool.*` metrics are untouched. Optional `thrownBy: 'service'` marks an entry the service layer produces, so `error-contract-unthrown` skips it while still checking the handler's own reasons — lint-only metadata, nothing at runtime reads it.
 
 ```ts
 errors: [
@@ -420,7 +420,7 @@ For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { se
 
 **Error-path parity.** Tool errors: `content[]` carries `Error: <message>`, then `Recovery: <hint>` when the hint says something the message does not already contain, then a closing `(reason … · not retryable)` for whichever of `data.reason` / `data.retryable` is present; the numeric code and `data.issues` stay JSON-only. `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope. An argument rejection is one of them: `-32602` with `data.issues`, plus `data.reason: 'invalid_arguments'` and a hint synthesized from the issues and the root schema — never a tool-declared `reason`, since the handler never ran. `client_capability_missing` is the second framework-owned reason: a `ctx.requestInput` return a 2025-era connection cannot serve is refused before any wire traffic as `-32600` carrying that reason and a hint naming the capability.
 
-**Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`, `error-contract-unthrown` (a declared reason no literal `ctx.fail`/`ctx.recoveryFor` in the handler names). See `api-linter` skill.
+**Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`, `error-contract-unthrown` (a declared reason no literal `ctx.fail`/`ctx.recoveryFor` in the handler names, unless marked `thrownBy: 'service'`), `error-contract-recovery-unforwarded` (a `ctx.fail` site carrying neither `ctx.recoveryFor('<reason>')` nor its own `recovery` key, so the declared hint reaches neither client surface). See `api-linter` skill.
 
 See `api-errors` skill for the full pattern-matching table, error code reference, and detailed examples.
 
@@ -483,7 +483,7 @@ describe('myTool', () => {
 
 **`createMockContext` options:** `createMockContext()` (state included), `{ tenantId: 'test-tenant' }` (explicit tenant; defaults to `'default'`, as stdio resolves it), `{ errors: myTool.errors }` (typed `ctx.fail`), `{ inputResponses }` / `{ requestState }` (seed `ctx.inputs` to drive a multi-round-trip handler's second round directly), plus `auth`, `sessionId`, `signal`, `requestId`, `uri`, and the four `notify*` callbacks.
 
-**`ctx.state` in tests is the production path.** The mock backs it with a real `StorageService` over an `InMemoryProvider`, so key validation (`[a-zA-Z0-9_.\-/]+` — colons rejected) and TTL expiry behave exactly as they do in a deployment. Passing `errors` narrows the return type to `HandlerContext<ReasonOf<…>>`, which is what a definition declaring a contract types its handler's `ctx` as — so `definition.handler(input, ctx)` typechecks.
+**`ctx.state` in tests is the production path.** The mock backs it with a real `StorageService` over an `InMemoryProvider`, so key validation (`[a-zA-Z0-9_.\-/]+` — colons rejected), the JSON round-trip of every value, and TTL expiry behave exactly as they do in a deployment. Passing `errors` narrows the return type to `HandlerContext<ReasonOf<…>>`, which is what a definition declaring a contract types its handler's `ctx` as — so `definition.handler(input, ctx)` typechecks.
 
 **HTTP/session fixtures:** `createFetchMock(routes)` provides a strict fetch-compatible fake with ordered routes, captured `Request` objects, one-shot responses, and optional global install/restore. `createMockSession(options)` returns `{ sessionId, tenantId, ctx }` for handlers that branch on durable HTTP session identity.
 

package/README.md

@@ -1,12 +1,12 @@
 <div align="center">
   <h1>@cyanheads/mcp-ts-core</h1>
-  <p><b>Agent-native TypeScript framework for building MCP servers. Includes runtime infrastructure and agent skills for building, testing, and shipping servers.</b></p>
-  <p>Give your agent the infrastructure, patterns, and skills to build and ship your server.</p>
+  <p><b>Agent-native TypeScript framework for building MCP servers.</b></p>
+  <p>Runtime infrastructure for your server, and the agent skills to build, test, and ship it.</p>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.13.5-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2026--07--28-8A2BE2.svg?style=flat-square)](https://modelcontextprotocol.io/specification/2026-07-28)
+[![Version](https://img.shields.io/badge/Version-0.13.7-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2026--07--28-8A2BE2.svg?style=flat-square)](https://modelcontextprotocol.io/specification/2026-07-28)
 
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
@@ -16,17 +16,17 @@
 
 ---
 
-## Build AI tools for anything you can describe.
+## Build AI tools for anything you can describe
 
-Connect an API, a dataset, or a workflow to an AI agent through the Model Context Protocol (MCP). Your project holds the domain code; `@cyanheads/mcp-ts-core` provides the auth, storage, logging, and deployment underneath it.
+Connect an API, a dataset, or a workflow to an AI agent through the Model Context Protocol (MCP). Your project holds the domain code; `@cyanheads/mcp-ts-core` handles the auth, storage, logging, and transports underneath it.
 
-**Agent-native means your agent knows what to do.** Every scaffold includes framework documentation and Agent Skills: reusable workflows for designing tools, writing tests, reviewing security, and publishing releases. You decide what the server should do; your agent has the patterns and checks to help implement it.
+**Agent-native.** Every scaffold ships the framework reference and a set of Agent Skills: workflows for designing tools, writing tests, reviewing security, and cutting releases. You decide what the server does; your agent follows the skills to build it.
 
-**The framework stays a dependency.** Infrastructure fixes arrive through package upgrades — run the `maintenance` skill and your agent updates core, pulls the latest skills, and integrates them into your project.
+**The framework stays a dependency.** Infrastructure fixes arrive as package upgrades. Run the `maintenance` skill and your agent bumps core, syncs the latest skills, and adopts what changed.
 
 ## Quick start
 
-Servers can run on Bun, Node.js 24 or later, or Cloudflare Workers.
+Servers run on Bun, Node.js 24+, or Cloudflare Workers.
 
 ```bash
 bunx @cyanheads/mcp-ts-core init my-mcp-server
@@ -34,17 +34,15 @@ cd my-mcp-server
 bun install
 ```
 
-Open the project in Claude Code, Codex, or your preferred agent and give it a concrete starting point:
+The scaffold includes a source tree, build and test configuration, `CLAUDE.md`/`AGENTS.md`, Agent Skills, and plugin metadata for Claude Code and Codex. Open it in Claude Code, Codex, or another agent and describe what you want:
 
 > Build an MCP server for my team's inventory API. We need to find products, check stock across warehouses, investigate stock movements, and record adjustments and transfers. Let's get started.
 
-The scaffold includes a source tree, build and test configuration, `CLAUDE.md`/`AGENTS.md`, Agent Skills, and plugin metadata for Claude Code and Codex.
-
-Already have a TypeScript project? Install the framework directly with `bun add @cyanheads/mcp-ts-core` and register your definitions with `createApp()`.
+Already have a TypeScript project? Run `bun add @cyanheads/mcp-ts-core` and register your definitions with `createApp()`.
 
 ## A tool is a schema and a function
 
-Here's a complete server that searches a small catalog. To try it in the scaffolded project, replace `src/index.ts` with:
+This is a complete server that searches a three-item catalog. To try it, replace the scaffold's `src/index.ts` with it:
 
 ```ts
 import { createApp, tool, z } from '@cyanheads/mcp-ts-core';
@@ -79,7 +77,7 @@ bun run rebuild
 bun run start:http
 ```
 
-Connect your MCP client to `http://127.0.0.1:3010/mcp` (Streamable HTTP), or configure stdio with `bun /absolute/path/to/dist/index.js`.
+Point your MCP client at `http://127.0.0.1:3010/mcp` (Streamable HTTP), or have the client launch it over stdio with `bun /absolute/path/to/dist/index.js`.
 
 ## What comes with it
 
@@ -91,13 +89,13 @@ Connect your MCP client to `http://127.0.0.1:3010/mcp` (Streamable HTTP), or con
 | Run locally or host a service | stdio and HTTP on Bun/Node.js; a separate entry point for Cloudflare Workers |
 | Understand failures and catch mistakes | Structured logs, optional OpenTelemetry, definition linting, contract tests, and fuzz testing |
 
-Optional integrations such as DuckDB, Supabase, and the OpenTelemetry SDK are peer dependencies, installed when you need them.
+Optional integrations (DuckDB, Supabase, the OpenTelemetry SDK) are peer dependencies; install them when you need them.
 
 ## Give agents useful results
 
-Use `enrichment` and `ctx.enrich()` for result context such as totals, applied filters, and empty-result notices. Declare failures and recovery guidance in `errors`, then throw with the typed `ctx.fail()`. Both contracts are visible to clients before a call.
+Two declared contracts shape what an agent gets back. `enrichment` carries success-path context (totals, the parsed query, empty-result notices), populated with `ctx.enrich()`. `errors` lists each expected failure with its recovery guidance, and the handler throws one with the typed `ctx.fail()`.
 
-Here, `runSearch(query, limit)` returns `{ items, total, parsed }` (matches, total before the limit, and parsed query), or `null` if the index is unavailable:
+`runSearch(query, limit)` stands in for your search backend. It returns `{ items, total, parsed }`, or `null` when the index is down:
 
 ```ts
 import { createApp, tool, z } from '@cyanheads/mcp-ts-core';
@@ -143,13 +141,13 @@ const search = tool('search', {
 await createApp({ tools: [search] });
 ```
 
-Enrichment and error contracts are advertised through `tools/list` and checked by the definition linter. `ctx.recoveryFor()` includes the declared recovery hint in the error response.
+Both contracts are advertised in `tools/list`, so clients see them before calling, and the definition linter checks the handler against them. `ctx.recoveryFor()` adds the declared recovery hint to the error response.
 
 ### Same data across client surfaces
 
-MCP hosts differ in what they expose to the agent: some use `content[]`, some use `structuredContent`, and some use both. The framework keeps tool-result data in sync across both surfaces, so the agent receives the same information whichever one its host exposes. `structuredContent` carries structured JSON; `content[]` carries the same data as text.
+MCP hosts differ in which part of a tool result they hand the agent: `structuredContent` (JSON), `content[]` (text), or both. The framework fills both with the same data, so the agent sees the same result on any host.
 
-`format()` controls the text representation, and the format-parity linter enforces that every output field is represented. Without a custom formatter, the framework uses JSON text. Declared enrichment is mirrored into both surfaces automatically. For example, this formatter presents the item names as a markdown list:
+`format()` renders the text side; without one, `content[]` gets JSON. The format-parity lint rule fails `lint:mcp` if any output field is missing from the rendered text. Enrichment needs no `format()` entry, because the framework adds it to both surfaces. This formatter renders the items as a markdown list:
 
 ```ts
 format: (result) => [{
@@ -162,7 +160,7 @@ format: (result) => [{
 
 ### Resources
 
-Resources expose data at a URI. This definition delegates the lookup to your own `getItem()` service:
+Resources expose data at a URI. This one reads from your own `getItem()` service:
 
 ```ts
 import { resource, z } from '@cyanheads/mcp-ts-core';
@@ -183,7 +181,7 @@ Everything registers through `createApp()` in your entry point:
 ```ts
 await createApp({
   name: 'my-mcp-server',
-  version: '0.1.0',
+  title: 'my-mcp-server', // display name in client UIs
   tools: allToolDefinitions,
   resources: allResourceDefinitions,
   prompts: allPromptDefinitions,
@@ -191,16 +189,17 @@ await createApp({
 });
 ```
 
-It also works on Cloudflare Workers with `createWorkerHandler()` — same definitions, different entry point.
+On Cloudflare Workers, `createWorkerHandler()` takes the same definitions from a separate entry point.
 
 ## Runtime and integration details
 
-- **Auth and storage:** Declare `auth: ['scope']` on a definition to check access before dispatch. Choose JWT or OAuth authentication. Tenant-scoped `ctx.state` supports in-memory, filesystem, Supabase, and Cloudflare D1/KV/R2 storage; select the backend through configuration.
-- **Client interaction:** Return `ctx.requestInput(...)` to request confirmation, model sampling, or the client's roots. The handler runs again with responses available on `ctx.inputs`.
-- **Protocol compatibility:** HTTP supports the 2026-07-28 revision's per-request `_meta` envelope and session-based 2025-era clients. The SDK's compatibility layer handles input requests for older clients.
-- **Server presentation:** `instructions` provides guidance during initialization without repeating it in every tool description. Identity fields such as `title`, `websiteUrl`, `description`, and `icons` populate client server information, the `/.well-known/mcp.json` server card, and the HTTP landing page.
-- **Definition checks:** `lint:mcp` checks names, schemas, scopes, annotations, format parity, and JSON Schema portability at build time. These checks do not run at server startup.
-- **DataCanvas:** An optional DuckDB workspace for SQL queries across API results and CSV/Parquet/JSON exports. Agents can share a workspace through an opaque canvas token. Enable it with `CANVAS_PROVIDER_TYPE=duckdb` and install `@duckdb/node-api`; it requires Bun or Node.js. See [brapi-mcp-server](https://github.com/cyanheads/brapi-mcp-server#working-with-dataframes) for a walkthrough of loading API results into a dataframe and querying them with SQL.
+- **Auth and storage:** Declare `auth: ['scope']` on a definition and the scope is checked, under JWT or OAuth, before the handler runs. `ctx.state` is tenant-scoped storage over in-memory, filesystem, Supabase, or Cloudflare D1/KV/R2, chosen by config.
+- **Client interaction:** Return `ctx.requestInput(...)` to ask the user for input, the client's model for a sample, or the client for its roots. The handler runs again with the answers on `ctx.inputs`.
+- **Protocol compatibility:** HTTP serves 2026-07-28 clients (per-request `_meta` envelope) and session-based 2025-era clients. The SDK's compatibility layer handles input requests for the older ones.
+- **Server presentation:** `instructions` gives the model server-wide guidance once, at `initialize`, instead of in every tool description. Identity fields (`title`, `websiteUrl`, `description`, `icons`) populate the client's server info, the `/.well-known/mcp.json` server card, and the HTTP landing page.
+- **Definition checks:** `lint:mcp` checks names, schemas, scopes, annotations, format parity, and JSON Schema portability. It runs at build time, never at startup, so a new rule can't break a deployed server.
+- **DataCanvas:** An optional DuckDB workspace where agents run SQL across staged API results and export CSV, Parquet, or JSON. Agents share a workspace by passing its canvas token. Enable it with `CANVAS_PROVIDER_TYPE=duckdb` and `@duckdb/node-api` (Bun or Node.js only). [brapi-mcp-server](https://github.com/cyanheads/brapi-mcp-server#working-with-dataframes) walks through loading API results into a dataframe and querying it.
+- **Mirror:** The `/mirror` module keeps a persistent local copy of a bulk upstream dataset in embedded SQLite with an optional FTS5 index, so tools query it locally instead of paging the live API on every call. You write the `sync` ingester and the schema; the framework handles storage, resumable initial loads, and incremental refreshes. Bun or Node.js only (`better-sqlite3` is an optional peer on Node). [faa-aircraft-registry-mcp-server](https://github.com/cyanheads/faa-aircraft-registry-mcp-server) serves the full FAA registry this way.
 
 See the [framework reference](CLAUDE.md) for configuration and handler patterns, and the [observability guide](docs/telemetry/observability.md) for Pino logging and OpenTelemetry traces and metrics.
 
@@ -221,14 +220,14 @@ my-mcp-server/
       prompts/definitions/                # Prompt definitions (.prompt.ts)
   package.json
   tsconfig.json                           # extends @cyanheads/mcp-ts-core/tsconfig.base.json
-  CLAUDE.md / AGENTS.md                   # Point to core's CLAUDE.md / AGENTS.md for framework docs
+  CLAUDE.md / AGENTS.md                   # Server conventions; points to core's framework reference
 ```
 
-Framework infrastructure lives in `node_modules`; your source tree contains the server's definitions, configuration, and domain services.
+Framework infrastructure lives in `node_modules`; your source tree holds the server's definitions, configuration, and domain services.
 
 ## Configuration
 
-All core config is Zod-validated from environment variables. Server-specific config uses a separate Zod schema with lazy parsing.
+Core config comes from environment variables, validated with Zod. Server-specific variables get their own schema, parsed lazily so Workers can inject env at request time.
 
 | Variable | Description | Default |
 |:---------|:------------|:--------|
@@ -240,7 +239,7 @@ All core config is Zod-validated from environment variables. Server-specific con
 | `STORAGE_PROVIDER_TYPE` | `in-memory`, `filesystem`, `supabase`, `cloudflare-d1`/`kv`/`r2` | `in-memory` |
 | `CANVAS_PROVIDER_TYPE` | `none` or `duckdb` (optional peer dependency `@duckdb/node-api`) | `none` |
 | `OTEL_ENABLED` | Enable OpenTelemetry | `false` |
-| `OPENROUTER_API_KEY` | OpenRouter LLM API key | — |
+| `OPENROUTER_API_KEY` | API key for the optional OpenRouter LLM provider (`/services`) | — |
 
 See [CLAUDE.md/AGENTS.md](CLAUDE.md) for the full configuration reference.
 
@@ -250,7 +249,7 @@ See [CLAUDE.md/AGENTS.md](CLAUDE.md) for the full configuration reference.
 
 | Function | Purpose |
 |:---------|:--------|
-| `createApp(options)` | Bun or Node.js server — handles full lifecycle |
+| `createApp(options)` | Bun or Node.js server; manages startup and shutdown |
 | `createWorkerHandler(options)` | Cloudflare Workers — returns an `ExportedHandler` |
 
 ### Builders
@@ -265,7 +264,7 @@ See [CLAUDE.md/AGENTS.md](CLAUDE.md) for the full configuration reference.
 
 ### Context
 
-Handlers receive a shared `Context`, with typed helpers for declared enrichment and error contracts:
+Tool and resource handlers receive a `Context`. `ctx.enrich` and `ctx.fail` are typed against the definition's declared contracts:
 
 | Property | Type | Description |
 |:---------|:-----|:------------|
@@ -276,7 +275,7 @@ Handlers receive a shared `Context`, with typed helpers for declared enrichment
 | `ctx.enrich` | `Enrich` / `TypedEnrich<E>` | Add declared result context to structured output and text content |
 | `ctx.content` | `ContentCollect` | Attach image/audio blocks to `content[]` — `content.image(data, mimeType)`, `content.audio(...)`, or a raw block |
 | `ctx.fail` | `(reason, msg?, data?) => McpError` | Creates an error for `throw ctx.fail(...)`; available with a declared `errors` contract |
-| `ctx.recoveryFor` | `(reason) => object` | Resolves a declared recovery hint to `{ recovery: { hint } }` — spread into `ctx.fail`'s data argument |
+| `ctx.recoveryFor` | `(reason) => object` | Resolves a declared recovery hint to `{ recovery: { hint } }`, for `ctx.fail`'s data argument |
 | `ctx.signal` | `AbortSignal` | Cancellation signal |
 | `ctx.notifyResourceUpdated` | `Function?` | Notify subscribed clients a resource changed |
 | `ctx.notifyResourceListChanged` | `Function?` | Notify clients the resource list changed |
@@ -298,6 +297,7 @@ import { checkScopes } from '@cyanheads/mcp-ts-core/auth';
 import { markdown, fetchWithTimeout } from '@cyanheads/mcp-ts-core/utils';
 import { OpenRouterProvider, GraphService } from '@cyanheads/mcp-ts-core/services';
 import type { DataCanvas, CanvasInstance } from '@cyanheads/mcp-ts-core/canvas';
+import { defineMirror, sqliteMirrorStore } from '@cyanheads/mcp-ts-core/mirror';
 import { validateDefinitions } from '@cyanheads/mcp-ts-core/linter';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
 import { mcpTest, toolContractSuite } from '@cyanheads/mcp-ts-core/testing/vitest';
@@ -308,21 +308,23 @@ See [CLAUDE.md/AGENTS.md](CLAUDE.md) for the complete exports reference.
 
 ## Examples
 
-The `examples/` directory contains a reference server consuming core through public exports, demonstrating core patterns:
+`examples/` holds a reference server built only on the public exports. `examples/index.ts` (Node/Bun) and `examples/worker.ts` (Cloudflare Workers) register the same `definitions/index.ts` barrels.
 
-| Tool | Pattern |
-|:-----|:--------|
-| `template_echo_message` | Basic tool with `format`, `auth` |
-| `template_cat_fact` | External API call, error factories |
-| `template_madlibs_elicitation` | `ctx.requestInput` / `ctx.inputs` for multi-round-trip input |
-| `template_image_test` | Image content blocks |
-| `template_data_explorer` | MCP Apps with a linked HTML UI resource |
+| Kind | Name | Pattern |
+|:-----|:-----|:--------|
+| Tool | `template_echo_message` | `errors[]` contract with `ctx.fail`, `inputAliases`, full-fidelity `format()` |
+| Tool | `template_cat_fact` | `fetchWithTimeout`, a typed not-found contract, enrichment echo |
+| Tool | `template_image_test` | `ctx.content.image` |
+| Tool | `template_madlibs_elicitation` | `return ctx.requestInput`, a declined-input contract with `severity` |
+| Tool | `template_data_explorer` | `appTool`/`appResource`, host theming, `cacheHint` |
+| Resource | `echo://{message}` | Templated resource |
+| Resource | `ui://template-data-explorer/app.html` | UI resource paired with `template_data_explorer` |
+| Prompt | `code_review` | `completable()` argument, `code` argument |
 
 ## Testing
 
 ```ts
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
-import { mcpTest, toolContractSuite } from '@cyanheads/mcp-ts-core/testing/vitest';
 import { myTool } from '@/mcp-server/tools/definitions/my-tool.tool.js';
 
 const ctx = createMockContext();
@@ -330,11 +332,11 @@ const input = myTool.input.parse({ query: 'test' });
 const result = await myTool.handler(input, ctx);
 ```
 
-`createMockContext()` provides a recording `log`, a working `state`, and a `signal`. State runs on a real `StorageService` over an in-memory provider — the same key validation and TTL expiry a deployed server applies — scoped to tenant `'default'` unless `{ tenantId }` says otherwise. Pass `{ errors: myTool.errors }` for a typed `ctx.fail` matching the definition's contract, and `{ inputResponses, requestState }` to drive a multi-round-trip handler into its second round.
+`createMockContext()` gives you a recording `log`, a `signal`, and a `state` backed by a real `StorageService` over an in-memory provider, so key validation, TTL expiry, and the JSON round-trip of stored values behave as they do in production: a `Date` reads back as its ISO string, and a value JSON cannot encode rejects. It uses tenant `'default'` unless you pass `{ tenantId }`. Pass `{ errors: myTool.errors }` for a typed `ctx.fail`, or `{ inputResponses, requestState }` to start a multi-round-trip handler at its second round.
 
-`/testing` also exports `createMockSession()` for session-bound contexts, `createFetchMock()` for upstream HTTP boundaries, and `runToolContract()` to drive a definition through schema, handler, formatting, and error-envelope checks. `/testing/vitest` adds the `mcpTest` fixtures (`ctx`, `session`, `fetchMock`, `storage`) and `toolContractSuite()`.
+`/testing` also exports `createMockSession()` for session-bound contexts, `createFetchMock()` as a strict fake for upstream HTTP, and `runToolContract()`, which runs a definition through schema, handler, formatting, and error-envelope checks. `/testing/vitest` adds the `mcpTest` fixtures (`ctx`, `session`, `fetchMock`, `storage`) and `toolContractSuite()`.
 
-For fuzz testing, `/testing/fuzz` uses `fast-check` to generate valid inputs from Zod schemas and adversarial payloads that probe for crashes, data leaks, and prototype pollution:
+`/testing/fuzz` uses `fast-check` to generate valid inputs from your Zod schemas plus adversarial payloads, then checks for crashes, stack-trace leaks, and prototype pollution:
 
 ```ts
 import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';
@@ -345,13 +347,13 @@ expect(report.leaks).toHaveLength(0);
 expect(report.prototypePollution).toBe(false);
 ```
 
-Also exports `fuzzResource`, `fuzzPrompt`, `zodToArbitrary`, and `ADVERSARIAL_STRINGS` for custom property-based tests.
+It also exports `fuzzResource`, `fuzzPrompt`, `zodToArbitrary`, and `ADVERSARIAL_STRINGS` for custom property-based tests.
 
 ## Documentation
 
-- **[CLAUDE.md/AGENTS.md](CLAUDE.md)** — Framework reference: exports catalog, patterns, Context interface, error codes, auth, config, testing. Ships in the npm package and is auto-accessible in your project after `init`.
-- **[docs/telemetry/](docs/telemetry/)** — OpenTelemetry: full catalog of spans, metrics, and attributes the framework emits ([observability.md](docs/telemetry/observability.md)), plus an example Grafana dashboard and vendor-agnostic query recipes for Datadog, New Relic, Honeycomb ([dashboards.md](docs/telemetry/dashboards.md)).
-- **[CHANGELOG.md](CHANGELOG.md)** — Version history. Each entry includes a summary, migration notes, and links to commits/issues. Directory-based changelogs that work well for Agents. Entries include agent-specific notes per version as needed.
+- **[CLAUDE.md/AGENTS.md](CLAUDE.md)**: the framework reference, covering exports, patterns, `Context`, error codes, auth, config, and testing. It ships in the npm package, so your agent reads it from `node_modules` after `init`.
+- **[docs/telemetry/](docs/telemetry/)**: every span, metric, and attribute the framework emits ([observability.md](docs/telemetry/observability.md)), plus an example Grafana dashboard and query recipes for Datadog, New Relic, and Honeycomb ([dashboards.md](docs/telemetry/dashboards.md)).
+- **[CHANGELOG.md](CHANGELOG.md)**: version history, indexing one file per release under `changelog/`. Each has a summary, migration notes, and links to commits and issues; releases that need downstream changes carry `agent-notes` for the `maintenance` skill to act on.
 
 ## Development
 
@@ -360,6 +362,7 @@ bun run rebuild        # clean + build (scripts/clean.ts + scripts/build.ts)
 bun run devcheck       # full gate: lint/format, typecheck, MCP defs, framework antipatterns, docs/skills/changelog sync, audit, outdated, secrets/TODO scan
 bun run lint:mcp       # validate MCP definitions against spec
 bun run test:all       # rebuild + coverage + Node.js + Workers + integration
+bun run test:package   # pack the tarball and consume it as an external project would
 ```
 
 ## License

package/biome.json

@@ -1,12 +1,12 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.13/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.14/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",
     "useIgnoreFile": true
   },
   "files": {
-    "includes": ["src/**", "scripts/**", "tests/**", "*.json", "*.js", "*.ts"]
+    "includes": ["src/**", "scripts/**", "tests/**", "examples/**", "*.json", "*.js", "*.ts"]
   },
   "formatter": {
     "enabled": true,

package/changelog/0.13.x/0.13.6.md

@@ -0,0 +1,49 @@
+---
+summary: "A ctx.fail site that never forwards its declared recovery now warns, an errors[] entry can mark itself thrownBy: 'service' so the unthrown rule skips it, capped-list-no-truncation stops firing on value bounds like max_depth_km, and devcheck.config.json can carry the truncation allowlist."
+breaking: false
+security: false
+agent-notes: |
+  Four adoption steps for a consumer upgrading from 0.13.5.
+
+  1. `error-contract-recovery-unforwarded` is new and fires on the next
+     `devcheck` / `lint:mcp`: a literal `ctx.fail('<reason>', …)` site carrying
+     neither `ctx.recoveryFor('<reason>')` nor its own `recovery` key. Clear it
+     by spreading `...ctx.recoveryFor('<reason>')` into the data argument, by
+     passing the resolver as that argument, or with an explicit
+     `recovery: { hint }` when the hint needs runtime context.
+  2. An `errors[]` reason the service layer produces takes `thrownBy: 'service'`,
+     which is what `error-contract-unthrown` reads to skip it. Prefer it over
+     moving the handler's literal `ctx.fail` out of scan range — that silences
+     the rule for the whole definition, handler-local reasons included.
+  3. Declare `lint.truncationAllowlist` in `devcheck.config.json` in place of
+     `MCP_LINT_TRUNCATION_ALLOWLIST` on each script entry, and drop the env var
+     from the `devcheck` and `lint:mcp` scripts once the key is in place. A
+     scaffolded config predating this release has no `lint` key; add it.
+  4. Drop any `truncationAllowlist` entry added only to silence
+     `capped-list-no-truncation` on a value-bound `max_*` input — those no
+     longer warn.
+---
+
+# 0.13.6 — 2026-09-19
+
+## Added
+
+- **Lint rule `error-contract-recovery-unforwarded`** (warning, [#255](https://github.com/cyanheads/mcp-ts-core/issues/255)) — one diagnostic per literal `ctx.fail('<reason>', …)` site carrying neither `ctx.recoveryFor('<reason>')` nor its own `recovery` key, so the declared hint reaches neither client surface. A site whose only resolver names a different reason warns too, naming both.
+- **`thrownBy: 'service'` on an `errors[]` entry** ([#462](https://github.com/cyanheads/mcp-ts-core/issues/462)) — lint-only metadata marking a reason produced below the handler, so `error-contract-unthrown` skips it while the handler's own reasons keep being checked. The entry stays typed, advertised, and thrown exactly as an unmarked one.
+- **`lint.truncationAllowlist` in `devcheck.config.json`** ([#388](https://github.com/cyanheads/mcp-ts-core/issues/388)) — read by `scripts/lint-mcp.ts` and forwarded as `LintInput.truncationAllowlist`, so one project-owned declaration covers every entrypoint that shells out to the linter. Takes an array of tool names or `false`; precedence is explicit `LintInput`, then the config file, then `MCP_LINT_TRUNCATION_ALLOWLIST`.
+
+## Changed
+
+- **The scaffold's `echo` tool forwards its declared recovery** ([#255](https://github.com/cyanheads/mcp-ts-core/issues/255)) — `templates/src/mcp-server/tools/definitions/echo.tool.ts` spreads `ctx.recoveryFor('empty_message')`, so a new server starts from the shape the rule asks for.
+- Skill versions: `add-service` 1.10 → 1.11, `add-tool` 2.28 → 2.29, `api-errors` 1.14 → 1.15, `api-linter` 1.16 → 1.17.
+
+## Fixed
+
+- **`capped-list-no-truncation`'s `max_` arm requires the counted noun to name a returned list** ([#345](https://github.com/cyanheads/mcp-ts-core/issues/345)) — a depth-0 array in `output` (plural-insensitive, a trailing `_count` stripped first) or a generic result container (`results`, `records`, `items`, `rows`, `hits`, `entries`, `matches`, `count`, `page`, `docs`). Value bounds (`max_depth_km`, `maxLat`, `max_date`) and work budgets (`max_court_lookups`, `maxCharacters`) stop warning; `limit`, `<noun>_limit`, and the page-size idioms are unchanged.
+- **`error-contract-unthrown` skips a definition whose `ctx.recoveryFor(` takes a non-literal first argument** ([#462](https://github.com/cyanheads/mcp-ts-core/issues/462)), as it already did for `ctx.fail(` — unknown reasons are in play either way. Its message now names all three fixes.
+- **The `format-parity` diagnostic no longer points authors at a `z.discriminatedUnion` output** ([#268](https://github.com/cyanheads/mcp-ts-core/issues/268)), which `tool()` rejects before any lint rule runs. The "Primary fix" line names a flat `z.object` with a `kind` discriminator and presence-based optional arms, rendered by independent `if` blocks.
+- **The `sanitizeHtml` event-handler property matches only inside a tag** ([#463](https://github.com/cyanheads/mcp-ts-core/issues/463)) — the whole-string `/\bon\w+\s*=/` also matched inert text such as `on0=`, failing roughly once in 300 runs. `on0=` and `<p>onclick=1</p>` are pinned as `examples`; the sanitizer itself is unchanged.
+
+## Dependencies
+
+- `@biomejs/biome` 2.5.13 → 2.5.14, `fast-check` ^4.10.0 → ^4.10.1.

package/changelog/0.13.x/0.13.7.md

@@ -0,0 +1,77 @@
+---
+summary: "Server stack traces no longer reach clients through McpError.data, in-memory storage round-trips values as JSON like every other provider, OTEL_EXPORTER_OTLP_ENDPOINT is honored, and the unused MCP client, ext-apps, and dotenv dependencies are gone."
+breaking: true
+security: true
+agent-notes: |
+  Adoption steps for a consumer upgrading from 0.13.6.
+
+  1. The framework no longer installs `@modelcontextprotocol/client` (now a
+     devDependency), `@modelcontextprotocol/ext-apps`, or `dotenv`. A server
+     whose own code or tests import any of them without declaring it adds it —
+     tests that drive a `Client` need `bun add -d @modelcontextprotocol/client@^2.0.0`.
+  2. Raise the server's `zod` to `^4.6.5`, the new peer floor, so a single copy
+     installs alongside the framework.
+  3. Stored values now round-trip as JSON on every provider, `in-memory` and
+     `createMockContext().state` included. Fix code and tests that expect the
+     written object back by identity, or a `Date` / `Map` to survive: a `Date`
+     reads back as its ISO string, so validate reads with `z.string()`, not
+     `z.date()`. A value JSON cannot encode now throws
+     `McpError(SerializationError)` on write, and fails a whole `setMany`.
+  4. `McpError.data` from `ErrorHandler.handleError` / `tryCatch` no longer
+     carries `originalStack` or `causeChain`; anything reading them there reads
+     the log record instead (`rootCause` and `originalMessage` stay). A prompt
+     whose `generate()` throws a non-`McpError` now answers with code and
+     message only.
+  5. With `OTEL_ENABLED=true`, `OTEL_EXPORTER_OTLP_ENDPOINT` alone now exports
+     traces and metrics to `<base>/v1/traces` and `<base>/v1/metrics`. OTel log
+     records are never exported, `OTEL_METRICS_EXPORTER` / `OTEL_LOGS_EXPORTER`
+     are not consulted, and a deployment with no endpoint set exports nothing
+     (it used to send metrics and logs to `localhost:4318`). Confirm a
+     deployment that sets only the base endpoint wants traces sent there.
+  6. The `filesystem` provider writes its envelope as compact single-line JSON.
+     Existing indented files still read; update anything that inspects the files
+     on disk and expects the old formatting.
+  7. `.env` loads through `process.loadEnvFile()` with the same no-override
+     rule, but a `.env` that exists and cannot be read now fails startup with a
+     `ConfigurationError`.
+  8. Drop `validator` / `@types/validator` if they were installed only for
+     `sanitizeUrl` / `sanitizeNumber`. `sanitizeUrl` now passes single-label
+     hosts such as `localhost` (loopback IP literals always passed); a server
+     that must refuse internal hosts checks the host itself.
+  9. Optional, to match the scaffold: `packageManager` `bun@1.4.2` and
+     `oven/bun:1.4.2` Dockerfile tags. The `maintenance` template review picks up
+     the `templates/CLAUDE.md` edits (the `ctx.state` line, a bounded `limit`).
+---
+
+# 0.13.7 — 2026-09-25
+
+## Changed
+
+- **Stored values round-trip as JSON on every provider** ([#522](https://github.com/cyanheads/mcp-ts-core/issues/522)) — `in-memory`, and so `createMockContext().state`, holds JSON text and parses on each read: a `Date` reads back as its ISO string, a `Map` as `{}`, and a returned object never shares identity with the one written.
+- **The `filesystem` provider writes compact JSON** — the stored envelope is one line; files written by earlier versions still read.
+- **`sanitizeUrl` and `sanitizeNumber` validate without a peer dependency** — built-in checks replace `validator`; `sanitizeNumber` accepts the same plain decimals as before. `sanitizeUrl` now accepts single-label hosts (`localhost`), `_` in host labels, and a trailing-dot host, and refuses a host that parses differently from how it is written (`http://evil.com\@good.com`, which `validator` passed). It stays a format check, not an SSRF guard: loopback and private IP literals pass, as they did before.
+- **Two-segment tool names are scoped to complete-action verbs** ([#248](https://github.com/cyanheads/mcp-ts-core/issues/248)) — `design-mcp-server` and `add-tool` keep `git_pull`-style names, while an object-taking verb (`search`, `get`, `connect`) always carries its noun.
+- **The scaffold's echo app UI follows the host theme** — it reads the MCP Apps style variables over a light/dark baseline. New scaffolds only.
+- **The example server registers through definition barrels** — `examples/index.ts` and `examples/worker.ts` share one `definitions/index.ts` per primitive plus server `instructions`, and `examples/` is now typechecked, linted, and smoke-tested.
+- Skill versions: `add-app-tool` 1.5 → 1.6, `add-prompt` 1.3 → 1.4, `add-provider` 1.1 → 1.2, `add-resource` 1.6 → 1.7, `add-tool` 2.29 → 2.30, `api-canvas` 2.3 → 2.4, `api-config` 1.19 → 1.20, `api-context` 2.5 → 2.6, `api-errors` 1.15 → 1.16, `api-linter` 1.17 → 1.18, `api-telemetry` 1.12 → 1.13, `api-testing` 1.10 → 1.11, `api-utils` 2.11 → 2.12, `code-simplifier` 1.5 → 1.6, `design-mcp-server` 2.28 → 2.29, `git-wrapup` 1.19 → 1.25, `maintenance` 2.8 → 2.9, `orchestrations` 1.10 → 1.11, `polish-docs-meta` 2.17 → 2.18, `release-and-publish` 2.19 → 2.20, `release-pr-review` 1.4 → 1.5, `report-issue-framework` 1.12 → 1.13, `report-issue-local` 1.10 → 1.11, `security-pass` 1.8 → 1.10, `tool-defs-analysis` 1.6 → 1.7.
+
+## Fixed
+
+- **`OTEL_EXPORTER_OTLP_ENDPOINT` is honored** ([#523](https://github.com/cyanheads/mcp-ts-core/issues/523)) — it resolves `<base>/v1/traces` and `<base>/v1/metrics` when the signal-specific variable is unset. `NodeSDK` gets explicit metric readers and an empty log-processor list, so its env defaults no longer export outside the framework config.
+- **Unencodable values are rejected on every provider** ([#539](https://github.com/cyanheads/mcp-ts-core/issues/539)) — a `bigint`, a cyclic reference, or a top-level `undefined`, function, or symbol throws `McpError(SerializationError)` before anything is written; one such value fails a whole `setMany`.
+- **A client that disconnects mid-body is `RequestCancelled`** ([#507](https://github.com/cyanheads/mcp-ts-core/issues/507)) — `httpErrorHandler` resolves the error against the inbound request's signal, so the hang-up logs at info with no stack and answers 499 instead of a `-32004` 504.
+- **The default tenant comes from parsed config** ([#520](https://github.com/cyanheads/mcp-ts-core/issues/520)) — a blank or `${…}` `MCP_AUTH_MODE` on HTTP resolves tenant `'default'`, matching the `none` that config reads it as, instead of leaving `ctx.state` without a tenant.
+- **The shipped `tsconfig.base.json` anchors `outDir` and `@/*` to `${configDir}`** ([#521](https://github.com/cyanheads/mcp-ts-core/issues/521)) — a project extending it without restating them emits into its own `dist/`, never into the installed package; `test:package` checks this on TypeScript 7 and 6.
+- **Partial-success telemetry reads `partialResultSchema()`'s own keys** ([#524](https://github.com/cyanheads/mcp-ts-core/issues/524)) — `mcp.tool.partial_success` and `mcp.tool.batch.*` follow a custom `failedKey` / `succeededKey`, including through `.extend()`, `.pick()`, `.omit()`, and a `.shape` spread.
+- **`logger.close()` runs after a failed telemetry flush** ([#540](https://github.com/cyanheads/mcp-ts-core/issues/540)) — the failure is logged as a warning first, so the final log lines survive an unreachable collector.
+
+## Security
+
+- **Server stack traces no longer reach clients through `McpError.data`** ([#519](https://github.com/cyanheads/mcp-ts-core/issues/519)) — `ErrorHandler.handleError` and `tryCatch` keep `originalStack` and `causeChain` in the log record, and `prompts/get` forwards only the thrown `McpError`'s own `data`.
+
+## Dependencies
+
+- `@modelcontextprotocol/client` ^2.0.0 moves from `dependencies` to `devDependencies`; `@modelcontextprotocol/ext-apps` ^2.0.0 and `dotenv` ^17.4.2 are removed, `dotenv` in favor of `process.loadEnvFile()` ([#525](https://github.com/cyanheads/mcp-ts-core/issues/525)).
+- Peer `zod` ^4.4.3 → ^4.6.5, matching the dependency range; the optional `validator` peer is removed.
+- Dev: `@cloudflare/workers-types` 5.20260910.1 → 5.20260922.1, `@socketsecurity/bun-security-scanner` ^1.1.2 → ^1.1.3, `@supabase/supabase-js` ^2.116.0 → ^2.117.0, `@types/node` 26.5.1 → 26.6.2, `defuddle` ^0.19.3 → ^0.19.4, `fast-check` ^4.10.1 → ^4.10.2, `ignore` ^7.0.9 → ^7.0.10, `openai` ^7.15.0 → ^7.21.0, `repomix` ^1.18.0 → ^1.18.1; `validator`, `@types/validator`, and `bun-types` removed. The `depcheck` script and `package.json` block give way to the list in `devcheck.config.json`.
+- Bun 1.4.0 → 1.4.2 (`packageManager`, Docker base images, and the scaffold, whose `@types/node` and `@socketsecurity/bun-security-scanner` pins follow the framework's).

package/config/tsconfig.base.json

@@ -14,7 +14,7 @@
 
     "esModuleInterop": true,
 
-    "outDir": "../dist",
+    "outDir": "${configDir}/dist",
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
@@ -34,7 +34,7 @@
     "allowJs": false,
 
     "paths": {
-      "@/*": ["../src/*"]
+      "@/*": ["${configDir}/src/*"]
     }
   }
 }

package/dist/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,wEAAwE;AACxE,eAAO,MAAM,cAAc,2BAA2B,CAAC;AACvD,eAAO,MAAM,iBAAiB,QAAkC,CAAC;AAyBjE,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoWd,CAAC;AAGL,QAAA,MAAM,WAAW,kBAAmB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmMrE,CAAC;AAIF;;;;;;;;GAQG;AACH,QAAA,MAAM,WAAW,kBAAmB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAG,IAExE,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuBV,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAErD;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,wEAAwE;AACxE,eAAO,MAAM,cAAc,2BAA2B,CAAC;AACvD,eAAO,MAAM,iBAAiB,QAAkC,CAAC;AA6DjE,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsWd,CAAC;AAGL,QAAA,MAAM,WAAW,kBAAmB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2MrE,CAAC;AAIF;;;;;;;;GAQG;AACH,QAAA,MAAM,WAAW,kBAAmB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAG,IAExE,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuBV,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAErD;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC"}