@cyanheads/mcp-ts-core 0.5.3 → 0.6.0

package/changelog/0.1.x/0.1.26.md

@@ -0,0 +1,22 @@
+---
+summary: Resource notification support — ctx.notifyResourceUpdated and ctx.notifyResourceListChanged for dynamic resource subscriptions, mock context support, dependency updates
+breaking: false
+---
+
+# 0.1.26 — 2026-03-23
+
+Resource notification support and dependency updates.
+
+## Added
+
+- **Resource notifications on Context** — `ctx.notifyResourceUpdated(uri)` and `ctx.notifyResourceListChanged()` let tool and resource handlers notify subscribed clients when dynamic resources change. Optional (like `elicit`/`sample`), presence-checked before use. Threaded through `ContextDeps`, handler factories, and both tool/resource registries.
+- **`createMockContext` notification support** — `MockContextOptions` accepts `notifyResourceUpdated` and `notifyResourceListChanged` for testing handlers that fire resource notifications.
+- **Resource notifications design doc** — `docs/resource-notifications.md` documents the gap, SDK surface, API design, and alternatives considered.
+
+## Changed
+
+- **`diff`** — 8.0.3 → 8.0.4
+- **`hono`** — 4.12.8 → 4.12.9
+- **`@supabase/supabase-js`** — ^2.99.3 → ^2.100.0
+- **`typedoc`** — ^0.28.17 → ^0.28.18
+- **`vite`** — 8.0.1 → 8.0.2

package/changelog/0.1.x/0.1.27.md

@@ -0,0 +1,30 @@
+---
+summary: Expanded OTel metrics instrumentation — tool/resource I/O histograms, HTTP client duration, eager metric initialization, comprehensive metrics test suite
+breaking: false
+---
+
+# 0.1.27 — 2026-03-23
+
+Expanded OTel metrics instrumentation, eager metric initialization, and app lifecycle improvements.
+
+## Added
+
+- **Tool I/O byte histograms** — `mcp.tool.input_bytes` and `mcp.tool.output_bytes` histograms record payload sizes per tool invocation.
+- **Tool parameter usage counter** — `mcp.tool.param.usage` tracks which parameters are supplied per tool call (top-level keys).
+- **Resource output bytes histogram** — `mcp.resource.output_bytes` records payload size for successful resource reads.
+- **HTTP client duration histogram** — `http.client.request.duration` (seconds) in `fetchWithTimeout`, with `http.request.method`, `server.address`, and `http.response.status_code` attributes.
+- **Rate limit rejection counter** — `mcp.ratelimit.rejections` with `mcp.rate_limit.key` attribute fires on every rate-limited request.
+- **Error classification counter** — `mcp.errors.classified` exposed via `initErrorMetrics()` for eager initialization.
+- **Event loop utilization gauge** — `process.event_loop.utilization` (0–1 ratio) complements the existing p99 delay gauge.
+- **Eager metric initialization** — `initSessionMetrics()`, `initErrorMetrics()`, `initRateLimitMetrics()`, `initHttpClientMetrics()`, `initHandlerMetrics()` called at startup so all metric series exist from the first export cycle.
+- **Comprehensive metrics test suite** — 10 new test files covering OTel metric recording for tools, resources, tasks, sessions, auth, storage, graph, LLM, speech, error handler, HTTP client, and rate limiter subsystems.
+
+## Changed
+
+- **Lint warnings use logger** — `composeServices()` collects lint warnings and defers logging until after logger initialization. No more `console.warn` at startup.
+- **Session gauge unconditional** — `mcp.sessions.active` observable gauge registered regardless of transport type (reports 0 for stdio/stateless).
+- **Shutdown cleanup** — Extracted `flushTelemetryAndLogger()` helper, added `taskManager.cleanup()`, fatal error handlers now create proper request contexts.
+- **`repomix`** — ^1.12.0 → ^1.13.0 (dev)
+- **`vitest`** — ^4.1.0 → ^4.1.1 (dev)
+- **`hono`** — ^4.12.8 → ^4.12.9
+- **`diff`** — ^8.0.3 → ^8.0.4

package/changelog/0.1.x/0.1.28.md

@@ -0,0 +1,16 @@
+---
+summary: TypeScript 6 migration — upgraded from 5.9 to 6.0, removed baseUrl from tsconfigs, switched path mappings to relative syntax, cleaned up duplicate typescript dependency
+breaking: false
+---
+
+# 0.1.28 — 2026-03-23
+
+TypeScript 6 migration and dependency updates.
+
+## Changed
+
+- **TypeScript 6** — upgraded from `^5.9.3` to `^6.0.2`; removed `baseUrl` from tsconfigs, switched path mappings to relative `./src/*` syntax.
+- **Removed duplicate `typescript`** from `dependencies` (remains in `devDependencies`).
+- **`@vitest/coverage-istanbul`** — 4.1.0 → 4.1.1 (dev)
+- **`@vitest/ui`** — 4.1.0 → 4.1.1 (dev)
+- **`fast-xml-parser`** — ^5.5.8 → ^5.5.9 (peer)

package/changelog/0.1.x/0.1.29.md

