@cyanheads/mcp-ts-core 0.5.3 → 0.6.0

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Protocol
 
-**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.5.3
+**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.6.0
 **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.
@@ -14,7 +14,7 @@
 - **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.
 - **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.
+- **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.
 
 ---
@@ -453,6 +453,7 @@ Detailed method signatures, options, and examples live in skill files. Read the
 | `api-config` | `skills/api-config/SKILL.md` | AppConfig, parseConfig, env vars |
 | `api-testing` | `skills/api-testing/SKILL.md` | createMockContext, test patterns, MockContextOptions |
 | `api-workers` | `skills/api-workers/SKILL.md` | createWorkerHandler, CloudflareBindings, Worker runtime |
+| `api-linter` | `skills/api-linter/SKILL.md` | Definition lint rules (`format-parity`, `schema-*`, `name-*`, `server-json-*`, …) — look here when devcheck reports a lint diagnostic |
 | `add-tool` | `skills/add-tool/SKILL.md` | Scaffold a new MCP tool definition |
 | `add-app-tool` | `skills/add-app-tool/SKILL.md` | Scaffold an MCP App tool + UI resource pair |
 | `add-resource` | `skills/add-resource/SKILL.md` | Scaffold a new MCP resource definition |
@@ -517,11 +518,49 @@ Detailed method signatures, options, and examples live in skill files. Read the
 | `bun run dev:http` | Development mode (HTTP) |
 | `bun run start:stdio` | Production mode (stdio, after build) |
 | `bun run start:http` | Production mode (HTTP, after build) |
+| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
+| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync with `changelog/` (used by devcheck) |
 
 After `bun update --latest`, run the `maintenance` skill to investigate changelogs, adopt upstream changes, and sync project skills.
 
 ---
 
