@cyanheads/mcp-ts-core 0.8.18 → 0.8.20

package/CLAUDE.md

@@ -1,9 +1,28 @@
-# Agent Protocol
+# Developer Protocol
 
-**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.8.18
-**npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) · **Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
+**Package:** `@cyanheads/mcp-ts-core`
+**Version:** 0.8.20
+**Engines:** Bun ≥1.3.0, Node ≥24.0.0
+**MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
+**Zod:** ^4.4.3
+**GitHub:** [cyanheads/mcp-ts-core](https://github.com/cyanheads/mcp-ts-core)
+**npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+**Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
 
-> **Developer note:** Never assume. Read related files and docs before making changes. Read full file content for context. Never edit a file before reading it.
+> **Developer note:** Never assume. Read related files and docs before making changes. Read full file content for context. Never try to edit a file before reading it.
+
+---
+
+## Consumers
+
+This package serves two consumer paths. When making changes, know which audience your change affects:
+
+| Path | On-ramp | Affected by changes to |
+|:--|:--|:--|
+| **Direct package import** — existing project pulls in the package | `bun add @cyanheads/mcp-ts-core` → `import { createApp, tool, z } from '@cyanheads/mcp-ts-core'` | Public API surface (`src/`) — existing consumers feel changes immediately on upgrade |
+| **Init-scaffolded server** — fresh project bootstrapped from this repo's templates | `bunx @cyanheads/mcp-ts-core init [name]` copies `templates/` into the new directory | `templates/` — only affects newly scaffolded servers, not existing ones |
+
+Both paths end up consuming the same public API. The init script bootstraps the project structure: starter `package.json`, `tsconfig`, `biome.json`, `vitest.config.ts`, `.env.example`, `Dockerfile`, `CLAUDE.md`/`AGENTS.md`, and example tool/resource/prompt definitions. Files in `templates/` prefixed with `_` (e.g. `_.gitignore`, `_tsconfig.json`) have the prefix stripped on copy. After init, agents should consult the `setup` skill.
 
 ---
 
@@ -13,7 +32,7 @@
 - **Full-stack observability.** The framework automatically instruments every tool/resource call — OTel span, duration/payload/memory metrics, structured completion log. Use `ctx.log` for additional domain-specific logging within handlers (external API calls, multi-step operations, business events). `requestId`, `traceId`, `tenantId` auto-correlated. No `console` calls.
 - **Unified Context.** Handlers receive `ctx` with logging (`ctx.log`), tenant-scoped storage (`ctx.state`), optional protocol capabilities (`ctx.elicit`, `ctx.sample`), and cancellation (`ctx.signal`).
 - **Decoupled storage.** `ctx.state` for tenant-scoped KV. Never access persistence backends directly.
-- **Canvas tokens are capabilities, not tenant-scoped state.** A `canvasId` is a 10-char URL-safe token; possession grants full read/write/drop on that canvas. Tokens are designed to be shareable — between agents in one session, and across users in single-tenant deployments (stdio, HTTP + `MCP_AUTH_MODE=none`, where every request resolves to `tenantId='default'`). Tools should accept the token in `input` (or omit to create fresh) and return it in `output`; collaboration is opt-in via explicit token exchange. **Do NOT cache canvasIds in `ctx.state` as a "default canvas"** — under shared `tenantId='default'` every concurrent user reads the same cached id and silently collides on one workspace. The same rule applies to any UUID-keyed primitive (datasets, derived row stores): the ID is the access grant, scoping happens by token possession, not by tenant. Public/free deployments of this framework run stateless and auth-mode-`none` — design accordingly.
+- **Canvas tokens are capabilities, not tenant-scoped state.** A `canvasId` is a 10-char URL-safe token; possession grants full read/write/drop on that canvas. Tokens are designed to be shareable — between agents in one session, and across users in single-tenant deployments (see tenant resolution table under `ctx.state`). Tools should accept the token in `input` (or omit to create fresh) and return it in `output`; collaboration is opt-in via explicit token exchange.
 - **Runtime parity.** All features work with `stdio`/`http` and Worker bundle. Guard non-portable deps via `runtimeCaps` from `@cyanheads/mcp-ts-core/utils` — a frozen capability object (`isNode`, `isBun`, `isWorkerLike`, `hasBuffer`, `hasProcess`, etc.) computed once at module load. Prefer runtime-agnostic abstractions (Hono + `@hono/mcp`, Fetch APIs).
 - **Startup validation.** `createApp()` runs the definition linter before proceeding — errors (spec violations) throw `ConfigurationError` and block startup; warnings are logged. Also available standalone via `bun run lint:mcp` and as a devcheck step. Every diagnostic links to the rule reference in `api-linter` skill; see that skill for the full rule catalog.
 - **Elicitation for missing input.** Use `ctx.elicit` when the client supports it.
@@ -151,10 +170,6 @@ src/
 
 **File suffixes:** `.tool.ts` (standard or task), `.resource.ts`, `.prompt.ts`, `.app-tool.ts` (UI-enabled), `.app-resource.ts` (UI resource linked to app tool).
 
-**Scaffold a new server:** `npx @cyanheads/mcp-ts-core init [name]` copies `templates/` into a new project. After running, consult the `setup` skill.
-
-**`templates/` directory:** Scaffolding source for the init CLI. Contents are copied into new consumer servers — includes starter `package.json`, `tsconfig`, `biome.json`, `vitest.config.ts`, `.env.example`, `Dockerfile`, `CLAUDE.md`/`AGENTS.md`, and example tool/resource/prompt definitions. Files prefixed with `_` (e.g. `_.gitignore`, `_tsconfig.json`) are renamed on copy (strip `_` prefix). Changes here affect every newly scaffolded server.
-
 ---
 
 ## Adding a Tool
@@ -199,9 +214,14 @@ export const myTool = tool('my_tool', {
 
 **Schema constraint:** Input/output schemas must use JSON-Schema-serializable Zod types only. The MCP SDK converts schemas to JSON Schema for `tools/list` — non-serializable types (`z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`) cause a hard runtime failure. Use structural equivalents instead (e.g., `z.string()` with `.describe('ISO 8601 date')` instead of `z.date()`). The linter validates this at startup.
 
-**Form-client safety:** Form-based MCP clients (MCP Inspector, web UIs) send optional object fields with empty-string inner values instead of `undefined`. Don't reject with `.min(1)` on optional fields — guard for meaningful values in the handler (`if (input.dateRange?.minDate && input.dateRange?.maxDate)`). Test with both omitted and empty-value payloads. Alternative when schema-level constraints (regex/length) matter enough to surface in the JSON Schema: wrap in a union with a `z.literal('')` sentinel — `z.union([z.literal(''), z.string().regex(...).describe(...)])`. The linter exempts literal variants from `describe-on-fields`; the LLM sees the regex/length via the non-literal branch.
+**Form-client safety:** Form-based clients (MCP Inspector, web UIs) send optional fields as empty strings, not `undefined`. Don't reject with `.min(1)` on optional fields — guard for meaningful values in the handler (`if (input.dateRange?.minDate && input.dateRange?.maxDate)`). Test with both omitted and empty-value payloads. When schema-level constraints (regex/length) need to surface in the JSON Schema, wrap in a union with a `z.literal('')` sentinel: `z.union([z.literal(''), z.string().regex(...).describe(...)])` — the linter exempts the literal variant from `describe-on-fields`.
+
+**`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.
 
-**`format`**: Maps output to MCP `content[]`. Different MCP clients forward different surfaces to the model — some (e.g., Claude Code) read `structuredContent` from `output`, others (e.g., Claude Desktop) read `content[]` from `format()`. **Both must be content-complete** so every client sees the same data — `format()` is the markdown-rendered twin of `structuredContent`, not a separate payload. A thin `format()` (count or title only) leaves `content[]`-only clients blind to data that `structuredContent` clients can see. Enforced at lint time: every terminal field in `output` must appear in `format()`'s rendered text (via sentinel injection), or startup fails with a `format-parity` error. Primary fix: render the missing field in `format()` (use `z.discriminatedUnion` for list/detail variants — each branch is validated separately). Escape hatch: if the output schema was over-typed for a genuinely dynamic upstream API, relax it (`z.object({}).passthrough()`) rather than maintaining aspirational typing — passthrough still flows data to `structuredContent`. Omit `format` entirely for JSON stringify fallback. Additional formatters: `markdown()` (builder), `diffFormatter` (async), `tableFormatter`, `treeFormatter` from `/utils`.
+- **Parity is enforced.** Every terminal field in `output` must appear in `format()`'s rendered text (via sentinel injection), or startup fails with a `format-parity` lint error.
+- **Primary fix:** render the missing field in `format()`. Use `z.discriminatedUnion` for list/detail variants — each branch is validated separately.
+- **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`.
 
 **Task tools:** Add `task: true` for long-running async operations. Framework manages lifecycle: creates task → returns ID immediately → runs handler in background with `ctx.progress` → stores result/error → `ctx.signal` for cancellation. See `add-tool` skill for full example.
 
@@ -396,11 +416,7 @@ For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { se
 
 **Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: `McpError` code (preserved as-is) → JS constructor name (`TypeError` → `ValidationError`) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name → `InternalError` fallback.
 
-**Error-path parity.** Tool errors mirror the success-path `format-parity` invariant — both surfaces clients forward to the agent carry the same payload:
-- `content[]` (read by clients like Claude Desktop) — markdown rendering of the error, with `data.recovery.hint` mirrored into the text when present
-- `structuredContent.error` (read by clients like Claude Code) — JSON `{ code, message, data? }` carrying the error code, message, and any structured data from the thrown `McpError` or `ZodError`
-
-`_meta.error` is **not** emitted on tool errors — error data lives on `structuredContent.error`. Resources re-throw to the SDK, which routes them through the JSON-RPC error envelope (no parity wiring needed there).
+**Error-path parity.** Tool errors apply the same client-surface parity as success: `content[]` carries a markdown rendering with `data.recovery.hint` mirrored in, `structuredContent.error` carries `{ code, message, data? }`. `_meta.error` is not emitted. Resources re-throw to the SDK and route through the JSON-RPC error envelope (no parity wiring there).
 
 The startup linter checks handler bodies for `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, plus contract conformance (`error-contract-conformance` for undeclared non-baseline codes, `error-contract-prefer-fail` for declared codes thrown directly instead of via `ctx.fail`) — all warnings, surfaced in `bun run devcheck`.
 
@@ -423,6 +439,8 @@ Pick one convention per server and stay consistent. Verbs are typically `read`,
 
 **Modes** (`MCP_AUTH_MODE`): `none` (default) | `jwt` (local secret via `MCP_AUTH_SECRET_KEY`) | `oauth` (JWKS via `OAUTH_ISSUER_URL`, `OAUTH_AUDIENCE`). See `api-auth` skill for claims, CORS, and detailed config.
 
+**Granted scopes** are unioned from `scp`, `scope`, and `mcp_tool_scopes` JWT claims. The `mcp_tool_scopes` custom claim is the supported escape hatch for OIDC providers (Authentik, Keycloak < 26.5, Zitadel) that ignore property mappings overriding `scope` in `authorization_code` flow. For deployments where no custom claim can be injected, `MCP_AUTH_DISABLE_SCOPE_CHECKS=true` bypasses both `withRequiredScopes` and `checkScopes` after the auth-context presence check (signature/audience/issuer/expiry validation intact). A `WARNING` is logged at startup whenever the bypass is active.
+
 ---
 
 ## Configuration
@@ -434,7 +452,7 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod. Precedence: `createApp()
 | Category | Key Variables |
 |:---------|:-------------|
 | Transport | `MCP_TRANSPORT_TYPE` (`stdio`\|`http`), `MCP_HTTP_PORT`, `MCP_HTTP_HOST`, `MCP_HTTP_ENDPOINT_PATH` |
-| Auth | `MCP_AUTH_MODE`, `MCP_AUTH_SECRET_KEY`, `OAUTH_*` |
+| Auth | `MCP_AUTH_MODE`, `MCP_AUTH_SECRET_KEY`, `MCP_AUTH_DISABLE_SCOPE_CHECKS`, `OAUTH_*` |
 | Storage | `STORAGE_PROVIDER_TYPE` (`in-memory`\|`filesystem`\|`supabase`\|`cloudflare-r2`\|`cloudflare-kv`\|`cloudflare-d1`) |
 | LLM | `OPENROUTER_API_KEY`, `OPENROUTER_APP_URL/NAME`, `LLM_DEFAULT_*` |
 | Telemetry | `OTEL_ENABLED`, `OTEL_SERVICE_NAME/VERSION`, `OTEL_EXPORTER_OTLP_*` |
@@ -494,7 +512,8 @@ Each `skills/<name>/SKILL.md` carries a `metadata.version` string in its frontma
 
 | Skill | Path | Covers |
 |:------|:-----|:-------|
-| `api-utils` | `skills/api-utils/SKILL.md` | formatting, parsing, security, network, pagination, runtime, scheduling, types, logger, requestContext, errorHandler, telemetry |
+| `api-utils` | `skills/api-utils/SKILL.md` | formatting, parsing, security, network, pagination, runtime, scheduling, types, logger, requestContext, errorHandler, telemetry helpers (`withSpan`, `createCounter`, …) |
+| `api-telemetry` | `skills/api-telemetry/SKILL.md` | OTel catalog: span names, metric names + attributes, completion log fields, env config, runtime support, cardinality rules |
 | `api-services` | `skills/api-services/SKILL.md` | LLM (OpenRouter), Speech (ElevenLabs TTS, Whisper STT), Graph (CRUD, traversal, pathfinding) |
 | `api-context` | `skills/api-context/SKILL.md` | Context interface, createContext, ContextLogger/State/Progress |
 | `api-errors` | `skills/api-errors/SKILL.md` | McpError, JsonRpcErrorCode, error handling patterns |
@@ -535,7 +554,7 @@ Each `skills/<name>/SKILL.md` carries a `metadata.version` string in its frontma
 - **JSDoc:** `@fileoverview` + `@module` required on every file
 - **No fabricated signal:** Don't invent synthetic scores or arbitrary "confidence percentages." Surface real signal.
 - **Builders:** `tool()`/`resource()`/`prompt()` with correct fields (`handler`, `input`, `output`, `format`, `auth`, `args`)
-- **`format()` completeness:** different clients forward different surfaces (Claude Code reads `structuredContent`, Claude Desktop reads `content[]`) — both must carry the same data; `format()` is the markdown twin of `structuredContent`, not a reduced summary
+- **`format()` completeness:** must carry the same data as `output` (parity is lint-enforced — see Adding a Tool)
 - **Auth:** via `auth: ['scope']` on definitions (not HOF wrapper)
 - **Presence checks:** `ctx.elicit`/`ctx.sample` checked before use
 - **Task tools:** use `task: true` flag
@@ -547,14 +566,6 @@ Each `skills/<name>/SKILL.md` carries a `metadata.version` string in its frontma
 
 ---
 
-## Git
-
-**Safety:** NEVER `git stash`. NEVER destructive commands (`reset --hard`, `checkout -- .`, `restore .`, `clean -f`) unless user explicitly requests. Read-only is always safe.
-
-**Commits:** Plain `-m` strings, no heredoc/command substitution. [Conventional Commits](https://www.conventionalcommits.org/): `feat|fix|refactor|chore|docs|test|build(scope): message`. Group related changes atomically.
-
----
-
 ## Commands
 
 | Command | Purpose |
@@ -576,7 +587,9 @@ After `bun update --latest`, run the `maintenance` skill to investigate changelo
 
 ## Changelog
 
-Directory-based, grouped by minor series using the `.x` semver-wildcard convention. Source of truth is `changelog/<major.minor>.x/<version>.md` — one standalone file per released version (e.g. `changelog/0.5.x/0.5.4.md`), shipped in the npm package so agents can read a specific version from `node_modules/@cyanheads/mcp-ts-core/changelog/<major.minor>.x/<version>.md` without parsing a monolithic file. At release time, author the per-version file with a concrete version and date, then run `bun run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited, never renamed, never moved. Read it to remember the frontmatter + section layout when scaffolding a new per-version file.
+Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth is `changelog/<major.minor>.x/<version>.md` — one standalone file per release (e.g. `changelog/0.5.x/0.5.4.md`). Per-version files ship in the npm package so agents can read a specific version directly from `node_modules` without parsing a monolithic file.
+
+At release time, author the per-version file with a concrete version and date, then run `bun run changelog:build` to regenerate the rollup. `changelog/template.md` is a format reference — never edited; consult it for frontmatter and section layout when scaffolding a new file. Be concise and accurate.
 
 `CHANGELOG.md` is a **navigation index**, not a copy of bodies — each entry is a clickable header + one-line summary pulled from the per-version file's frontmatter. Regenerated by `bun run changelog:build`. Devcheck runs `changelog:check` and hard-fails on drift. Never hand-edit `CHANGELOG.md` — edit the per-version file and rerun the build.
 
@@ -584,14 +597,13 @@ Directory-based, grouped by minor series using the `.x` semver-wildcard conventi
 
 ```markdown
 ---
-summary: One-line headline, ≤250 chars, no markdown  # required
-breaking: false                                       # optional, default false
+summary: "One-line headline, ≤250 chars, no markdown"  # required
+breaking: false                                         # optional, default false
+security: false                                         # optional, default false
 ---
 
 # 0.5.4 — 2026-04-20
 
-Optional narrative intro (1-3 sentences).
-
 ## Added
 
 - ...
@@ -601,10 +613,13 @@ Optional narrative intro (1-3 sentences).
 
 | Field | Required | Purpose |
 |:------|:---------|:--------|
-| `summary` | yes | Rollup index line. Max 250 chars, no markdown, single line. Write like a GitHub Release title. |
+| `summary` | yes | Rollup index line. ≤250 chars, no markdown, single line. Write like a GitHub Release title. |
 | `breaking` | no (default `false`) | Flags releases with breaking changes. Renders as `· ⚠️ Breaking` badge in the rollup. Agents running the `maintenance` skill read this to prioritize review. |
+| `security` | no (default `false`) | Flags releases with security fixes. Renders as `· 🛡️ Security` badge in the rollup so users can triage upgrade urgency. Pairs with the `## Security` body section. |
 
-Summary > 250 chars or malformed `breaking` fails `changelog:check`. Missing `summary` emits a warning and renders the rollup entry as header-only.
+When both flags are set, badges render in fixed order: `· ⚠️ Breaking · 🛡️ Security`. Summary > 250 chars or a malformed boolean fails `changelog:check`. Missing `summary` emits a warning and renders the rollup entry as header-only.
+
+**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
 
 Pre-release versions (`0.6.0-beta.1`, `0.6.0-rc.1`, etc.) are consolidated as `##`/`###` sub-headers inside the final version's per-version file (`changelog/0.6.x/0.6.0.md`) when the final ships — they share the final version's frontmatter, no separate files per pre-release.
 
@@ -612,16 +627,4 @@ Pre-release versions (`0.6.0-beta.1`, `0.6.0-rc.1`, etc.) are consolidated as `#
 
 ## Publishing
 
-Run the `release-and-publish` skill — it runs the verification gate (`devcheck`, `rebuild`, `test:all`), pushes commits and tags, and publishes to every applicable destination. The full reference:
-
-```bash
-bun publish --access public
-
-docker buildx build --platform linux/amd64,linux/arm64 \
-  -t ghcr.io/cyanheads/mcp-ts-core:<version> \
-  -t ghcr.io/cyanheads/mcp-ts-core:latest \
-  --push .
-
-mcp-publisher publish
-```
-
+If the user requests it, run the `release-and-publish` skill — it runs the verification gate (`devcheck`, `rebuild`, `test:all`), pushes commits and tags, and publishes to every applicable destination. The full reference:

package/README.md

@@ -15,7 +15,9 @@
 
 ## What is this?
 
-`@cyanheads/mcp-ts-core` is the infrastructure layer for TypeScript MCP servers. Install it as a dependency — don't fork it. You write tools, resources, and prompts; the framework handles transports, auth, storage, config, logging, telemetry, and lifecycle.
+`@cyanheads/mcp-ts-core` is the infrastructure layer for TypeScript MCP servers. Install it as a dependency — don't fork it. Your agent collaborates with you to design and build the tools, resources, and prompts for your server.
+
+The framework handles the plumbing: transports, auth, config, logging, telemetry, & more. Define your domain logic with the builders and let the framework take care of the rest.
 
 ```ts
 import { createApp, tool, z } from '@cyanheads/mcp-ts-core';
@@ -23,15 +25,21 @@ import { createApp, tool, z } from '@cyanheads/mcp-ts-core';
 const greet = tool('greet', {
   description: 'Greet someone by name and return a personalized message.',
   annotations: { readOnlyHint: true },
-  input: z.object({ name: z.string().describe('Name of the person to greet') }),
-  output: z.object({ message: z.string().describe('The greeting message') }),
-  handler: async (input) => ({ message: `Hello, ${input.name}!` }),
+  input: z.object({
+    name: z.string().describe('Name of the person to greet'),
+  }),
+  output: z.object({
+    message: z.string().describe('The greeting message'),
+  }),
+  handler: async (input) => ({
+    message: `Hello, ${input.name}!`,
+  }),
 });
 
 await createApp({ tools: [greet] });
 ```
 
-That's a complete MCP server. Every tool call is automatically logged with duration, payload sizes, memory usage, and request correlation — no instrumentation code needed. `createApp()` handles config parsing, logger init, transport startup, signal handlers, and graceful shutdown.
+That's a complete MCP server. Every tool call is automatically logged with duration, payload sizes, and request correlation — no instrumentation code needed. `createApp()` handles config parsing, logger init, transport startup, signal handlers, and graceful shutdown.
 
 ## Quick start
 
@@ -43,7 +51,7 @@ bun install
 
 You get a scaffolded project with `CLAUDE.md`, Agent Skills, and a `src/` tree ready for your tools. Infrastructure — transports, auth, storage, telemetry, lifecycle, linting — lives in `node_modules`. What's left is domain: which APIs to wrap, which workflows to expose.
 
-Start your coding agent (Claude Code, Codex, Cursor), describe the system you want to expose, and it drives the build. The included skills cover the full cycle: `setup`, `design-mcp-server`, scaffolding, testing, `security-pass`, `release-and-publish`.
+Start your coding agent (i.e. Claude Code, Codex) and describe what you want. The agent knows what to do from there. The included Agent Skills cover the full cycle: `setup`, `design-mcp-server`, scaffolding, testing, `security-pass`, `release-and-publish`, `maintenance`, & more.
 
 ### What you get
 
@@ -58,7 +66,9 @@ export const search = tool('search', {
     query: z.string().describe('Search query'),
     limit: z.number().default(10).describe('Max results'),
   }),
-  output: z.object({ items: z.array(z.string()).describe('Search results') }),
+  output: z.object({
+    items: z.array(z.string()).describe('Search results'),
+  }),
   async handler(input) {
     const results = await doSearch(input.query, input.limit);
     return { items: results };
@@ -73,7 +83,9 @@ import { resource, z } from '@cyanheads/mcp-ts-core';
 
 export const itemData = resource('items://{itemId}', {
   description: 'Retrieve item data by ID.',
-  params: z.object({ itemId: z.string().describe('Item ID') }),
+  params: z.object({
+    itemId: z.string().describe('Item ID'),
+  }),
   async handler(params, ctx) {
     return await getItem(params.itemId);
   },
@@ -96,32 +108,17 @@ It also works on Cloudflare Workers with `createWorkerHandler()` — same defini
 
 ## Features
 
-- **Declarative definitions** — `tool()`, `resource()`, `prompt()` builders with Zod schemas. `appTool()`/`appResource()` add interactive HTML UIs.
+- **Declarative definitions** — `tool()`, `resource()`, `prompt()` builders with Zod schemas; `appTool()`/`appResource()` add interactive HTML UIs.
 - **Unified Context** — one `ctx` for logging, tenant-scoped storage, elicitation, sampling, cancellation, and task progress.
-- **Inline auth** — `auth: ['scope']` on definitions. Framework checks scopes before dispatch — no wrapper code.
+- **Auth** — `auth: ['scope']` on definitions, checked before dispatch (no wrapper code). Modes: `none`, `jwt`, or `oauth` (local secret or JWKS).
 - **Task tools** — `task: true` for long-running ops; framework manages create/poll/progress/complete/cancel.
-- **Definition linter** — validates names, schemas, auth scopes, annotation coherence, and format-parity at startup. Standalone CLI (`lint:mcp`) and devcheck step.
-- **Typed error contracts** — declare `errors: [{ reason, code, when, retryable? }]` on a tool/resource and the handler receives a typed `ctx.fail(reason, …)` keyed against the declared reasons. The contract publishes in `tools/list` so clients preview failure modes; the linter cross-checks the handler body. Error factories (`notFound()`, `httpErrorFromResponse()`, …) for ad-hoc throws; plain `Error` works too — framework auto-classifies.
-- **Multi-backend storage** — `in-memory`, filesystem, Supabase, Cloudflare D1/KV/R2. Swap providers via env var; handlers don't change.
+- **Definition linter** — validates names, schemas, auth scopes, annotations, and format-parity at startup. Standalone via `lint:mcp` or devcheck.
+- **Typed error contracts** — declare `errors: [{ reason, code, when, retryable? }]` and handlers get a typed `ctx.fail(reason, …)`. Contracts publish in `tools/list` so clients preview failure modes; the linter cross-checks the handler. Factories (`notFound()`, `httpErrorFromResponse()`, …) cover ad-hoc throws; plain `Error` auto-classifies.
+- **Multi-backend storage** — `in-memory`, filesystem, Supabase, Cloudflare D1/KV/R2. Swap via env var; handlers don't change.
 - **DataCanvas (optional)** — Tier 3 SQL/analytical workspace backed by DuckDB. Register tabular data from upstream APIs, run SQL across registered tables, export CSV/Parquet/JSON. Token-sharing model (opaque `canvas_id`) for multi-agent collaboration; sliding TTL + per-tenant scoping. Opt-in via `CANVAS_PROVIDER_TYPE=duckdb`; fails closed on Workers.
-- **Pluggable auth** — `none`, `jwt`, or `oauth`. Local secret or JWKS verification.
-- **Observability** — Pino logging, optional OpenTelemetry traces and metrics. Request correlation and tool metrics are automatic.
-- **Local + edge** — same definitions run on stdio, HTTP (Hono), and Cloudflare Workers.
-- **Tiered dependencies** — parsers, OTEL SDK, Supabase, and OpenAI are optional peers. Install what you use.
-- **Agent-first DX** — ships `CLAUDE.md` with the full exports catalog so AI agents ramp up without prompting.
-
-### Storage Behavior Snapshot
-
-Provider behavior is intentionally normalized at the interface, but backend limits still matter:
-
-| Provider | Delete count accuracy | List TTL filtering | Notes |
-|:---------|:----------------------|:-------------------|:------|
-| `in-memory` | Exact | Exact | Volatile process memory |
-| `filesystem` | Exact | Exact | Node/Bun only |
-| `supabase` | Exact | Exact | Requires configured Supabase client |
-| `cloudflare-d1` | Exact | Exact | Workers D1 binding |
-| `cloudflare-kv` | Idempotent API success | Native/eventual | Delete cannot prove prior existence |
-| `cloudflare-r2` | Idempotent API success | Not applied during list | Expired envelopes are removed on read |
+- **Observability** — Pino logging + optional OpenTelemetry traces/metrics. Request correlation and tool metrics automatic.
+- **Tiered dependencies** — parsers, OTEL SDK, Supabase, OpenAI as optional peers. Install what you use.
+- **Agent-first DX** — ships `CLAUDE.md` / `AGENTS.md` with the codebase documented throughout Agent Skills.
 
 ## Server structure
 
@@ -181,7 +178,6 @@ See [CLAUDE.md](CLAUDE.md) for the full configuration reference.
 | `prompt(name, options)` | Define a prompt with `generate(args)` |
 | `appTool(name, options)` | Define an MCP Apps tool with auto-populated `_meta.ui` |
 | `appResource(uriTemplate, options)` | Define an MCP Apps HTML resource with the correct MIME type and `_meta.ui` mirroring for read content |
-| `disabledTool(def, meta)` | Mark a tool present-in-manifest but skipped at registration — clients can't invoke; landing page renders it muted with the operator-facing reason and optional hint. Compose with feature-flag conditionals at definition time. |
 
 ### Context
 
@@ -215,7 +211,7 @@ import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
 import { fuzzTool, fuzzResource, fuzzPrompt } from '@cyanheads/mcp-ts-core/testing/fuzz';
 ```
 
-See [CLAUDE.md](CLAUDE.md) for the complete exports reference.
+See [CLAUDE.md/AGENTS.md](CLAUDE.md) for the complete exports reference.
 
 ## Examples
 
@@ -261,16 +257,18 @@ Also exports `fuzzResource`, `fuzzPrompt`, `zodToArbitrary`, and `ADVERSARIAL_ST
 
 ## Documentation
 
-- **[CLAUDE.md](CLAUDE.md)** — Framework reference: exports catalog, patterns, Context interface, error codes, auth, config, testing. Ships in the npm package.
-- **[CHANGELOG.md](CHANGELOG.md)** — Version history
+- **[CLAUDE.md/AGENTS.md](CLAUDE.md)** — Framework reference: exports catalog, patterns, Context interface, error codes, auth, config, testing. Ships in the npm package.
+- **[docs/telemetry/observability.md](docs/telemetry/observability.md)** — OpenTelemetry catalog: every span, metric, and attribute the framework emits, plus the env vars to wire export.
+- **[docs/telemetry/dashboards.md](docs/telemetry/dashboards.md)** — Example Grafana dashboard JSON and vendor-agnostic query recipes (Datadog, New Relic, Honeycomb).
+- **[CHANGELOG.md](CHANGELOG.md)** — Version history - Directory based for easier parsing by agents. Each entry includes a summary, migration notes, and links to commits/issues.
 
 ## Development
 
 ```bash
 bun run rebuild        # clean + build (scripts/clean.ts + scripts/build.ts)
-bun run devcheck       # lint, format, typecheck, MCP defs, audit, outdated
+bun run devcheck       # full gate: lint/format, typecheck, MCP defs, framework antipatterns, docs/skills/changelog sync, tests, audit, outdated, secrets/TODO scan
 bun run lint:mcp       # validate MCP definitions against spec
-bun run test:all       # vitest (unit + integration)
+bun run test:all       # vitest: unit + Workers pool + integration
 ```
 
 ## Contributing

package/changelog/0.8.x/0.8.19.md

@@ -0,0 +1,33 @@
+---
+summary: "Telemetry visualization docs ([#125](https://github.com/cyanheads/mcp-ts-core/issues/125)) — example Grafana dashboard JSON, vendor-agnostic query recipes, new `api-telemetry` skill. Engines bumped to Bun ≥1.3.0 / Node ≥24.0.0."
+breaking: false
+security: false
+---
+
+# 0.8.19 — 2026-05-08
+
+## Added
+
+- **`docs/telemetry/dashboards.md` + `mcp-ts-core-dashboard.json`** ([#125](https://github.com/cyanheads/mcp-ts-core/issues/125)) — example Grafana dashboard (54 panels, schemaVersion 39) plus an import quickstart and equivalent query recipes for Datadog / NRQL / Honeycomb. Single `$service` template variable, `(?:@[^/]+/)?` regex strips any npm-org prefix, no publisher-specific names. `docs/telemetry/observability.md` cross-links it. Framework-source-only — `docs/` is intentionally not shipped in the npm `dist`.
+- **`api-telemetry` skill** (v1.0) — catalog of every span, metric, attribute, completion-log field, env var, and runtime caveat the framework emits. Cross-linked from `api-utils` (which now scopes to the helper API only) and from CLAUDE.md/AGENTS.md skill index.
+- **Changelog frontmatter `security: boolean`** — pairs with the `## Security` section to render a `🛡️ Security` badge in the rollup. Both flags render in fixed order (`· ⚠️ Breaking · 🛡️ Security`) when set. `scripts/build-changelog.ts` parses and validates `security` like `breaking` (must be literal `true`/`false`).
+- **`init` template substitutions** — `{{MCP_SDK_VERSION}}` and `{{ZOD_VERSION}}` now resolve from the framework `package.json` `dependencies` map. Joins existing `{{PACKAGE_NAME}}` and `{{FRAMEWORK_VERSION}}`.
+
+## Changed
+
+- **Engines bumped:** Bun `>=1.2.0` → `>=1.3.0`, Node `>=22.0.0` → `>=24.0.0`. Mirrored in `templates/package.json` and `skills/polish-docs-meta/references/package-meta.md`.
+- **Docker base image:** `oven/bun:1` → `oven/bun:1.3` (build + runtime stages, root and template Dockerfiles).
+- **CLAUDE.md / AGENTS.md** — restructured: new "Consumers" section explains the package-import vs init-scaffolded paths up front; tool/format guidance condensed; standalone Git section dropped (the global protocol covers it). Now reflects 0.8.19 + Bun ≥1.3.0 / Node ≥24.0.0 in the header.
+- **`changelog/template.md` / `templates/changelog/template.md`** — rewritten authoring guide: bold-the-symbol bullet style, Keep-a-Changelog section order, scaffolded `Deprecated` / `Removed` / `Security` sections (commented out by default).
+- **`README.md`** — leaner feature list, reordered storage detail behind a single `node_modules` link, added cross-links to `docs/telemetry/observability.md` and `dashboards.md`.
+- **Skill bumps:** `setup` 1.6 → 1.7 (rebrands `npx` examples to `bunx`, replaces `{{PACKAGE_NAME}}` placeholder guidance with substituted-name verification, adds `release-and-publish` to the rough progression). `maintenance` 2.0 → 2.1 — Phase C now also resyncs pristine reference files (`templates/changelog/template.md` → consumer `changelog/template.md`) on content-hash mismatch. `report-issue-framework` 1.5 → 1.6, `report-issue-local` 1.4 → 1.5 — terser issue-writing guidance, "cite cross-references once," Bun `1.3.x` examples. `api-utils` 2.1 → 2.2 — telemetry section header points readers to the new `api-telemetry` skill for the catalog.
+- **Keywords:** added `bun`, `mcp-framework`; removed `edge`.
+- **Dependency refresh:**
+  - `@hono/node-server` `^2.0.1` → `^2.0.2`
+  - `@cloudflare/vitest-pool-workers` `^0.16.0` → `^0.16.3`
+  - `@cloudflare/workers-types` `^4.20260506.1` → `^4.20260508.1`
+  - `@hono/otel` `^1.1.1` → `^1.1.2`
+  - `@types/node` `^25.6.0` → `^25.6.2`
+  - `openai` `^6.36.0` → `^6.37.0`
+  - `vite` `8.0.10` → `8.0.11`
+  - `fast-xml-parser` `^5.7.3` (new dev dep)

package/changelog/0.8.x/0.8.20.md

@@ -0,0 +1,26 @@
+---
+summary: "`mcp_tool_scopes` claim union + `MCP_AUTH_DISABLE_SCOPE_CHECKS` bypass ([#128](https://github.com/cyanheads/mcp-ts-core/issues/128)) — operator escape hatches for OIDC providers that can't inject scopes into `scope`."
+breaking: false
+security: false
+---
+
+# 0.8.20 — 2026-05-09
+
+Two operator escape hatches for the standard OIDC reality. Authentik, Keycloak < 26.5, and Zitadel issue `authorization_code` tokens whose `scope` claim is fixed at `openid email profile offline_access` — property mappings can't override it, so per-tool scopes can't be injected the standard way. The framework now reads granted scopes from a 3-claim union (`scp` + `scope` + new `mcp_tool_scopes`), and ships an explicit bypass for deployments where no claim-injection path exists at all.
+
+## Added
+
+- **`mcp_tool_scopes` JWT claim** ([#128](https://github.com/cyanheads/mcp-ts-core/issues/128)) — operator-defined custom claim parsed alongside `scp` and `scope`. Accepts space-delimited string (`"tool:foo:read tool:bar:write"`) or array form. Empty-string entries are dropped; arrays containing any non-string entry cause the claim to be ignored entirely. Documented in the `api-auth` skill as the OIDC operator setup path.
+- **`MCP_AUTH_DISABLE_SCOPE_CHECKS` env var** (`mcpAuthDisableScopeChecks`, default `false`) — when `true`, bypasses both `withRequiredScopes` (declared `auth: [...]`) and `checkScopes` (runtime-computed scopes inside handlers, including tenant patterns like `team:${input.teamId}:write`) after the auth-context presence check. Token signature, audience, issuer, and expiry validation remain intact. `authFactory` logs a `WARNING` whenever the bypass is active under a non-`none` auth mode. Combine with server-side ACLs — without an in-handler ACL, every authenticated user effectively has every scope.
+- **`extractStringScopes` helper** in `claimParser.ts` — shared parser for the three claim sites; handles both array and space-delimited string forms, drops empty-string array entries, ignores arrays with non-string members.
+
+## Changed
+
+- **Granted scopes are now a union of `scp`, `scope`, and `mcp_tool_scopes`** — previously `scp` took precedence and `scope` was only read as a fallback. Operator-visible behavior change for tokens that populate both `scp` and `scope`: those tokens now receive the union of both claims. The Okta-only and OIDC-only cases (the common shapes) are unaffected.
+- **`authFactory`** — OAuth-mode startup log upgraded from `debug` to `info` with claim-resolution guidance and a pointer to the bypass flag for ops without claim-injection control.
+- **`tool-defs-analysis` skill** 1.0 → 1.1 ([#127](https://github.com/cyanheads/mcp-ts-core/issues/127)) — drops "or env vars" from the recovery-hints smell list. Env var names are actionable: the agent can name the var the user must set or rotate. Internal class names and file paths remain smells.
+- **Skill bumps:** `api-auth` 1.0 → 1.1 (claims mapping table, OIDC operator setup section, bypass flag docs), `api-config` 1.3 → 1.4 (env-var table row), `security-pass` 1.3 → 1.4 (Axis 2 check item: bypass-in-production warning).
+
+## Fixed
+
+- **`extractStringScopes` no longer leaks empty-string entries** through array-form claims. Pre-change array handling preserved `['', 'real-scope']` as-is, leaving an empty entry in the granted set. Practical exploitability was bounded (required scopes are non-empty static strings, so `Set.has('')` returned `false`), but the inconsistency vs. the string-path's `.trim()` check is now closed.

package/changelog/template.md

@@ -1,56 +1,71 @@
 ---
-# FORMAT REFERENCE — this file is never edited, never moved, never renamed.
-#
-# At release time, author a new per-version file at:
-#   changelog/<major.minor>.x/<version>.md   (e.g. changelog/0.6.x/0.6.6.md)
-# using this file's frontmatter and section layout as the starting point.
-# Set that new file's H1 to `# <version> — YYYY-MM-DD` with a concrete date.
-
-# Required. One-line headline describing the release. Max 250 chars. No markdown.
-# This line is what the CHANGELOG.md rollup shows — write it like a GitHub Release title.
-# Keep the double quotes around the value — unquoted YAML treats `:` (colon-space)
-# inside the string as a key separator, which fails GitHub's strict YAML parser.
+# FORMAT REFERENCE — do not edit. Copy this file to
+# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
+# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
+# with a concrete date.
+
+# Required. One-line GitHub Release-style headline. ~250 character soft cap.
+# Default short and scannable. Don't pad, don't stitch unrelated changes with
+# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
+# inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
-# Set to `true` only if this release has breaking changes (API removals, signature
-# changes, config renames, anything that requires consumer code changes on update).
-# Flagged as ⚠️ Breaking in the rollup.
+# Set `true` when consumers must change code to upgrade: API removals,
+# signature changes, config renames, behavior changes that break existing
+# usage. Flagged as `Breaking` in the rollup.
 breaking: false
+
+# Set `true` if this release contains any security fix. Pairs with the
+# `## Security` section below. Flagged as `Security` in the rollup so
+# users can triage upgrade urgency at a glance.
+security: false
 ---
 
 # <version> — YYYY-MM-DD
 
 <!--
-  FORMAT REFERENCE — do not edit this file. It exists so the per-version file
-  structure has a single copy-source. Create new release notes at
-  `changelog/<major.minor>.x/<version>.md` using this layout.
-
-  Optional narrative intro — 1-3 sentences framing the release theme. Delete if not needed.
-
-  TONE: terse and fact-dense. 1-2 sentence(s) per bullet where possible —
-  name the symbol, state what changed, stop. Drop "explains how it works" prose;
-  that belongs in JSDoc, AGENTS.md, or the relevant skill. Drop ceremonial
-  framings ("This release introduces…", "fully backwards compatible:" with a
-  paragraph of justification). Prefer code/symbol names over English
-  re-explanations. If a bullet runs more than ~2 lines, split it or cut it.
-
-  WHAT TO INCLUDE: every distinct fact a reader needs to adopt or audit the
-  release — new exports, signatures, lint rule IDs, env vars, breaking
-  changes, version bumps on shipped skills. WHAT TO CUT: mechanism walkthroughs,
-  duplicate prose between Added and Changed, file-by-file test enumerations,
-  internal implementation notes. Trust the reader to read the code or the docs.
-
-  Linking issues/PRs: use full URLs so the link works everywhere (GitHub web UI,
-  npm/node_modules reads, local editors). GitHub's bare `#NN` auto-link only
-  resolves inside its own UI.
-
-    [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
-    [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
-
-  Only link numbers you've verified exist (via `gh issue view NN` or
-  `gh pr view NN`). Never speculate on a future number — `#42` for "my
-  upcoming PR" will quietly resolve to whatever real item already owns 42,
-  and GitHub timeline previews will pull in that unrelated item's title.
+  AUTHORING GUIDE — applies to the new per-version file you create from this
+  template.
+
+  Audience: someone scanning release notes to decide what affects them. Lead
+  each bullet with the symbol or concept name in **bold** so they can skip
+  what's irrelevant and zoom in on what's not.
+
+  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
+  name the symbol, state what changed, stop. Use a second sentence only when
+  it carries weight. If a bullet feels long, it is.
+
+  Cut: mechanism walkthroughs (those belong in JSDoc, AGENTS.md, or the
+  relevant skill), ceremonial framings ("This release introduces…",
+  backwards-compat paragraphs), file-by-file test enumerations, internal
+  implementation notes. Prefer code/symbol names over English re-explanations.
+
+  Narrative intro: skip by default. Add one short sentence only when the
+  release theme genuinely needs framing the bullets can't carry.
+
+  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
+  Fixed, Security. Include only sections with entries; delete the rest
+  (including the commented-out scaffolding below). Don't ship empty headers.
+
+  Include: every distinct fact a reader needs to adopt or audit the release —
+  new exports, signatures, lint rule IDs, env vars, breaking changes, version
+  bumps on shipped skills. Nothing more.
+
+  Links: link issues, PRs, docs, or skills where they help a reader jump to
+  context. Once per item per entry — don't re-link the same issue in summary,
+  narrative, and bullet. Skip links for inline symbol names; code spans speak
+  for themselves.
+
+  Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
+  inside its own UI, not in npm reads or local editors.
+
+      [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
+      [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
+
+  Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
+  Never speculate on a future number — `#42` for an upcoming PR silently
+  resolves to whatever real item already owns 42, and timeline previews pull
+  in that unrelated item's metadata.
 -->
 
 ## Added
@@ -61,6 +76,18 @@ breaking: false
 
 -
 
+<!-- ## Deprecated
+
+- -->
+
+<!-- ## Removed
+
+- -->
+
 ## Fixed
 
 -
+
+<!-- ## Security
+
+- -->

package/dist/cli/init.js

@@ -66,10 +66,16 @@ function init() {
         mkdirSync(dest, { recursive: true });
     }
     console.log(`\n  Scaffolding${name ? ` ${name}` : ''} in ${dest}\n`);
+    const substitutions = {
+        PACKAGE_NAME: packageName,
+        FRAMEWORK_VERSION: PACKAGE_JSON.version,
+        MCP_SDK_VERSION: PACKAGE_JSON.dependencies?.['@modelcontextprotocol/sdk'] ?? '',
+        ZOD_VERSION: PACKAGE_JSON.dependencies?.zod ?? '',
+    };
     const created = [];
     const skipped = [];
     // Step 1: Copy templates
-    copyTemplates(dest, packageName, PACKAGE_JSON.version, created, skipped);
+    copyTemplates(dest, substitutions, created, skipped);
     // Step 2: Copy scripts
     copyScripts(dest, created, skipped);
     // Step 3: Copy external skills
@@ -78,7 +84,7 @@ function init() {
     printSummary(created, skipped, name);
 }
 // ── Template copying ──────────────────────────────────────────────────
-function copyTemplates(dest, name, frameworkVersion, created, skipped) {
+function copyTemplates(dest, substitutions, created, skipped) {
     const entries = walkDir(TEMPLATES_DIR);
     for (const srcPath of entries) {
         let relPath = relative(TEMPLATES_DIR, srcPath);
@@ -94,9 +100,10 @@ function copyTemplates(dest, name, frameworkVersion, created, skipped) {
                 continue;
             }
             mkdirSync(dirname(destPath), { recursive: true });
-            const content = readFileSync(srcPath, 'utf-8')
-                .replace(/\{\{PACKAGE_NAME\}\}/g, name)
-                .replace(/\{\{FRAMEWORK_VERSION\}\}/g, frameworkVersion);
+            let content = readFileSync(srcPath, 'utf-8');
+            for (const [key, value] of Object.entries(substitutions)) {
+                content = content.replaceAll(`{{${key}}}`, value);
+            }
             writeFileSync(destPath, content);
             created.push(relPath);
         }