@@ -0,0 +1,19 @@
+---
+summary: Linter fix for idempotentHint false positive, skill doc improvements for design and polish-docs-meta, dependency updates
+breaking: false
+---
+
+# 0.1.29 — 2026-03-24
+
+Linter fix, skill doc improvements, and dependency updates.
+
+## Fixed
+
+- **Linter annotation-coherence** — removed `idempotentHint` redundancy warning for `readOnlyHint: true` tools. Explicit `idempotentHint` is valid and correct, not redundant.
+
+## Changed
+
+- **`design-mcp-server` skill** — added tool audit step, convenience shortcuts pattern, expanded naming convention (`{domain}_{verb}_{noun}`), optional design doc sections.
+- **`polish-docs-meta` skill** — added GitHub repo metadata sync step, description-as-canonical-source guidance, Dockerfile OCI label alignment.
+- **`@modelcontextprotocol/ext-apps`** — ^1.2.2 → ^1.3.1
+- **`fast-xml-parser`** — ^5.5.9 → latest (peer dep)

package/changelog/0.1.x/0.1.3.md

@@ -0,0 +1,22 @@
+---
+summary: Housekeeping release — regex fix for skill audience extraction, version alignment, removal of obsolete planning docs and schemas
+breaking: false
+---
+
+# 0.1.3 — 2026-03-14
+
+Housekeeping release: regex fix for skill audience extraction, version alignment across manifests, and removal of obsolete planning docs and schemas.
+
+## Fixed
+
+- `extractAudience` regex in `init` CLI now handles sibling keys before `audience:` under `metadata:` in skill frontmatter.
+
+## Removed
+
+- `core-extraction/` planning docs (14 files) — extraction complete, no longer needed.
+- `docs/mcp-apps.md`, `docs/mcp-elicitation-summary.md`, `docs/publishing-mcp-server-registry.md` — superseded by CLAUDE.md and skill files.
+- `schemas/cloudflare-d1-schema.sql` — D1 schema now managed by the framework internally.
+
+## Changed
+
+- `server.json` version aligned to 0.1.3 (was 0.1.1).

package/changelog/0.1.x/0.1.4.md

@@ -0,0 +1,17 @@
+---
+summary: Rebrand from mcp-ts-template to mcp-ts-core — Dockerfile labels, package metadata, repository URLs, and smithery command updated throughout
+breaking: false
+---
+
+# 0.1.4 — 2026-03-14
+
+Rebranding and version bump: repository URLs, Docker labels, and package metadata updated from `mcp-ts-template` to `mcp-ts-core`.
+
+## Changed
+
+- Dockerfile labels and log paths renamed from `mcp-ts-template` to `mcp-ts-core`.
+- `package.json` repository, bugs, and homepage URLs updated to `mcp-ts-core`.
+- `server.json` repository URL updated to `mcp-ts-core`.
+- `smithery.yaml` bunx command updated to `@cyanheads/mcp-ts-core`.
+- `docs/tree.md` regenerated to reflect current directory structure (removed obsolete planning docs and schemas).
+- Version bumped to 0.1.4 across `package.json`, `server.json`, and `README.md`.

package/changelog/0.1.x/0.1.5.md

@@ -0,0 +1,25 @@
+---
+summary: Security hardening and task tool auth fixes — scope enumeration prevention, ALS context capture for background handlers, structuredContent gating, HTTP session header correction
+breaking: false
+---
+
+# 0.1.5 — 2026-03-14
+
+Security hardening, task tool auth fixes, and transport correctness improvements.
+
+## Fixed
+
+- **Task tool auth context** — Auth info is now captured from the request's AsyncLocalStorage before the background handler fires. Previously, ALS was gone in the detached context, causing auth scopes and tenant identity to be lost. Scope checks now run in `createTask` (inside ALS) instead of the background handler.
+- **`withAuthInfo` operation inheritance** — `requestContextService.withAuthInfo()` now inherits the `operation` name from the parent context instead of hardcoding `'withAuthInfo'`, preserving operation traceability for task handlers.
+- **`structuredContent` conditional** — Tool responses only include `structuredContent` when the tool definition has an `output` schema. Prevents sending untyped data as structured content.
+- **HTTP session header for `auto` mode** — Session header now uses the resolved `isStateful` flag instead of comparing `config.mcpSessionMode === 'stateful'`, fixing stateful session headers when mode is `'auto'`.
+- **Config cache reset after `composeServices()`** — `resetConfig()` is now called after restoring env vars, preventing stale cached config from leaking into subsequent calls in the same process.
+
+## Security
+
+- **Scope enumeration prevention** — Auth error responses no longer include scope names, required scopes, or missing scopes in client-facing error data. Full details remain in server-side logs. Applies to both `withRequiredScopes` and `checkScopes`.
+
+## Changed
+
+- Bumped `js-yaml` optional peer dependency from `^3.14.2` to `^4.0.0`.
+- Setup skill: added "update dependencies to latest" as first post-install step.

package/changelog/0.1.x/0.1.6.md

@@ -0,0 +1,26 @@
+---
+summary: Task manager lifecycle fix, error metadata on responses, resource output validation, HTTP tenant isolation hardening, config override timing
+breaking: false
+---
+
+# 0.1.6 — 2026-03-16
+
+Task lifecycle improvements, error metadata for programmatic clients, resource output validation, and tenant isolation hardening.
+
+## Added
+
+- **Error metadata on tool responses** — Error responses now include `_meta.error` with the JSON-RPC error code and, for explicitly thrown `McpError` instances, the `data` payload. Programmatic clients can distinguish error types (auth, validation, not-found, etc.) without parsing the text message.
+- **Resource output validation** — Resource handler factory validates handler output against the `output` schema when defined, matching tool handler behavior.
+
+## Fixed
+
+- **Task manager lifecycle** — `TaskManager` is now created inside `composeServices()` and its `taskStore`/`taskMessageQueue` are passed directly to the `McpServer` constructor. Previously, the task manager was created after service composition in `createApp()`, which meant the SDK server had no task support wired in.
+- **Config override timing** — `name`/`version` overrides from `createApp()` options are now applied before OTEL initialization, so the telemetry service name reflects the actual server identity.
+- **Context TTL edge case** — `ctx.state.set()` and `ctx.state.setMany()` now use `opts?.ttl !== undefined` instead of a truthy check, allowing `ttl: 0` to be passed through correctly.
+- **HTTP tenant isolation** — HTTP transport without auth now leaves `tenantId` unset instead of defaulting to `'default'`. `ctx.state` operations fail-closed via `requireContext()`, preventing unauthenticated callers from sharing a single tenant namespace. Stdio continues to default to `'default'`.
+
+## Changed
+
+- Reverted `js-yaml` optional peer dependency from `^4.0.0` back to `^3.14.2`.
+- Updated dev dependencies: `@cloudflare/workers-types`, `@supabase/supabase-js`, `msw`, `openai`.
+- Improved HTTP transport port-detection test with proper `try/finally` cleanup.

