@cyanheads/mcp-ts-core 0.13.6 → 0.13.8

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.13.6
+**Version:** 0.13.8
 **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
@@ -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 });
@@ -416,7 +416,7 @@ Available factories: `invalidParams`, `invalidRequest`, `notFound`, `forbidden`,
 
 For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { service, data })` from `/utils` — maps the full status table (401/403/408/422/429/5xx) and captures body + `Retry-After`.
 
-**Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: request signal already aborted (→ `RequestCancelled`, outranking the thrown value's own code, `McpError` included) → `McpError` code (preserved as-is) → SDK `ConnectionClosed` (→ `RequestCancelled`) → JS constructor name (`TypeError` → `ValidationError`) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name (→ `Timeout`) → `InternalError` fallback.
+**Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: request signal already aborted (→ `RequestCancelled`, outranking the thrown value's own code, `McpError` included) → `McpError` code (preserved as-is) → SDK `ConnectionClosed` (→ `RequestCancelled`) → engine resource-limit `RangeError` by whole message — stack overflow, maximum string size (→ `InternalError`) → JS constructor name (`SyntaxError` → `ValidationError`; `TypeError` is excluded) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name (→ `Timeout`) → `InternalError` fallback. A result that breaks the definition's own `output` or `enrichment` schema fails as `InternalError` naming that contract, not `ValidationError`.
 
 **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.
 
@@ -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.
 
@@ -520,7 +520,7 @@ Detailed method signatures, options, and examples live in skill files. Read the
 
 Each `framework-skills/<name>/SKILL.md` carries `metadata.version` in frontmatter. The `maintenance` skill's Phase A uses this to sync consumer copies — replaces the **entire skill directory** as one unit. Without a version bump, Phase A skips the skill (content-hash backstop catches drift, but noisier).
 
-**Policy:** Bump `metadata.version` when changing any file under `framework-skills/<name>/` — SKILL.md is the single version knob for the directory. Typo/whitespace fixes exempt. One bump per release cycle suffices. Enforced by `bun run devcheck` (`scripts/check-skill-versions.ts`): a SKILL.md body change vs `HEAD` without a `metadata.version` bump surfaces as a warning; whitespace-only edits never trigger it, and a genuine typo fix opts out via `devcheck.config.json` `skillVersions.ignore`.
+**Policy:** Bump `metadata.version` when changing any file under `framework-skills/<name>/` — SKILL.md is the single version knob for the directory. Typo/whitespace fixes exempt. **Exactly one step per release, however many edits land:** before bumping, compare the version against the last release tag (`git show $(git describe --tags --abbrev=0):framework-skills/<name>/SKILL.md`) and skip the bump when it has already moved. Enforced by `bun run devcheck` (`scripts/check-skill-versions.ts`), both directions as warnings: a SKILL.md body change vs `HEAD` without a `metadata.version` bump while the version still matches the last release tag, and a version more than one step (next minor, or next major at `.0`) past the last release tag. Whitespace-only edits never trigger the first, and a genuine typo fix opts out via `devcheck.config.json` `skillVersions.ignore`.
 
 Skills live in `framework-skills/<name>/SKILL.md`; the full list is discoverable via the agent's skill registry at session start. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, and these are development-time skills, not skills for the agents that use a server. `skills/` stays free for that second kind.
 

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.13.6
+**Version:** 0.13.8
 **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
@@ -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 });
@@ -416,7 +416,7 @@ Available factories: `invalidParams`, `invalidRequest`, `notFound`, `forbidden`,
 
 For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { service, data })` from `/utils` — maps the full status table (401/403/408/422/429/5xx) and captures body + `Retry-After`.
 
-**Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: request signal already aborted (→ `RequestCancelled`, outranking the thrown value's own code, `McpError` included) → `McpError` code (preserved as-is) → SDK `ConnectionClosed` (→ `RequestCancelled`) → JS constructor name (`TypeError` → `ValidationError`) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name (→ `Timeout`) → `InternalError` fallback.
+**Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: request signal already aborted (→ `RequestCancelled`, outranking the thrown value's own code, `McpError` included) → `McpError` code (preserved as-is) → SDK `ConnectionClosed` (→ `RequestCancelled`) → engine resource-limit `RangeError` by whole message — stack overflow, maximum string size (→ `InternalError`) → JS constructor name (`SyntaxError` → `ValidationError`; `TypeError` is excluded) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name (→ `Timeout`) → `InternalError` fallback. A result that breaks the definition's own `output` or `enrichment` schema fails as `InternalError` naming that contract, not `ValidationError`.
 
 **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.
 
@@ -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.
 
@@ -520,7 +520,7 @@ Detailed method signatures, options, and examples live in skill files. Read the
 
 Each `framework-skills/<name>/SKILL.md` carries `metadata.version` in frontmatter. The `maintenance` skill's Phase A uses this to sync consumer copies — replaces the **entire skill directory** as one unit. Without a version bump, Phase A skips the skill (content-hash backstop catches drift, but noisier).
 
-**Policy:** Bump `metadata.version` when changing any file under `framework-skills/<name>/` — SKILL.md is the single version knob for the directory. Typo/whitespace fixes exempt. One bump per release cycle suffices. Enforced by `bun run devcheck` (`scripts/check-skill-versions.ts`): a SKILL.md body change vs `HEAD` without a `metadata.version` bump surfaces as a warning; whitespace-only edits never trigger it, and a genuine typo fix opts out via `devcheck.config.json` `skillVersions.ignore`.
+**Policy:** Bump `metadata.version` when changing any file under `framework-skills/<name>/` — SKILL.md is the single version knob for the directory. Typo/whitespace fixes exempt. **Exactly one step per release, however many edits land:** before bumping, compare the version against the last release tag (`git show $(git describe --tags --abbrev=0):framework-skills/<name>/SKILL.md`) and skip the bump when it has already moved. Enforced by `bun run devcheck` (`scripts/check-skill-versions.ts`), both directions as warnings: a SKILL.md body change vs `HEAD` without a `metadata.version` bump while the version still matches the last release tag, and a version more than one step (next minor, or next major at `.0`) past the last release tag. Whitespace-only edits never trigger the first, and a genuine typo fix opts out via `devcheck.config.json` `skillVersions.ignore`.
 
 Skills live in `framework-skills/<name>/SKILL.md`; the full list is discoverable via the agent's skill registry at session start. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, and these are development-time skills, not skills for the agents that use a server. `skills/` stays free for that second kind.
 

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.6-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.8-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,9 @@ 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 | — |
+| `LOG_TOOL_FAILURE_PAYLOADS` | Log each failed tool call's arguments and result, redacted by key name (a secret inside a free-form value is not caught) | `false` |
+| `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES` | Cap per logged payload, in UTF-8 bytes | `16384` |
+| `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 +251,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 +266,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 +277,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 +299,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 +310,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 +334,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 +349,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 +364,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

@@ -6,7 +6,7 @@
     "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.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).