+## 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. Work-in-progress entries live at the top level in `changelog/unreleased.md` and are moved into the appropriate series directory on release.
+
+`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.
+
+### Per-version file format
+
+```markdown
+---
+summary: One-line headline, ≤250 chars, no markdown  # required
+breaking: false                                       # optional, default false
+---
+
+# 0.5.4 — 2026-04-20
+
+Optional narrative intro (1-3 sentences).
+
+## Added
+
+- ...
+```
+
+**Frontmatter fields:**
+
+| Field | Required | Purpose |
+|:------|:---------|:--------|
+| `summary` | yes | Rollup index line. Max 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. |
+
+Summary > 250 chars or malformed `breaking` fails `changelog:check`. Missing `summary` emits a warning and renders the rollup entry as header-only.
+
+Pre-release versions (`0.6.0-beta.1`, `0.6.0-rc.1`, etc.) accumulate as sub-headers inside `unreleased.md` during development and are consolidated into the single final-version file (`changelog/0.6.x/0.6.0.md`) when the final ships.
+
+---
+
 ## Publishing
 
 Run the `release` skill first — it verifies version consistency across all files, changelog completeness, skill version bumps, and runs the final check suite. It ends by presenting these irreversible publish commands:

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.5.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
+[![Version](https://img.shields.io/badge/Version-0.6.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 

package/changelog/0.1.x/0.1.0.md

@@ -0,0 +1,78 @@
+---
+summary: Initial stable pre-release — builder API for tools/resources/prompts, unified Context, createApp lifecycle, Cloudflare Workers support, 25+ subpath exports
+breaking: false
+---
+
+# 0.1.0 — 2026-03-14
+
+First stable pre-release of `@cyanheads/mcp-ts-core` — a framework for building MCP servers in TypeScript. Extracted from the `mcp-ts-template` template into a standalone npm package with explicit subpath exports, builder-pattern definition APIs, unified handler context, and full-stack observability.
+
+## Highlights
+
+- **Package identity**: `@cyanheads/mcp-ts-core` on npm, `ghcr.io/cyanheads/mcp-ts-core` on Docker.
+- **Builder API**: `tool()`, `resource()`, `prompt()` builders with Zod-validated `input`/`output`/`args`, inline `auth`, and `handler(input, ctx)` signatures. Replaces the legacy `logic`/`inputSchema`/`outputSchema`/`responseFormatter`/`withToolAuth` pattern.
+- **Unified `Context`**: Single handler argument providing `ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.sample`, `ctx.signal`, `ctx.progress`, and `ctx.uri`.
+- **`createApp()` lifecycle**: Owns OTEL init, logger, transport startup, signal handling, and graceful shutdown. Returns `ServerHandle` with `shutdown()` and `services`.
+- **Cloudflare Workers**: `createWorkerHandler()` with per-request `McpServer` factory, env binding injection, and `onScheduled` support.
+- **Comprehensive observability**: Every tool/resource/prompt call automatically instrumented with OTel spans, duration histograms, call/error counters, and structured completion logs. Process-level gauges (RSS, heap, uptime, event loop delay). Subsystem instrumentation for storage, auth, sessions, tasks, LLM, speech, graph, and error classification. 60+ semantic convention constants.
+
+## Added
+
+- **Definition builders**: `tool()`, `resource()`, `prompt()` with Zod schemas, inline `auth` scopes, `format` functions, `title` field, and `task: true` for async task tools.
+- **Unified `Context` interface**: `ctx.log` (auto-correlated logging), `ctx.state` (tenant-scoped KV with generics, Zod validation, batch ops, TTL), `ctx.elicit` (user prompting), `ctx.sample` (LLM completion), `ctx.signal` (cancellation), `ctx.progress` (task progress).
+- **`createApp(options)`**: Composition root accepting `tools`, `resources`, `prompts`, `setup()`, `name`, `version`. Full server lifecycle management.
+- **`createWorkerHandler(options)`**: Cloudflare Workers entry point with `extraEnvBindings`, `extraObjectBindings`, `onScheduled`.
+- **Subpath exports**: 25+ explicit entries — `./tools`, `./resources`, `./prompts`, `./tasks`, `./errors`, `./config`, `./auth`, `./storage`, `./storage/types`, `./utils`, `./services`, `./testing`, `./worker`.
+- **`z` re-export**: `import { tool, z } from '@cyanheads/mcp-ts-core'` — no separate `zod` import needed.
+- **Error factories**: `notFound()`, `validationError()`, `unauthorized()`, `forbidden()`, `conflict()`, `rateLimited()`, `timeout()`, `serviceUnavailable()`, `configurationError()`, `invalidParams()`, `invalidRequest()` — all accept `(message, data?, options?)` with `{ cause }` for error chaining.
+- **Auto-error classification**: Framework catches all handler errors and classifies by type/message pattern matching — `ZodError` to `ValidationError`, HTTP status codes, common message patterns, `McpError` preserved as-is.
+- **`checkScopes(ctx, scopes)`**: Dynamic scope checking for runtime-dependent auth requirements.
+- **`createMockContext(options?)`**: Test utility with stubbed `log`, in-memory `state`, optional `elicit`/`sample`/`progress` mocks.
+- **Auto-task tools**: `task: true` on tool definitions — framework manages task creation, background execution, progress reporting, cancellation, and result storage.
+- **`GET /mcp` discovery**: Server capabilities, framework identity, auth mode, and definition counts.
+- **`init` CLI**: `mcp-ts-core init [name]` scaffolds a new consumer project with templates, echo definitions, and agent protocol files.
+- **Shareable configs**: `tsconfig.base.json`, `biome.json`, `vitest.config.base.ts` for consumer extension.
+- **Agent skills**: 12+ skill files (`skills/`) covering `setup`, `add-tool`, `add-resource`, `add-prompt`, `add-service`, `add-provider`, `add-export`, `devcheck`, `release`, `maintenance`, `migrate-mcp-ts-template`, and API references.
+- **`examples/` directory**: Complete reference consumer server with 7 tools, 2 resources, 1 prompt, and 39 tests.
+- **OTel instrumentation**: Process gauges, startup/shutdown spans, resource/prompt measurement, active request gauge, storage/auth/session/task/LLM/speech/graph instrumentation, error classification metric.
+- **Semantic conventions**: `src/utils/telemetry/semconv.ts` with 60+ constants for all custom OTel attributes.
+- **Services**: `CoreServices` exposes `config`, `logger`, `storage`, `rateLimiter`, optional `llmProvider`, `speechService`, `supabase`.
+- **`GraphService.healthCheck()`**: Liveness check delegated to the underlying graph provider.
+- **Utility barrels**: Unified `./utils` and `./services` exports covering formatting, parsing, security, network, pagination, scheduling, telemetry, encoding, runtime, token counting, and type guards.
+
+## Changed (from legacy template)
+
+- **DI container removed**: Replaced by `createApp()` direct construction. Explicit dependency struct (`McpServerDeps`) instead of token-based resolution.
+- **Definition types consolidated**: Merged `New*Definition` types into canonical `ToolDefinition`, `ResourceDefinition`, `PromptDefinition`. Single code path per primitive in registration.
+- **Error handling simplified**: "Logic throws, framework catches." Handlers throw plain `Error` or use error factories. No `try/catch` needed in handlers. Framework classifies, normalizes, and returns `isError: true`.
+- **Auth moved inline**: `auth: ['scope']` on definitions replaces `withToolAuth()`/`withResourceAuth()` HOF wrappers.
+- **`ctx.state` accepts any serializable value**: No manual `JSON.stringify`/`JSON.parse`. Supports generic types, Zod validation, batch operations (`getMany`, `setMany`, `deleteMany`), and TTL.
+- **Tenant ID defaults to `'default'`**: `ctx.state` works in stdio mode without JWT auth.
+- **Build system**: `tsc` + `tsc-alias` replaces `bun build` for proper `.d.ts` generation.
+- **Dependencies restructured**: Heavy deps (OTEL, Supabase, OpenAI, parsers, sanitization, scheduling) moved to optional peer dependencies with lazy dynamic `import()`. Core deps minimized.
+- **Auth fail-closed**: When auth is enabled but no auth context exists, throws `Unauthorized` instead of defaulting to allowed.
+- **Config immutable**: Config proxy `set()`/`defineProperty()` traps return `false` after parse.
+- **Async API surface**: Parser `parse()` methods, `diffFormatter`, and `sanitization` methods are async due to lazy loading.
+- **Zod modernized**: `z.url()`, `z.email()`, `z.iso.datetime()` replace string refinements.
+- **`devcheck` audit**: Classifies vulnerabilities as direct vs transitive, warns instead of failing for upstream-only issues.
+- **HTTP error mappings expanded**: `InvalidParams` 400, `Timeout` 504, `ServiceUnavailable` 503. Error responses include `McpError.data`.
+- **Prompt registration**: Callbacks wrapped in error handling via `ErrorHandler.handleError`.
+- **OpenRouter provider**: SDK-level retries (`maxRetries: 2`) with exponential backoff on 429/5xx, replacing manual retry logic.
+- **`ElicitResult` type**: Updated to match actual MCP SDK shape — flat `Record<string, string | number | boolean | string[]>` content, not a discriminated union with typed `data`.
+- **Speech API parameters**: TTS uses `voice: { voiceId }` / `format`, STT uses `audio` / `format`. `WhisperProvider` uses direct HTTP instead of OpenAI SDK.
+- **`AuthContext` narrowed**: Removed `[key: string]: unknown` index signature — explicit fields only.
+- **Agent skill documentation**: Expanded with full env var reference tables (all defaults), provider registration guides per domain, auto-classification pattern reference, vitest `mergeConfig` setup, and corrected pagination/elicitation examples.
+
+## Removed
+
+- **DI container** (`src/container/`): 6 source files + 5 test files.
+- **Legacy definition types**: `New*` prefixed types, `isNew*Definition` type guards, `newToolHandlerFactory`, `newResourceHandlerFactory`, `newPromptDefinition` — all consolidated into canonical modules.
+- **`withAuth` HOF**: `withToolAuth()`, `withResourceAuth()` — replaced by inline `auth` on definitions.
+- **Template definitions from `src/`**: Moved to `examples/`. Core library ships with no built-in tools/resources/prompts.
+- **Legacy READMEs**: `src/mcp-server/README.md`, `src/services/README.md`, `src/storage/README.md` — superseded by CLAUDE.md and skill files.
+- **Conformance test suite**: 20 test files + 4 helpers — to be rewritten against stable API post-publish.
+- **`./context` subpath export**: `Context` available from main entry point.
+- **11 granular `./utils/*` subpath exports**: Replaced by single `./utils` barrel.
+- **`changelog/archive.md`**: Pre-3.0.0 history.
+- **`@traversable/*` devDependencies**: No longer needed after removing Zod schema compatibility tests.
+- **`vite-tsconfig-paths`**: Replaced by native Vitest `resolve.tsconfigPaths`.

package/changelog/0.1.x/0.1.1.md

@@ -0,0 +1,28 @@
+---
+summary: Scaffold and build portability — Node-portable build script, shared config extensions for tsconfig/biome/vitest, template overhaul, init CLI improvements
+breaking: false
+---
+
+# 0.1.1 — 2026-03-14
+
+Scaffold and build portability improvements. Consumer projects now extend core shared configs instead of inlining them, and the build script runs on plain Node.js.
+
+## Changed
+
+- Made `scripts/build.ts` Node-portable by replacing Bun-specific `spawn` and `Bun.file` with `node:child_process/execFile` and `readFileSync`.
+- Renamed `./biome.json` subpath export to `./biome` for consistency with `extends` syntax.
+- Template `tsconfig.json` now extends `@cyanheads/mcp-ts-core/tsconfig.base.json` instead of inlining compiler options.
+- Template `biome.json` now extends `@cyanheads/mcp-ts-core/biome` instead of inlining rules.
+- Template `vitest.config.ts` now extends core vitest config via `mergeConfig`.
+- Template `package.json` overhauled: proper metadata fields, `tsx scripts/build.ts` build command, `--watch` for dev scripts, updated dependency versions, added `pino-pretty`.
+- Template `CLAUDE.md` updated commands table to distinguish `npm` (portable) from `bun` (bun-only) scripts, added description naming convention, added Bun requirement note.
+- `init` CLI now copies build scripts (`build.ts`, `clean.ts`, `devcheck.ts`, `tree.ts`) into scaffolded projects.
+- `init` CLI refactored template copying with shared `copyIfAbsent` helper and consistent `packageName` derivation.
+- Added `scripts/` directory to npm package `files` array so consumers receive build scripts.
+
+## Removed
+
+- Deleted `scripts/test-report.ts` (624-line HTML test report generator).
+- Deleted `scripts/verify-exports.ts` (export path verifier).
+- Removed `prepublishOnly` and `prepare` scripts from package.json.
+- Removed `test:report`, `test:report:open`, `coverage:update`, and `coverage:commit` scripts from package.json.

package/changelog/0.1.x/0.1.10.md

@@ -0,0 +1,32 @@
+---
+summary: Security hardening — prevent HTTP error data leaks, drop raw token from AuthContext, concurrency-safe config overrides, cancellation in ContextState and LLM provider
+breaking: false
+---
+
+# 0.1.10 — 2026-03-20
+
+Security hardening, concurrency-safe config overrides, cancellation support in context state and LLM provider, and filesystem list optimization.
+
+## Security
+
+- **HTTP error data leak prevention** — HTTP error handler now captures original `McpError.data` before `ErrorHandler.handleError()` enrichment, preventing internal details (stack traces, cause chains, operation context) from leaking in JSON-RPC error responses.
+- **Removed raw token from `AuthContext`** — Dropped the `token` field from the context-facing auth shape. Raw JWT/OAuth bearer tokens no longer propagate through `ctx.auth`.
+
+## Fixed
+
+- **Concurrency-safe config overrides** — `composeServices()` no longer mutates `process.env` for `name`/`version` overrides. `parseConfig()` and `resetConfig()` accept an optional `envOverrides` parameter, avoiding races in Workers and parallel test suites.
+- **Auth bridging from ALS** — `requestContextService.createRequestContext()` now bridges auth info from AsyncLocalStorage into the context, so `ctx.auth` is populated in tool/resource handlers without requiring a separate `withAuthInfo()` call.
+
+## Added
+
+- **Cancellation in `ContextState`** — All `ctx.state` methods (`get`, `set`, `delete`, `getMany`, `setMany`, `deleteMany`, `list`) now call `signal.throwIfAborted()` before I/O, respecting request cancellation.
+- **`AbortSignal` on LLM provider** — `ILlmProvider.chatCompletion()` and `chatCompletionStream()` accept an optional `signal` parameter, plumbed through `OpenRouterProvider` to the OpenAI SDK.
+- **`ListResult.values`** — `IStorageProvider.ListResult` gained an optional `values` map for pre-fetched data, allowing providers to avoid redundant I/O.
+
+## Changed
+
+- **Filesystem list optimization** — `FileSystemProvider.list()` retains parsed values during TTL validation and populates `ListResult.values`, eliminating a redundant `getMany()` round-trip in `ContextState.list()`.
+- **Peer dependency version ranges** — All `peerDependencies` now specify proper semver ranges (were empty strings).
+- **Removed stale `resolutions`** — Dropped `escape-string-regexp`, `@isaacs/brace-expansion`, `markdown-it`, `qs`, `minimatch`, `ajv`, `lodash`, `rollup` from `resolutions`.
+- **Removed `inspector` script** — Dropped `mcp-inspector` script from `package.json`.
+- Fixed "template's" → "framework's" in `storageBackedTaskStore` comments.

package/changelog/0.1.x/0.1.11.md

@@ -0,0 +1,51 @@
+---
+summary: Security hardening across auth, sessions, and error data — HMAC cursors, auth-gated metadata, JWT issuer/audience validation, public API barrel, zod promoted to direct dependency
+breaking: false
+---
+
+# 0.1.11 — 2026-03-20
+
+Security hardening, reliability improvements, public API surface refinement, and storage provider consistency.
+
+## Security
+
+- **HMAC-signed pagination cursors** — Cursors now include a truncated HMAC-SHA256 signature using a per-process random key, preventing cursor forgery for key enumeration within tenant namespaces. Cursors are ephemeral — they don't survive process restarts.
+- **Auth-gated server metadata** — `GET /mcp` returns minimal `{ status: 'ok' }` when auth is enabled, hiding server name, version, environment, and capability details from unauthenticated callers.
+- **OTel scope redaction** — Auth middleware logs scope count instead of scope values in OTel span attributes, preventing authorization model exposure to tracing backends.
+- **JWT issuer/audience validation** — `JwtStrategy` validates `iss` and `aud` claims when `MCP_JWT_EXPECTED_ISSUER` / `MCP_JWT_EXPECTED_AUDIENCE` are configured. Explicit `algorithms: ['HS256']` constraint on token verification.
+- **Dev bypass guard** — `DEV_MCP_AUTH_BYPASS` rejected in production (`NODE_ENV=production`). Allowed in development and testing environments.
+- **Session capacity limits** — `SessionStore` enforces a configurable maximum session count (default 10,000), preventing unbounded memory growth from session exhaustion.
+- **Atomic identity binding** — Session identity fields (tenantId, clientId, subject) bound atomically as a snapshot, preventing chimeric identities from per-field races across requests.
+- **Error data sanitization** — HTTP error handler captures `McpError.data` before `ErrorHandler` enrichment, preventing internal details (stack traces, cause chains) from leaking while preserving developer-intentional error context.
+
+## Added
+
+- **Public API barrel** — New `src/core/index.ts` selectively re-exports only the public API, keeping internal types (`ComposedApp`, `composeServices`, `TaskManager`) out of the consumer-facing surface. Package entry points updated from `dist/core/app.js` to `dist/core/index.js`.
+- **`zod` as direct dependency** — Moved from `peerDependencies` to `dependencies`. Consumers no longer need to install `zod` separately.
+- **Duplicate tool name detection** — `ToolRegistry` throws at startup if two tools share the same name.
+- **Auto-task timeout enforcement** — Background task handlers aborted after the task entry TTL expires, preventing leaked resources from hung handlers.
+- **`ErrorHandler.classifyOnly()`** — Classifies errors without logging, OTel side effects, or wrapping. Used by resource handler factory to avoid double-logging.
+- **`SchedulerService.destroyAll()`** — Stops and removes all cron jobs during shutdown, preventing timers from keeping the event loop alive.
+- **In-memory provider capacity limits** — Configurable `maxEntries` (default 10,000) with automatic TTL sweep when capacity is reached. New `size` getter for monitoring.
+- **Walk-based JSON size estimator** — `estimateJsonSize()` fallback in performance module handles circular references and BigInt without throwing.
+
+## Fixed
+
+- **Fatal shutdown backstop** — Uncaught exceptions and unhandled rejections trigger a 10-second backstop timer guaranteeing process exit, preventing hung shutdowns.
+- **Signal handler ordering** — `SIGTERM`/`SIGINT` handlers registered before transport start, so signals during HTTP bind still trigger graceful shutdown.
+- **Non-SSE transport cleanup** — Per-request `McpServer`/transport instances closed via microtask after non-SSE responses, preventing resource leaks in stateless HTTP mode.
+- **OTel shutdown race** — No-op catch on `sdk.shutdown()` promise prevents unhandled rejection when the timeout timer wins the race.
+- **Task ownership cleanup** — `SessionAwareTaskStore` removes ownership entries when tasks reach terminal state (completed/failed).
+- **Formatter error isolation** — Tool handler factory catches formatter errors separately from handler errors, providing clearer error messages.
+- **Lazy dotenv loading** — Deferred to first `parseConfig()` call. Avoids wasted filesystem syscall in Workers and prevents stale `.env` from loading before test setup.
+- **Config name/version overrides** — Persisted directly to `process.env` for process-lifetime visibility to OTEL/logger/transport, replacing the env-override parameter approach.
+
+## Changed
+
+- **TypeError no longer mapped to ValidationError** — Runtime TypeErrors (e.g., "Cannot read properties of undefined") are programming errors, not validation failures. They now fall through to message-pattern matching or `InternalError` fallback.
+- **Validation error pattern** — Restored broad `invalid` keyword matching. The pattern relies on ordering (Unauthorized patterns are checked first) rather than a restrictive noun list, so messages like "Invalid email" correctly classify as ValidationError.
+- **R2 provider: idempotent delete** — Removed pre-delete `head()` check. R2 `delete()` is idempotent; the extra round-trip added latency under eventual consistency.
+- **R2 provider: consistent pagination** — Switched from R2 native cursor to limit+1 pagination with `startAfter`, matching D1/Supabase providers.
+- **D1 provider: strict JSON parsing** — `getMany()` throws `McpError(SerializationError)` on parse failure instead of silently skipping corrupted values.
+- **Resource handler error path** — Uses `classifyOnly()` instead of full `handleError()` to avoid double-logging when the SDK catches the re-thrown error.
+- **Auto-task handler refactored** — Extracted `AutoTaskOptions` interface, configurable TTL from config, proper `finally` block for cleanup, error classification via `ErrorHandler`.

package/changelog/0.1.x/0.1.12.md

@@ -0,0 +1,21 @@
+---
+summary: Required output schemas, OAuth algorithm pinning, resource metric cardinality fix
+breaking: true
+---
+
+# 0.1.12 — 2026-03-20
+
+Required output schemas, OAuth hardening, and metric cardinality fix.
+
+## Security
+
+- **OAuth algorithm pinning** — `OauthStrategy` restricts JWT verification to `['RS256', 'ES256', 'PS256']`, preventing algorithm confusion attacks.
+
+## Added
+
+- **`ATTR_MCP_RESOURCE_NAME`** — New bounded resource identifier attribute for metric dimensions, replacing unbounded URI on metrics.
+
+## Changed
+
+- **`output` required on tool definitions** — `ToolDefinition.output` is now mandatory (was optional). Handler factory and task registration unconditionally validate output and include `structuredContent`.
+- **Resource metric cardinality** — Resource metrics use bounded `mcp.resource.name` attribute instead of unbounded `mcp.resource.uri`. URI attribute reserved for span-level detail only.

package/changelog/0.1.x/0.1.13.md

@@ -0,0 +1,16 @@
+---
+summary: Test suite reorganization into unit, integration, compliance, smoke, and helpers tiers — vitest config updated, helper files consolidated
+breaking: false
+---
+
+# 0.1.13 — 2026-03-20
+
+Test suite reorganization into a structured directory layout.
+
+## Changed
+
+- **Test directory restructure** — Reorganized flat `tests/` into `tests/unit/`, `tests/integration/`, `tests/compliance/`, `tests/smoke/`, and `tests/helpers/`. Clear separation of test tiers with dedicated directories for each category.
+- **Vitest config updates** — `vitest.config.ts` uses explicit `include` globs (`tests/unit/**`, `tests/compliance/**`, `tests/smoke/**`) instead of exclusion-based patterns. `vitest.integration.ts` includes both `*.test.ts` and `*.int.test.ts` patterns.
+- **Test helper consolidation** — Merged `tests/fixtures/`, `tests/mocks/`, and `tests/integration/helpers/` into a single `tests/helpers/` directory with renamed files (`fixtures.ts`, `mock-handlers.ts`, `mock-server.ts`, `http-helpers.ts`, `server-process.ts`).
+- All test import paths updated to match new directory depths.
+- Regenerated `docs/tree.md` to reflect new structure.

package/changelog/0.1.x/0.1.14.md

@@ -0,0 +1,20 @@
+---
+summary: Skill documentation overhaul — maintenance, migration, polish, and release skills updated with expanded guidance and examples, msw bumped
+breaking: false
+---
+
+# 0.1.14 — 2026-03-21
+
+Skill documentation overhaul and dependency updates.
+
+## Changed
+
+- **`maintenance` skill v1.1** — Simplified from three-tier to two-tier skill sync (package → project). Removed agent skill directory tier.
+- **`migrate-mcp-ts-template` skill v2.1** — Added worker, encoding, and service import mappings. Expanded framework file candidates with review-before-cleanup guidance. Added `setup()` and `vitest.config` examples.
+- **`polish-docs-meta` skill v1.1** — Added `server.json` and `bunfig.toml` verification steps. Rewrote README reference (tools-first structure, two-layer tool docs, badge guide). Rewrote `server.json` reference to use official MCP schema with two-package-entry pattern. Updated `package-meta` reference with `mcpName`, `packageManager`, and `engines.bun` fields.
+- **`release` skill v1.2** — Reframed as a verification gate; git wrapup protocol now handles version bumps, changelog, and commits. Added template version check.
+- Minor wording refinements across `add-test`, `api-context`, and `setup` skills.
+
+## Dependencies
+
+- Bumped `msw` to `^2.12.14`.

package/changelog/0.1.x/0.1.15.md

@@ -0,0 +1,24 @@
+---
+summary: MCP definition linter at startup, standalone lint:mcp script, runtime-agnostic devcheck, npm-first templates
+breaking: false
+---
+
+# 0.1.15 — 2026-03-21
+
+MCP definition linter, Bun-free devcheck, and template portability.
+
+## Added
+
+- **MCP definition linter** — New `src/linter/` module validates tool, resource, and prompt definitions against MCP spec and framework conventions at startup. Checks name format/uniqueness, description presence, handler existence, Zod schema structure, `.describe()` on fields, URI template validity, and annotation types. Errors (MUST violations) block startup; warnings (SHOULD/quality) are logged.
+- **`./linter` subpath export** — `validateDefinitions()` and lint types available via `@cyanheads/mcp-ts-core/linter` for standalone use.
+- **`lint:mcp` script** — `scripts/lint-mcp.ts` discovers definitions from conventional paths and runs the linter as a standalone CLI or devcheck step.
+- **Duplicate name detection for prompts and resources** — `PromptRegistry` and `ResourceRegistry` now throw at startup on duplicate names, matching existing `ToolRegistry` behavior.
+- **Linter test suite** — 370-line test file covering all lint rules, edge cases, and report structure.
+
+## Changed
+
+- **`devcheck` is now runtime-agnostic** — Migrated from `Bun.spawn` to Node.js `child_process.spawn`. Auto-detects bun for package management commands, falls back to npm. Shebang changed from `bun` to `tsx`. Removed "slowest check" summary line.
+- **Templates default to npm/tsx** — `AGENTS.md`, `CLAUDE.md`, and `package.json` templates use `tsx` for scripts and `npm run` for commands. Bun is documented as an optional upgrade. Removed "Bun requirement" note and `migrate-mcp-ts-template` skill reference. Added `rebuild` and `lint:mcp` commands.
+- **Skills section wording** — Templates clarify that skills live at `skills/` and should be copied to agent directories, replacing the "sync" language.
+- **`init` CLI** — Now copies `lint-mcp.ts` to scaffolded projects.
+- **`setup` skill** — Updated to recommend npm as default with bun as alternative.

package/changelog/0.1.x/0.1.16.md

@@ -0,0 +1,17 @@
+---
+summary: Security patch for flatted prototype pollution CVE-2026-33228, rebranded framework description, condensed agent protocol in CLAUDE.md
+breaking: false
+---
+
+# 0.1.16 — 2026-03-21
+
+Security patch and agent protocol cleanup.
+
+## Security
+
+- **CVE-2026-33228** — Pinned `flatted` to `3.4.2` via `overrides` to fix prototype pollution vulnerability in `flatted <= 3.4.1` (transitive dep via `@vitest/ui`).
+
+## Changed
+
+- **Project description** — Rebranded to "Agent-native TypeScript framework for building MCP servers." Updated `package.json` description, keywords, and README tagline.
+- **CLAUDE.md** — Condensed agent protocol: removed inline code examples duplicated in skills, merged Checklist into Code Style section, shortened Context/Error/Auth sections with skill cross-references.

package/changelog/0.1.x/0.1.17.md

@@ -0,0 +1,14 @@
+---
+summary: Three bug fixes for HTTP duplicate registration, stale tsbuildinfo cleanup, and missing tsconfig.build.json in scaffold
+breaking: false
+---
+
+# 0.1.17 — 2026-03-21
+
+Three bug fixes affecting consumer projects scaffolded via `mcp-ts-core init` and HTTP transport mode.
+
+## Fixed
+
+- **Duplicate registration in HTTP mode** — Shared `ToolRegistry`, `ResourceRegistry`, and `PromptRegistry` instances now clear their `registeredNames` Set at the top of `registerAll()`, preventing duplicate-name errors when per-request `McpServer` instances are created (GHSA-345p-7cg4-v4c7 security pattern).
+- **Stale `.tsbuildinfo` not cleaned** — `scripts/clean.ts` now dynamically globs for all `*.tsbuildinfo` files in the project root instead of hardcoding a single `.tsbuildinfo` filename. Prevents silent 0-file builds when tsc names buildinfo after the tsconfig (e.g., `tsconfig.build.tsbuildinfo`).
+- **Missing `tsconfig.build.json` in scaffold** — Added `templates/_tsconfig.build.json` so `init` creates the file consumers need for `scripts/build.ts` (which defaults to `-p tsconfig.build.json`).

package/changelog/0.1.x/0.1.18.md

@@ -0,0 +1,18 @@
+---
+summary: Devcheck output visibility improvements, expanded template .gitignore, added VS Code config to scaffolded projects
+breaking: false
+---
+
+# 0.1.18 — 2026-03-21
+
+Template and devcheck improvements.
+
+## Changed
+
+- **Devcheck output visibility** — `scripts/devcheck.ts` now shows stdout for all checks (dimmed), not just failures. Stderr is dimmed for passing checks, red for failures. Makes it easier to verify what ran.
+- **Template `.gitignore` rewrite** — Expanded from a minimal Node.js gitignore to a comprehensive multi-language template covering OS files, IDE files, Node/Python/Java/Ruby, build artifacts, logs, coverage, environment files, and MCP-specific patterns.
+- **Template `.vscode/` config** — Added `extensions.json` (recommends Biome + markdownlint) and `settings.json` (Biome as default formatter, markdownlint config, format-on-save) to scaffolded projects.
+
+## Fixed
+
+- **`docs/tree.md`** — Corrected `vitest.config.base.ts` → `vitest.config.base.js` filename.

package/changelog/0.1.x/0.1.19.md

@@ -0,0 +1,19 @@
+---
+summary: Devcheck config externalization, field-test skill reference, template guidance additions, MCP_SESSION_MODE docs
+breaking: false
+---
+
+# 0.1.19 — 2026-03-21
+
+Devcheck config externalization, template guidance, and field-test skill.
+
+## Added
+
+- **`devcheck.config.json`** — Devcheck now reads depcheck ignores, ignore patterns, and outdated allowlist from a project-local JSON config file instead of hardcoded values in `scripts/devcheck.ts`. Consumer template includes a starter config.
+- **"What's Next?" section in templates** — `AGENTS.md` and `CLAUDE.md` templates now include a prioritized list of suggested next steps, helping agents guide users through the server development workflow.
+- **`field-test` skill reference** — Added to skill tables in `CLAUDE.md`, `templates/AGENTS.md`, and `templates/CLAUDE.md`.
+- **`MCP_SESSION_MODE` env var** — Documented in `templates/.env.example` (`stateful` | `stateless`).
+
+## Changed
+
+- **Template Dockerfile** — Simplified production install step; removed manual cleanup of platform-specific `@oven`/`@rollup` binaries (no longer needed).

package/changelog/0.1.x/0.1.2.md

@@ -0,0 +1,25 @@
+---
+summary: Reliability fixes for lifecycle, transport, storage, and telemetry — new design-mcp-server skill, onboarding improvements in consumer templates
+breaking: false
+---
+
+# 0.1.2 — 2026-03-14
+
+Reliability fixes for core lifecycle, transport, storage, and telemetry. New `design-mcp-server` skill for planning tool surfaces before scaffolding.
+
+## Added
+
+- `design-mcp-server` skill (`skills/design-mcp-server/SKILL.md`) — structured workflow for mapping a domain into tools, resources, and services before implementation.
+- "First Session" onboarding section in consumer templates (`CLAUDE.md`, `AGENTS.md`) guiding new projects through framework docs, setup, and design.
+
+## Fixed
+
+- `composeServices()` now saves and restores `process.env.MCP_SERVER_NAME` / `MCP_SERVER_VERSION` so successive calls in the same process aren't contaminated by earlier overrides.
+- OpenTelemetry initialization sets `isOtelInitialized` only after `sdk.start()` succeeds, and resets the flag and promise on failure — prevents a failed init from blocking retries.
+- Storage factory throws `configurationError` for unsupported providers in serverless environments instead of silently falling back to `in-memory`.
+- HTTP transport resolves `mcpSessionMode: 'auto'` to stateful (per MCP spec conformance) instead of treating it as stateless.
+
+## Changed
+
+- Setup skill simplified: skill sync is now a single `cp -R skills/* .claude/skills/` command instead of a multi-step comparison workflow.
+- Consumer templates updated: expanded commands table distinguishing `npm` (portable) from `bun` (bun-only) scripts, added description naming convention, added `design-mcp-server` to skills table.

package/changelog/0.1.x/0.1.20.md

@@ -0,0 +1,21 @@
+---
+summary: Template scaffolding improvements — dynamic framework version pinning, server.json manifest, slimmed gitignore focused on TypeScript/Node.js
+breaking: false
+---
+
+# 0.1.20 — 2026-03-21
+
+Template scaffolding improvements: dynamic framework version pinning, slimmed gitignore, and new server.json template.
+
+## Added
+
+- **`server.json` template** — Scaffolded projects now include a pre-configured MCP server manifest with stdio and streamable-http transport entries, using `{{PACKAGE_NAME}}` placeholder.
+- **Dynamic `{{FRAMEWORK_VERSION}}` placeholder** — `init` CLI reads the current framework version from its own `package.json` and injects it into templates. Scaffolded `package.json` now pins `@cyanheads/mcp-ts-core` to the exact version that generated the project, replacing the hardcoded `^0.1.0`.
+
+## Changed
+
+- **Template `_.gitignore` slimmed** — Removed Python, Java, Ruby, and other language-specific sections. Focused exclusively on TypeScript/Node.js patterns (OS files, IDE, build output, coverage, logs, env, MCP-specific). Added trailing newline.
+- **Template `package.json` enhanced** — Added `README.md`, `LICENSE`, `CLAUDE.md`, `AGENTS.md`, `Dockerfile`, and `server.json` to `files` array. Added empty `repository` field for consumers to fill in.
+- **Template `.env.example`** — Default HTTP port changed from 3000 to 3010.
+- **Template `.vscode/settings.json`** — Removed unused `ruff.enable: false` setting.
+- **`CLAUDE.md`** — Added `templates/` directory documentation explaining the scaffolding source and file naming conventions.

package/changelog/0.1.x/0.1.21.md

@@ -0,0 +1,17 @@
+---
+summary: Template test scaffolding, explicit stdio transport defaults, js-yaml v4 peer dep upgrade
+breaking: false
+---
+
+# 0.1.21 — 2026-03-21
+
+Template testing, dependency updates, and transport defaults.
+
+## Added
+
+- **Template test files** — Scaffolded projects now include starter tests for the echo tool, resource, and prompt (`templates/tests/`), demonstrating `createMockContext` usage and handler testing patterns.
+
+## Changed
+
+- **Template stdio scripts** — `dev:stdio` and `start:stdio` now explicitly set `MCP_TRANSPORT_TYPE=stdio`, matching the `dev:http`/`start:http` pattern. Prevents ambiguity when the default transport changes.
+- **`js-yaml` peer dependency** — Upgraded from `^3.14.2` to `^4.1.0`. v4 drops unsafe `safeLoad`/`safeDump` aliases and uses safe parsing by default.

package/changelog/0.1.x/0.1.22.md

@@ -0,0 +1,28 @@
+---
+summary: Linter hardening — schema serializability, auth scope, annotation coherence, and URI template-params alignment checks added, tool name format upgraded to error
+breaking: false
+---
+
+# 0.1.22 — 2026-03-21
+
+Linter hardening: new rules catch schema serializability failures, auth scope issues, annotation contradictions, and URI template mismatches before they become runtime errors.
+
+## Added
+
+- **Schema serializability rule** — `checkSchemaSerializable` validates that tool/resource/prompt Zod schemas can convert to JSON Schema via `toJSONSchema()`. Non-serializable types (`z.custom()`, `z.date()`, `z.transform()`, etc.) that would crash `tools/list` at runtime are now caught at startup.
+- **Auth scope validation** — `lintAuthScopes` checks that `auth` arrays on tools and resources contain only non-empty strings. Catches typos like `auth: 'scope'` (not an array) or `auth: ['']` (empty scope).
+- **Annotation coherence warnings** — Flags contradictory annotation combos: `destructiveHint` with `readOnlyHint: true` (meaningless) and `idempotentHint` with `readOnlyHint: true` (redundant).
+- **Template-params alignment** — Resource linter cross-references URI template variables against `params` schema keys. Mismatches (e.g., `{itemId}` in template but `item_id` in schema) cause every resource read to fail silently — now caught at startup.
+- **`_.dockerignore` template** — Scaffolded projects now include a comprehensive `.dockerignore`, matching the framework's own.
+- **Linter tests** — ~130 lines of new test coverage for all new rules.
+
+## Changed
+
+- **Tool name format severity** — Upgraded from warning to error. The MCP spec uses MUST for the `[A-Za-z0-9._-]{1,128}` format; non-conforming names may break clients.
+- **README template** — `polish-docs-meta` reference updated: scoped package names in `<h1>`, count line (tools · resources · prompts), framework badge linking to `@cyanheads/mcp-ts-core`.
+- **Docs & skills** — Added JSON-Schema-serializable type guidance to `CLAUDE.md`, `add-tool`, `design-mcp-server`, `field-test` skills, and `AGENTS.md`/`CLAUDE.md` templates.
+
+## Fixed
+
+- **`lint-mcp` task tool detection** — `isToolLike()` now recognizes task tools (which have `taskHandlers` instead of `handler`).
+- **`.dockerignore`** — Added `.git/` to version control exclusions.

package/changelog/0.1.x/0.1.23.md

@@ -0,0 +1,23 @@
+---
+summary: Config correctness and transport resilience — env boolean coercion fix, optional OTel startup hardening, Docker OTel opt-in build arg
+breaking: false
+---
+
+# 0.1.23 — 2026-03-21
+
+Config correctness, transport resilience, and example cleanup.
+
+## Fixed
+
+- **String boolean coercion** — Added `envBoolean` preprocessor for OpenTelemetry and Speech config booleans. `z.coerce.boolean()` treats `"false"` as `true` (non-empty string); the new preprocessor correctly parses `"true"`/`"1"` as `true` and everything else as `false`.
+- **Missing `@hono/otel` handling** — HTTP transport now logs a warning instead of throwing `configurationError` when `@hono/otel` is not installed with OTel enabled. Prevents hard startup failures for optional instrumentation.
+
+## Added
+
+- **Docker OTel opt-in** — `OTEL_ENABLED=true` build arg conditionally installs OpenTelemetry peer dependencies in the production image. Base image stays lean by default.
+
+## Changed
+
+- **Example annotations** — Removed redundant `idempotentHint` from all example tool definitions (flagged by 0.1.22 linter as redundant when `readOnlyHint: true`).
+- **`js-yaml` dev dependency** — Bumped from `^4.1.0` to `^4.1.1`.
+- **`server.json` description** — Expanded to describe core capabilities.

package/changelog/0.1.x/0.1.24.md

@@ -0,0 +1,17 @@
+---
+summary: Docker OTel enabled by default, Worker transport type fix, SessionAwareTaskStore async correctness
+breaking: false
+---
+
+# 0.1.24 — 2026-03-21
+
+Docker OTel default, Worker transport fix, and task store async correctness.
+
+## Changed
+
+- **Docker OTel default** — `OTEL_ENABLED` build arg now defaults to `true` in both the framework and template Dockerfiles. Docker images ship with OpenTelemetry instrumentation enabled out of the box.
+
+## Fixed
+
+- **Worker transport type** — `createWorkerHandler()` now sets `MCP_TRANSPORT_TYPE=http` in the Worker environment. Workers are always HTTP; without this, `context.ts` could not determine the correct transport for tenant isolation.
+- **`SessionAwareTaskStore` async correctness** — `getTask()` and `getTaskResult()` are now properly `async` with explicit `await` on inner delegate calls. Previously returned bare promises without the `async` keyword, which could mask exceptions thrown by `assertOwnership()`.

package/changelog/0.1.x/0.1.25.md

@@ -0,0 +1,16 @@
+---
+summary: Consumer identity resolution — parseConfig reads consumer package.json, OTEL service identity propagated from createApp name and version
+breaking: false
+---
+
+# 0.1.25 — 2026-03-21
+
+Consumer identity resolution and OTEL service identity propagation.
+
+## Fixed
+
+- **Consumer package.json resolution** — `parseConfig()` now reads the consumer project's `package.json` from `process.cwd()` to resolve server name, version, and description. Previously fell through directly to the framework's own `package.json`, causing consumer servers to report the framework's identity. Resolution order: env var → consumer `package.json` → framework `package.json`.
+
+## Changed
+
+- **OTEL service identity** — `createApp({ name, version })` now propagates to `OTEL_SERVICE_NAME` and `OTEL_SERVICE_VERSION` (via `??=`), ensuring telemetry reflects the actual server identity rather than requiring separate env var configuration.