package/changelog/0.1.x/0.1.7.md

@@ -0,0 +1,29 @@
+---
+summary: Telemetry slim-down — focused MCP attribute keys replace semconv, lighter OTel instrumentation, removed per-call memory profiling and unused metric exports
+breaking: false
+---
+
+# 0.1.7 — 2026-03-17
+
+Telemetry refactor: slimmed OTel instrumentation, replaced bloated semconv module with focused MCP attribute keys, removed per-call memory profiling.
+
+## Changed
+
+- **`semconv.ts` → `attributes.ts`** — Replaced the 377-line `semconv.ts` (which re-exported standard OTel constants) with a focused `attributes.ts` containing only MCP-specific and actively-used attribute keys. Standard OTel conventions (HTTP, cloud, service, network, etc.) should now be imported directly from `@opentelemetry/semantic-conventions`.
+- **`ATTR_CODE_FUNCTION` → `ATTR_CODE_FUNCTION_NAME`** — Renamed to align with upstream OTel semantic conventions deprecation of `code.function` in favor of `code.function.name`.
+- **Targeted HTTP instrumentation** — Replaced `@opentelemetry/auto-instrumentations-node` (heavy, pulls many transitive deps) with `@opentelemetry/instrumentation-http` for a lighter footprint. Pino instrumentation remains unchanged.
+- **Prompt measurement simplified** — `measurePromptGeneration` now emits a structured log only (no OTel span or metric instruments). Prompts are pure synchronous template functions; full spans were unnecessary overhead.
+- **Removed per-call memory profiling** — `measureToolExecution` no longer captures RSS/heap before/after/delta on every tool call. Reduces per-call overhead; use external process monitoring for memory tracking.
+- **Trimmed metrics API** — Removed `createObservableCounter` and `createObservableUpDownCounter` from public exports. Use `getMeter()` directly for these instrument types.
+- **`TextEncoder` caching** — `toBytes()` in performance module now reuses a singleton `TextEncoder` instead of allocating one per call.
+- **OTel shutdown timer leak fix** — `shutdownOpenTelemetry` now clears the timeout timer on successful shutdown.
+- Updated `msw` dev dependency from 2.12.11 to 2.12.12.
+- Updated `skills/api-utils/SKILL.md` to reflect new telemetry module names and trimmed metrics API.
+
+## Removed
+
+- `src/utils/telemetry/semconv.ts` — Replaced by `attributes.ts`.
+- `tests/utils/telemetry/semconv.test.ts` — Replaced by `attributes.test.ts`.
+- Memory tracking span attributes (`ATTR_MCP_TOOL_MEMORY_RSS_*`, `ATTR_MCP_TOOL_MEMORY_HEAP_USED_*`).
+- Unused standard OTel attribute re-exports (`ATTR_SERVICE_*`, `ATTR_HTTP_*`, `ATTR_CLOUD_*`, `ATTR_URL_*`, `ATTR_NETWORK_*`, `ATTR_ERROR_TYPE`, `ATTR_EXCEPTION_*`, `ATTR_USER_AGENT_ORIGINAL`, etc.).
+- Unused MCP attributes (`ATTR_MCP_REQUEST_ID`, `ATTR_MCP_OPERATION_NAME`, `ATTR_MCP_SESSION_ID`, `ATTR_MCP_TASK_ID`, `ATTR_MCP_PROMPT_*`).

package/changelog/0.1.x/0.1.8.md

@@ -0,0 +1,33 @@
+---
+summary: Tool output validation, HTTP graceful shutdown hardening, add-test and polish-docs-meta skills, design-mcp-server v2 rewrite
+breaking: false
+---
+
+# 0.1.8 — 2026-03-20
+
+Output validation for tools, HTTP transport hardening, new skills, and template improvements.
+
+## Added
+
+- **`add-test` skill** — Scaffolds colocated test files for tools, resources, and services with `createMockContext` patterns.
+- **`polish-docs-meta` skill** — Finalizes docs, README, metadata, and agent protocol for ship-ready servers. Includes reference guides for README conventions, agent protocol updates, package.json metadata, and server.json manifests.
+- **`design-mcp-server` v2.0** — Major rewrite of tool design guidance: consolidation via operation/mode enums, description and parameter writing principles, output design for LLM chaining, error messages as recovery guidance.
+- **`release` skill v1.1** — Expanded with README review step, template version sync, skill version bumping, annotated git tags, and structured checklist.
+
+## Fixed
+
+- **Tool output validation** — Standard and task tool handlers now validate output against the `output` schema (via `.parse()`) before formatting. Previously, unvalidated handler output was passed directly to `format` and `structuredContent`.
+- **HTTP graceful shutdown** — Added 5-second drain timeout with `server.closeAllConnections()` fallback for pre-existing connections (e.g., SSE streams) that `server.close()` alone doesn't terminate.
+
+## Changed
+
+- **`composeServices()` ordering** — Now runs before env override application in `createApp()`, with overrides re-applied for process lifetime after composition. Fixes edge case where OTEL/logger could see stale identity.
+- **`SamplingOpts.modelPreferences`** — Typed as SDK `ModelPreferences` instead of `Record<string, unknown>`.
+- **Session identity binding** — Per-field gating ensures `tenantId`, `clientId`, and `subject` get bound independently across separate requests, instead of all-or-nothing on first authenticated request.
+- **HTTP transport** — Extracted `extractSessionIdentity()` helper to deduplicate identity extraction across DELETE and POST handlers.
+- **`rateLimiter.dispose()`** — Called during graceful shutdown to clean up interval timers.
+- **Storage validation** — Removed redundant path traversal check (already covered by the regex pattern) and redundant `isFinite` check on list limit (already a `number` type).
+- **`polish` skill renamed to `polish-docs-meta`** — More descriptive name. Updated all references in CLAUDE.md, templates, and changelog. Refined reference doc wording.
+- **VSCode workspace config** — Added Biome as default formatter, markdownlint for markdown files, TypeScript SDK path, format-on-save. Added extension recommendations for Biome and markdownlint.
+- **Templates** — Expanded `.env.example` with HTTP endpoint path, Cloudflare storage options, and OTEL vars. Added common gitignore patterns. Added `bin` field to `package.json`. Added `format` function to echo tool. Fixed template version from 0.1.2 to 0.1.0. Added `add-test` and `polish-docs-meta` skills to agent protocol.
+- Updated dependencies: `@biomejs/biome` 2.4.7→2.4.8, `@supabase/supabase-js` ^2.99.2→^2.99.3, `@types/bun` ^1.3.10→^1.3.11, `bun-types` ^1.3.10→^1.3.11, `msw` ^2.12.12→^2.12.13, `openai` ^6.31.0→^6.32.0, `sanitize-html` ^2.17.1→^2.17.2, `vite` 8.0.0→8.0.1, `jose` ^6.2.1→^6.2.2.

package/changelog/0.1.x/0.1.9.md

@@ -0,0 +1,19 @@
+---
+summary: Markdown linting and formatting compliance — markdownlint config, 14 skill/doc fixes, labeled code blocks, biome schema bump
+breaking: false
+---
+
+# 0.1.9 — 2026-03-20
+
+Markdown linting, formatting fixes, and biome schema alignment.
+
+## Added
+
+- **`.markdownlint.jsonc`** — Markdownlint config suppressing false positives for changelog headings, inline HTML, first-line h1, and dense reference tables.
+
+## Changed
+
+- Fixed markdown formatting across 14 skill files, templates, and docs for markdownlint compliance: added blank lines around fenced code blocks, escaped pipe characters in tables, labeled unlabeled code blocks with `text` language tag.
+- Updated `scripts/tree.ts` to emit labeled code blocks (` ```text ` instead of bare ` ``` `).
+- Regenerated `docs/tree.md` with current structure (adds `Dockerfile` template and `.markdownlint.jsonc`).
+- Bumped `biome.json` schema URL to 2.4.8 (aligns with devDep already at 2.4.8).

package/changelog/0.2.x/0.2.0.md

@@ -0,0 +1,32 @@
+---
+summary: Fuzz testing framework with schema-aware property-based testing, retry utility with exponential backoff, GitHub issue templates, and issue reporting skills
+breaking: false
+---
+
+# 0.2.0 — 2026-03-24
+
+Fuzz testing framework, retry utility, GitHub issue templates, and issue reporting skills.
+
+## Added
+
+- **Fuzz testing module** — `fuzzTool`, `fuzzResource`, `fuzzPrompt` from `@cyanheads/mcp-ts-core/testing/fuzz`. Schema-aware property-based testing via `fast-check`: generates valid inputs from Zod schemas and adversarial payloads (prototype pollution, injection strings, type confusion), then asserts handler invariants (no crashes, no stack trace leaks, no prototype pollution). Returns `FuzzReport` for custom assertions.
+- **`zodToArbitrary`** — Converts Zod schemas to `fast-check` arbitraries for custom property-based tests.
+- **`ADVERSARIAL_STRINGS`** — Curated set of injection, encoding, and parsing attack strings for targeted testing.
+- **`./testing/fuzz` subpath export** — New package export for the fuzz testing module.
+- **Retry utility** — `withRetry` from `@cyanheads/mcp-ts-core/utils`. Exponential backoff with jitter, transient error classification (`ServiceUnavailable`, `Timeout`, `RateLimited`), abort signal support, and exhaustion enrichment (attempt count in error message and data).
+- **GitHub issue templates** — Structured YAML form templates for bug reports and feature requests in `.github/ISSUE_TEMPLATE/`. Includes version/runtime/transport dropdowns and redaction guidance. Scaffolded to consumer projects via `init`.
+- **Issue reporting skills** — `report-issue-framework` (file bugs against `@cyanheads/mcp-ts-core`) and `report-issue-local` (file bugs against the consumer server). Both include triage guidance, `gh` CLI examples, redaction checklist, and title/label conventions.
+- **Fuzz test suite** — Three test files (`tests/fuzz/`) covering definition fuzzing, error handler fuzzing, and tool handler pipeline fuzzing (~850 lines).
+- **Service resilience documentation** — `add-service` skill gains a "Resilience" section with retry-wraps-full-pipeline pattern, backoff calibration, and parse failure classification. `design-mcp-server` skill gains a resilience planning table.
+
+## Changed
+
+- **Biome config** — `noExplicitAny: off` for `src/testing/**` (fuzz module requires `any` for Zod introspection).
+- **Vitest config** — Added `tests/fuzz/**/*.test.ts` to include patterns.
+- **`setup` skill** — Documents `.github/ISSUE_TEMPLATE/` in scaffolding output.
+- **Template `CLAUDE.md`** — Added `report-issue-framework` and `report-issue-local` to skills table.
+- **`.gitignore`** — Added `announcements/` and `agent-feedback/` directories.
+
+## Fixed
+
+- **`jsonParser.test.ts`** — Replaced fragile `rejects.toThrow(new McpError(...))` assertion with try/catch checking error code and message substring. Fixes intermittent test failures from McpError equality semantics.

package/changelog/0.2.x/0.2.1.md

@@ -0,0 +1,12 @@
+---
+summary: Docker build fix for optional peer deps — local FxpModule interface replaces static type reference, unblocks multi-platform builds
+breaking: false
+---
+
+# 0.2.1 — 2026-03-25
+
+Docker build fix for optional peer dependencies.
+
+## Fixed
+
+- **`xmlParser` Docker build** — Replaced static `typeof import('fast-xml-parser')` type reference with a local `FxpModule` interface. TypeScript no longer requires the optional peer dep's type declarations at compile time, fixing Docker multi-platform builds where `fast-xml-parser` isn't installed in the build stage.

package/changelog/0.2.x/0.2.10.md

@@ -0,0 +1,38 @@
+---
+summary: Task session isolation fixes, devcheck audit resilience, and broad test coverage across app lifecycle, CLI scaffold, task registration, auth, and HTTP authz
+breaking: false
+---
+
+# 0.2.10 — 2026-03-30
+
+Task ownership, devcheck resilience, and internal cleanup.
+
+## Fixed
+
+- **Task session ownership persistence** — `SessionAwareTaskStore` no longer deletes ownership tracking when a task reaches a terminal state (`completed`/`failed`). Previously, completed tasks became visible to other sessions, violating session isolation. Ownership now persists through the full task lifecycle.
+- **Task list visibility for sessionless callers** — Sessionless `listTasks` calls now correctly return only unowned tasks, consistent with `StorageBackedTaskStore` behavior. Previously returned all tasks regardless of ownership.
+
+## Changed
+
+- **Devcheck audit resilience** — Security audit check now detects connection/registry failures and emits a warning instead of silently passing when the output doesn't resemble a valid audit response.
+- **Internal object construction** — Replaced spread-with-conditionals patterns in `ctx.state.list()` and `SessionAwareTaskStore.listTasks()` with explicit object construction for clarity.
+
+## Tests
+
+- Updated `SessionAwareTaskStore` tests to assert ownership retention through terminal states and correct sessionless visibility filtering.
+- **`core/app`** — Composition root lifecycle: service composition, name/version overrides, Supabase storage init, signal handler registration, graceful shutdown, OTel init failure resilience, lint warning logging, process gauge callbacks, fatal handler backstops.
+- **`cli/init`** — Scaffold command: `--help` output, unknown subcommand rejection, invalid project name validation, named project scaffolding with templates/scripts/skills, current-directory init with skip-existing behavior.
+- **`tool-registration.lifecycle`** — Task and auto-task registration: resource notification binding, `_meta` forwarding, duplicate name rejection across regular/task tools, missing services guard, experimental task API registration, auth scope enforcement, default/custom formatters, completed/failed result storage, cancellation detection, TTL timeout, task-store polling failure handling.
+- **`heartbeat`** — Monitor start/stop, disabled no-op, failure counting with metric emission, recovery logging and counter reset, dead connection declaration after threshold, early-stop guard.
+- **`jwtStrategy.mocked`** — Non-Error verification failure normalization via mocked `jose`.
+- **`http-authz.e2e`** — End-to-end scoped tool authorization against a fixture server: scoped callers invoke both public and protected tools, missing scope returns MCP authz error.
+- **`prompt-registration`** — Duplicate prompt name rejection, generation failure wrapping as `McpError`.
+- **`authMiddleware.metrics`** — Active span identity attribute recording with tenant/subject fallbacks.
+- **`authUtils`** — Parent request context passthrough for scope checking.
+- **`jwtStrategy`** — Issuer and audience verification when configured, wrong audience rejection.
+- **`oauthStrategy`** — Error and non-Error JWKS init failure wrapping, `aud` claim fallback for resource validation, non-Error verification failure normalization.
+
+## Infrastructure
+
+- **`tests/fixtures/auth-scoped-server.js`** — Minimal HTTP fixture server with one public and one scoped tool for authz e2e tests.
+- **`tests/helpers/server-process.ts`** — `resolveEntrypoint()`, `assertServerEntrypoint()`, and `startServerFromEntrypoint()` for custom fixture server spawning.

package/changelog/0.2.x/0.2.11.md

@@ -0,0 +1,29 @@
+---
+summary: SEP-2133 extensions support, resource size metadata, HTTP protocol error handling, startup log consolidation
+breaking: false
+---
+
+# 0.2.11 — 2026-04-01
+
+SEP-2133 extensions support, resource size metadata, HTTP protocol error handling, and startup log noise reduction.
+
+## Added
+
+- **SEP-2133 extensions** — `createApp()` and `createWorkerHandler()` accept an `extensions` option (`Record<string, object>`) to advertise SEP-2133 extensions in server capabilities.
+- **Resource `size` field** — `ResourceDefinition` now accepts an optional `size` (bytes) passed through to the SDK's resource metadata.
+
+## Fixed
+
+- **HTTP protocol error handling** — `httpErrorHandler` now detects `HTTPException` from `@hono/mcp` and honors its pre-built response instead of wrapping it in a generic JSON-RPC error. Active OTel span is annotated with the error detail.
+
+## Changed
+
+- **Startup log consolidation** — Replaced multiple info/notice registration logs with a single summary line listing registered tool/resource/prompt names. Individual registration messages downgraded from info/notice to debug across tool, resource, prompt, and roots registries.
+- **Rate limit flush log level** — Suppressed-message flush downgraded from warning to debug.
+
+## Dependencies
+
+- `@biomejs/biome` 2.4.9 → 2.4.10
+- `@cloudflare/workers-types` ^4.20260329.1 → ^4.20260401.1
+- `@modelcontextprotocol/sdk` ^1.28.0 → ^1.29.0
+- `@supabase/supabase-js` ^2.100.1 → ^2.101.1

package/changelog/0.2.x/0.2.12.md

@@ -0,0 +1,31 @@
+---
+summary: OTel metricReaders deprecation fix, form-client safety guidance for empty-string optional fields, dependency updates
+breaking: false
+---
+
+# 0.2.12 — 2026-04-03
+
+OTel deprecation fix, form-client safety guidance, and dependency updates.
+
+## Fixed
+
+- **OTel `metricReader` deprecation** — `NodeSDK` constructor now uses the plural `metricReaders` array option, silencing the deprecation warning introduced in `@opentelemetry/sdk-node@^0.214.0`. Closes #21.
+
+## Added
+
+- **Form-client safety guidance** — Documented the pattern where form-based MCP clients (MCP Inspector, web UIs) send optional object fields with empty-string inner values instead of `undefined`. Added handler guard patterns, test examples, and checklist items to the agent protocol (`CLAUDE.md`), `add-tool` skill, `api-testing` skill, and consumer template. Closes #22.
+
+## Tests
+
+- Aligned log level assertions in `roots-registration` and `server` tests with the startup log downgrade from 0.2.11 (info → debug).
+- Updated OTel lifecycle test to expect `metricReaders` array.
+
+## Dependencies
+
+- `dotenv` 17.3.1 → 17.4.0
+- `hono` 4.12.9 → 4.12.10
+- `@cloudflare/workers-types` ^4.20260401.1 → ^4.20260403.1
+- `@modelcontextprotocol/ext-apps` ^1.3.2 → ^1.5.0
+- `@types/node` ^25.5.0 → ^25.5.2
+- `validator` ^13.15.26 → ^13.15.35
+- Added `lodash` 4.18.1 (pinned override)

package/changelog/0.2.x/0.2.2.md

@@ -0,0 +1,19 @@
+---
+summary: Error category telemetry — new ErrorCategory type and classifier, mcp.tool.error_category OTel attribute, OpenTelemetry and SDK dependency bumps
+breaking: false
+---
+
+# 0.2.2 — 2026-03-26
+
+Error category telemetry, dependency updates, and minor cleanup.
+
+## Added
+
+- **Error category telemetry** — New `ErrorCategory` type (`'upstream'` | `'server'` | `'client'`) and `getErrorCategory()` classifier in error handler mappings. Tool error metrics now emit `mcp.tool.error_category` attribute, enabling dashboards to distinguish external API failures from internal bugs and bad input.
+- **`ATTR_MCP_TOOL_ERROR_CATEGORY`** — New OTel attribute constant for the error category dimension.
+
+## Changed
+
+- **Dependencies** — `@modelcontextprotocol/sdk` ^1.27.1 → ^1.28.0, `@opentelemetry/*` packages bumped (api ^1.9.1, SDK ^0.214.0, resources/metrics/trace ^2.6.1, instrumentation-pino ^0.60.0), `@biomejs/biome` 2.4.8 → 2.4.9, `vitest` 4.1.1 → 4.1.2, `vite` 8.0.2 → 8.0.3, `openai` ^6.33.0, `repomix` ^1.13.1, `@supabase/supabase-js` ^2.100.1.
+- **New runtime deps** — Added `picomatch` 2.3.2 and `yaml` 1.10.3 to dependencies.
+- **Minor refactors** — Simplified optional chaining in `authUtils.ts` and `trace.ts`.

package/changelog/0.2.x/0.2.3.md

@@ -0,0 +1,15 @@
+---
+summary: format() content-completeness guidance across docs and scaffolding, echo template clarification, minor dependency update
+breaking: false
+---
+
+# 0.2.3 — 2026-03-28
+
+`format()` content-completeness guidance and minor dependency update.
+
+## Changed
+
+- **`format()` content-completeness** — Clarified across all documentation and scaffolding that `format()` populates MCP `content[]`, which is the only field most LLM clients (Claude Code, VS Code Copilot, Cursor, Windsurf) forward to the model. `structuredContent` (from `output`) is for programmatic/machine use and is not reliably shown to the LLM. Updated `ToolDefinition` JSDoc, `CLAUDE.md`, `templates/CLAUDE.md`, `skills/add-tool`, and `skills/design-mcp-server` with richer example formatters, explicit warnings against thin one-liners, and new checklist items.
+- **`echo.tool.ts` template** — Added clarifying comment about `format()` content-completeness in the scaffolded echo tool.
+- **`polish-docs-meta` reference** — Added `LOGS_DIR` env var to the environment variable reference table.
+- **Dependencies** — `@modelcontextprotocol/ext-apps` ^1.3.1 → ^1.3.2.

package/changelog/0.2.x/0.2.4.md

@@ -0,0 +1,24 @@
+---
+summary: Server.json manifest linter with full spec validation, API efficiency patterns in service skill, dependency security overrides
+breaking: false
+---
+
+# 0.2.4 — 2026-03-28
+
+Server.json manifest linter, API efficiency patterns, and dependency security overrides.
+
+## Added
+
+- **Server.json manifest linter** — New `lintServerJson()` rule set validates `server.json` against the MCP server manifest spec (2025-12-11). Checks name format (reverse-DNS), description length, version (no ranges, semver), repository structure, packages (registryType, identifier, transport, arguments, env vars), remotes (transport constraints), and cross-validates version against `package.json`. Integrated into `validateDefinitions()` pipeline and `lint-mcp` CLI script.
+- **`LintDefinitionType`** — New exported type (`'tool' | 'resource' | 'prompt' | 'server-json'`) for lint diagnostics. Exported from `/linter` and main entry point.
+- **API efficiency guidance** — New section in `add-service` skill covering batch-over-N+1, field selection, and pagination awareness patterns. Added corresponding checklist item.
+- **Live API probing step** — `design-mcp-server` skill now includes a step to hit real API endpoints during research to verify response shapes, batch endpoints, field selection, pagination, and error formats.
+- **API efficiency planning table** — `design-mcp-server` skill gains a service design table for batch, field selection, request consolidation, and pagination decisions.
+
+## Changed
+
+- **`LintInput`** — Now accepts optional `serverJson` and `packageJson` fields for manifest and cross-validation.
+- **`lint-mcp.ts` script** — Discovers and parses `server.json` + `package.json` at project root, passes them to `validateDefinitions()`. Skips lint only when no definitions and no server.json found.
+- **Template `format()` example** — Updated `templates/AGENTS.md` and `templates/CLAUDE.md` with content-complete `format()` example and checklist item.
+- **CLAUDE.md** — Added API efficiency note to service documentation section.
+- **Dependency overrides** — Added `brace-expansion` 1.1.13, `handlebars` 4.7.9, `path-to-regexp` 8.4.0 to resolve security advisories in transitive dependencies.

package/changelog/0.2.x/0.2.5.md

@@ -0,0 +1,27 @@
+---
+summary: Batch partial success telemetry with auto-detection, new OTel attribute constants, tools-first design philosophy, expanded error classification guidance
+breaking: false
+---
+
+# 0.2.5 — 2026-03-28
+
+Batch partial success telemetry and tools-first design guidance.
+
+## Added
+
+- **Batch partial success telemetry** — `measureToolExecution` auto-detects when a tool handler returns a result with a non-empty `failed` array (the batch response pattern from the design skill). Sets `mcp.tool.partial_success`, `mcp.tool.batch.succeeded_count`, and `mcp.tool.batch.failed_count` span attributes and structured log fields. No manual instrumentation needed.
+- **`ATTR_MCP_TOOL_PARTIAL_SUCCESS`**, **`ATTR_MCP_TOOL_BATCH_SUCCEEDED`**, **`ATTR_MCP_TOOL_BATCH_FAILED`** — New OTel attribute constants exported from `/utils`.
+- **Batch input design section** — `design-mcp-server` skill gains guidance on when to accept array input, partial success output schema patterns, and telemetry integration.
+- **Error design section** — `design-mcp-server` and `add-tool` skills expanded with error classification by origin (client/upstream/not-found/auth/internal), error factory usage, and failure mode planning tables.
+
+## Changed
+
+- **Tools-first design philosophy** — Updated `design-mcp-server`, `add-resource`, and `CLAUDE.md` to clarify that tools are the primary interface. Resources are supplementary — many MCP clients (Claude Code, Cursor, most chat UIs) are tool-only. Design guidance now requires verifying that resource data is also reachable via the tool surface.
+- **`add-resource` skill v1.1** — Added tool coverage checklist item and guidance note.
+- **`add-tool` skill v1.1** — Expanded batch input/partial success patterns with full code examples, improved error classification section with factory usage.
+- **`api-utils` skill** — Updated telemetry attributes documentation for new batch/partial success attributes.
+
+## Tests
+
+- **Partial success detection** — Four new test cases in `performance.test.ts`: detects non-empty `failed` array, skips empty `failed`, handles missing `succeeded`, ignores non-object results.
+- **Attribute constants** — Four new tests in `attributes.test.ts` for `error_category`, `partial_success`, `batch.succeeded_count`, `batch.failed_count`.

package/changelog/0.2.x/0.2.6.md

@@ -0,0 +1,23 @@
+---
+summary: Empty server handler init fix, OpenTelemetry API moved to optional peer dep, expanded unit and integration test coverage
+breaking: false
+---
+
+# 0.2.6 — 2026-03-28
+
+Handler initialization for empty servers, OTel API moved to peer deps, and comprehensive test coverage expansion.
+
+## Fixed
+
+- **Empty/task-only server handler initialization** — `ToolRegistry`, `ResourceRegistry`, and `PromptRegistry` now call the SDK's `setToolRequestHandlers()` / `setResourceRequestHandlers()` / `setPromptRequestHandlers()` up front before registering definitions. Previously, servers with zero standard tools (or only task tools) would not expose `tools/list`, `resources/list`, or `prompts/list` handlers, causing clients to get method-not-found errors.
+
+## Changed
+
+- **`@opentelemetry/api` moved to optional peer dependency** — Reduces mandatory install footprint for servers that don't use OpenTelemetry. The package is still required when `OTEL_ENABLED=true`.
+
+## Tests
+
+- **New unit tests** — `sessionAwareTaskStore.test.ts` (session ownership enforcement), `checkScopes.test.ts` (dynamic scope checking), `httpTransport.lifecycle.test.ts` (port retry and shutdown lifecycle), `protectedResourceMetadata.test.ts` (OAuth protected resource metadata), `sessionIdUtils.runtime.test.ts` (Web Crypto session ID fallback), `mockContext.test.ts` (mock context logger, state, progress helpers), `retry.test.ts` (retry helper with backoff, jitter, cancellation, abort signal), `instrumentation.lifecycle.test.ts` (OTel init/shutdown, cloud provider detection, timeout handling).
+- **New test helper** — `default-server-mcp.ts` with shared MCP surface assertions for capabilities, discovery, protocol errors, and task operations.
+- **Expanded integration tests** — HTTP auth (protected resource metadata, SSE rejection), HTTP sessions (DELETE without session ID), HTTP transport (MCP surface, protocol version rejection, origin rejection), stdio (MCP surface assertions).
+- **Expanded unit tests** — Tool registration (task-only registry handler init), storage factory (Cloudflare R2/KV/D1 serverless providers, Supabase client injection, filesystem serverless rejection).

package/changelog/0.2.x/0.2.7.md

@@ -0,0 +1,23 @@
+---
+summary: Stdio heartbeat monitor for dead connection detection, session duration histogram, new OTel attributes and counters
+breaking: false
+---
+
+# 0.2.7 — 2026-03-28
+
+Stdio heartbeat monitor for dead connection detection, session duration telemetry.
+
+## Added
+
+- **Stdio heartbeat monitor** — `HeartbeatMonitor` periodically pings the connected client via the MCP `ping` method to detect dead connections (orphaned child processes, crashed hosts). Configurable via `MCP_HEARTBEAT_INTERVAL_MS` (default 30s, disabled by default since 0.2.8) and `MCP_HEARTBEAT_MISS_THRESHOLD` (default 3). Uses recursive `setTimeout` to prevent ping overlap. Triggers graceful shutdown on threshold breach.
+- **Session duration histogram** — New `mcp.session.duration` metric (seconds) records session lifetime on termination and stale cleanup. Emitted alongside existing session event counters.
+- **`ATTR_MCP_CONNECTION_TRANSPORT`** — New OTel attribute constant for heartbeat and connection metrics.
+- **`mcp.heartbeat.failures`** — New OTel counter tracking individual heartbeat ping failures, attributed by transport type.
+
+## Changed
+
+- **Session termination** — `SessionStore.terminate()` and stale cleanup now record duration via the new histogram. Stale cleanup hoists `getSessionMetrics()` outside the loop to avoid repeated lazy-init checks.
+
+## Tests
+
+- Updated prompt and resource registration test mocks to match new SDK handler initialization methods (`setPromptRequestHandlers`, `setResourceRequestHandlers`, `sendResourceListChanged`, `server.sendResourceUpdated`).

package/changelog/0.2.x/0.2.8.md

@@ -0,0 +1,12 @@
+---
+summary: Heartbeat disabled by default — stdio servers no longer self-terminate in dev mode or simple harnesses without a client
+breaking: false
+---
+
+# 0.2.8 — 2026-03-28
+
+Heartbeat disabled by default — opt-in only.
+
+## Fixed
+
+- **Heartbeat default changed to disabled** — `MCP_HEARTBEAT_INTERVAL_MS` now defaults to `0` (off). The 30s default caused stdio servers to self-terminate when run without a client (dev mode, manual testing, simple harnesses). Set `MCP_HEARTBEAT_INTERVAL_MS=30000` to enable.

package/changelog/0.2.x/0.2.9.md

@@ -0,0 +1,25 @@
+---
+summary: Cache negative lazy-import results to eliminate optional peer dep metric spam — new lazyImport utility, OpenRouter tryCatch fix
+breaking: false
+---
+
+# 0.2.9 — 2026-03-29
+
+Cache negative lazy-import results for optional peer deps to prevent metric spam.
+
+## Fixed
+
+- **Lazy-import metric spam** — Optional peer dependency loaders (`chrono-node`, `diff`, `papaparse`, `partial-json`, `pdf-lib`, `unpdf`, `js-yaml`, `openai`) now cache negative import results via the new `lazyImport()` utility. Previously, every call to a function backed by a missing peer dep would re-attempt the dynamic `import()`, throw a `ConfigurationError` through `ErrorHandler.tryCatch`, and increment the `mcp.errors.classified` counter — producing unbounded metric spam for a static configuration issue. Now: first failure logs a warning once and caches the state; subsequent calls throw immediately without retry or counter increment. Closes #20.
+- **OpenRouter client init outside tryCatch** — Moved `ensureClient()` call in `chatCompletion()` outside the `ErrorHandler.tryCatch` boundary so a missing `openai` peer dep does not inflate the classified error counter on every LLM call.
+
+## Added
+
+- **`lazyImport()` utility** (`src/utils/internal/lazyImport.ts`) — Generic lazy-loader factory for optional peer dependencies that caches both success and failure. Logs a warning on first failure, throws `ConfigurationError` on all subsequent calls without re-importing or touching error metrics.
+
+## Tests
+
+- Unit tests for `lazyImport()` covering success caching, failure caching, single-warning behavior, and instance isolation.
+
+## Changed
+
+- `@cloudflare/workers-types` updated to `^4.20260329.1`.