@cyanheads/mcp-ts-core 0.9.14 → 0.9.16

package/AGENTS.md

@@ -0,0 +1,559 @@
+# Developer Protocol
+
+**Package:** `@cyanheads/mcp-ts-core`
+**Version:** 0.9.16
+**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 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 share the same public API. Init copies starter `package.json`, configs (`tsconfig`, `biome.json`, `vitest.config.ts`), `.env.example`, `Dockerfile`, `CLAUDE.md`/`AGENTS.md`, and example definitions. `_`-prefixed files (e.g. `_.gitignore`) drop the prefix on copy. After init, consult the `setup` skill.
+
+---
+
+## Core Rules
+
+- **Logic throws, framework catches.** Pure, stateless `handler` functions, no `try/catch`. Plain `Error` works — framework catches, classifies, formats. Use `McpError(code, message, data, options?)` only when you need a specific JSON-RPC code or structured data; 4th arg `{ cause }` chains.
+- **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. Shareable between agents and across users in single-tenant deployments. Tools accept token in `input` (omit to create fresh) and return in `output`; collaboration is opt-in via token exchange.
+- **Runtime parity.** All features work across `stdio`/`http`/Worker. Guard non-portable deps via `runtimeCaps` from `/utils` (`isNode`, `isBun`, `isWorkerLike`, `hasBuffer`, `hasProcess`, etc.). Prefer runtime-agnostic abstractions (Hono, Fetch APIs).
+- **Definition linting is build-time only.** Run `bun run lint:mcp` (standalone) or `bun run devcheck` (gate). Not invoked at server startup — new lint rules are additive and never break deployed servers. 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.
+- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
+
+---
+
+## Exports Reference
+
+| Subpath | Key Exports | Purpose |
+|:--------|:------------|:--------|
+| `@cyanheads/mcp-ts-core` | `createApp`, `tool`, `resource`, `prompt`, `appTool`, `appResource`, `APP_RESOURCE_MIME_TYPE`, `Context`, `createFail`, `createRecoveryFor`, `TypedFail`, `TypedRecoveryFor`, `ReasonOf`, `HandlerContext`, `Enrich`, `EnrichHelpers`, `TypedEnrich`, `z` | Main entry point |
+| `/worker` | `createWorkerHandler`, `CloudflareBindings` | Cloudflare Workers entry |
+| `/tools` | `ToolDefinition`, `AnyToolDefinition`, `ToolAnnotations` | Tool definition types |
+| `/resources` | `ResourceDefinition`, `AnyResourceDefinition` | Resource definition types |
+| `/prompts` | `PromptDefinition` | Prompt definition type |
+| `/tasks` | `TaskToolDefinition`, `isTaskToolDefinition` | Task tool escape hatch |
+| `/errors` | `McpError`, `JsonRpcErrorCode`, `notFound`, `validationError`, `unauthorized`, ... | Error types, codes, and factory functions |
+| `/config` | `AppConfig`, `config`, `parseConfig`, `parseEnvConfig`, `resetConfig`, `ConfigSchema`, `FRAMEWORK_NAME`, `FRAMEWORK_VERSION` | Zod-validated config, framework identity, env-var helper |
+| `/auth` | `checkScopes` | Dynamic scope checking |
+| `/storage` | `StorageService` | Storage abstraction |
+| `/storage/types` | `IStorageProvider` | Provider interface |
+| `/canvas` | `DataCanvas`, `CanvasInstance`, `CanvasRegistry`, `IDataCanvasProvider`, `DuckdbProvider`, `spillover`, `inferSchemaFromRows`, `assertReadOnlyQuery`, `quoteIdentifier`, ... | DataCanvas primitive (Tier 3, optional peer dep `@duckdb/node-api`); SQL/analytical workspace + source-agnostic spillover helper |
+| `/utils` | formatting, encoding, network, pagination, logging, runtime, telemetry, token counting, parsers†, sanitization†, scheduling† | All utilities (†optional peer deps) |
+| `/services` | `OpenRouterProvider`, `SpeechService`, `createSpeechProvider`, `ElevenLabsProvider`, `WhisperProvider`, `GraphService`, provider interfaces and types | LLM, Speech (TTS/STT), Graph services |
+| `/linter` | `validateDefinitions`, `LintReport`, `LintDiagnostic`, `LintInput`, `LintSeverity` | Definition validation |
+| `/testing` | `createMockContext`, `getEnrichment` | Test helpers |
+| `/testing/fuzz` | `fuzzTool`, `fuzzResource`, `fuzzPrompt`, `zodToArbitrary`, `adversarialArbitrary`, `ADVERSARIAL_STRINGS` | Fuzz testing |
+
+All subpaths prefixed with `@cyanheads/mcp-ts-core`. **†Tier 3 modules** require optional peer dependencies — see `package.json` `peerDependencies`. Tier 3 methods that lazy-load deps are **async**.
+
+### Import conventions
+
+```ts
+// Framework (from node_modules) — z is re-exported, no separate zod import needed
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+// Server's own code (via path alias)
+import { getMyService } from '@/services/my-domain/my-service.js';
+```
+
+Build configs exported for consumer extension: `tsconfig.json` extends `@cyanheads/mcp-ts-core/tsconfig.base.json`, `biome.json` extends `@cyanheads/mcp-ts-core/biome`, `vitest.config.ts` spreads from `@cyanheads/mcp-ts-core/vitest.config`.
+
+---
+
+## Entry Points
+
+### Node.js — `createApp(options)`
+
+```ts
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { allToolDefinitions } from './mcp-server/tools/index.js';
+import { allResourceDefinitions } from './mcp-server/resources/index.js';
+import { allPromptDefinitions } from './mcp-server/prompts/index.js';
+
+await createApp({
+  name: 'my-mcp-server',           // overrides package.json / MCP_SERVER_NAME
+  version: '0.1.0',                // overrides package.json / MCP_SERVER_VERSION
+  tools: allToolDefinitions,
+  resources: allResourceDefinitions,
+  prompts: allPromptDefinitions,
+  instructions:                     // server-level orientation, sent on every initialize
+    'Pre-configured shortcuts:\n- `default` → production API\n' +
+    'Other endpoints reachable via `connect({ baseUrl })`.',
+  extensions: {                     // SEP-2133 extensions advertised in capabilities
+    'vendor/my-extension': { /* extension config */ },
+  },
+  setup(core) {                     // runs after core services init, before transport starts
+    initMyService(core.config, core.storage);
+  },
+});
+```
+
+**`instructions`** — Optional server-level orientation, surfaced on every `initialize` response as session-level system context. Use for deployment-specific guidance (connection aliases, regional notes, scope hints) instead of repeating in tool descriptions. Client adoption uneven but no downside when set.
+
+### Cloudflare Workers — `createWorkerHandler(options)`
+
+```ts
+import { createWorkerHandler } from '@cyanheads/mcp-ts-core/worker';
+
+export default createWorkerHandler({
+  tools: allToolDefinitions,
+  resources: allResourceDefinitions,
+  prompts: allPromptDefinitions,
+  instructions: (env) => `Region: ${env.ENVIRONMENT ?? 'production'}`,  // string | (env) => string
+  setup(core) { initMyService(core.config, core.storage); },
+  extraEnvBindings: [['MY_API_KEY', 'MY_API_KEY']],       // string values → process.env
+  extraObjectBindings: [['MY_CUSTOM_KV', 'MY_CUSTOM_KV']], // KV/R2/D1 → globalThis
+  onScheduled: async (controller, env, ctx) => { /* cron */ },
+});
+```
+
+Per-request `McpServer` factory (security: SDK GHSA-345p-7cg4-v4c7). Requires `compatibility_flags = ["nodejs_compat"]` and `compatibility_date >= "2025-09-01"` in `wrangler.toml`. Only `in-memory`, `cloudflare-r2`, `cloudflare-kv`, `cloudflare-d1` storage in Workers. See `api-workers` skill for full details.
+
+### Interfaces
+
+`createApp()` returns `Promise<ServerHandle>`. `createWorkerHandler()` returns an `ExportedHandler`.
+
+```ts
+interface CoreServices {
+  config: AppConfig;
+  logger: Logger;
+  storage: StorageService;
+  rateLimiter: RateLimiter;
+  llmProvider?: ILlmProvider;
+  speechService?: SpeechService;
+  supabase?: SupabaseClient;
+}
+
+interface ServerHandle {
+  shutdown(signal?: string): Promise<void>;
+  readonly services: CoreServices;
+}
+```
+
+---
+
+## Server Structure
+
+```text
+src/
+  index.ts                              # createApp() entry point
+  worker.ts                             # createWorkerHandler() (if using Workers)
+  config/
+    server-config.ts                    # Server-specific env vars (own Zod schema)
+  services/
+    [domain]/
+      [domain]-service.ts               # Domain service (init/accessor pattern)
+      types.ts                          # Domain types
+  mcp-server/
+    tools/definitions/
+      [tool-name].tool.ts               # Tool definitions
+      index.ts                          # allToolDefinitions barrel
+    resources/definitions/
+      [resource-name].resource.ts       # Resource definitions
+      index.ts                          # allResourceDefinitions barrel
+    prompts/definitions/
+      [prompt-name].prompt.ts           # Prompt definitions
+      index.ts                          # allPromptDefinitions barrel
+```
+
+**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).
+
+---
+
+## Adding a Tool
+
+```ts
+import { tool, z } from '@cyanheads/mcp-ts-core';
+
+export const myTool = tool('my_tool', {
+  description: 'Does something useful.',
+  annotations: { readOnlyHint: true },
+  input: z.object({ query: z.string().describe('Search query') }),
+  output: z.object({
+    items: z.array(z.object({
+      id: z.string().describe('Item ID'),
+      name: z.string().describe('Item name'),
+      status: z.string().describe('Current status'),
+      description: z.string().optional().describe('Item description'),
+    })).describe('Matching items'),
+    totalCount: z.number().describe('Total matches before pagination'),
+  }),
+  auth: ['tool:my_tool:read'],
+
+  async handler(input, ctx) {
+    const data = await fetchFromApi(input.query);
+    ctx.log.info('Query resolved', { query: input.query, resultCount: data.items.length });
+    return data;
+  },
+
+  format: (result) => {
+    const lines = [`**${result.totalCount} results**\n`];
+    for (const item of result.items) {
+      lines.push(`### ${item.name}`);
+      lines.push(`**ID:** ${item.id} | **Status:** ${item.status}`);
+      if (item.description) lines.push(item.description);
+    }
+    return [{ type: 'text', text: lines.join('\n') }];
+  },
+});
+```
+
+**Steps:** Create `src/mcp-server/tools/definitions/[name].tool.ts` (kebab-case) → use `tool('snake_case', {...})` with Zod `.describe()` on all fields → implement `handler(input, ctx)` (pure, throws on failure) → add `auth`/`format` if needed → register in `definitions/index.ts` → `bun run devcheck` → smoke-test with `bun run rebuild && bun run start:stdio` (or `start:http`).
+
+**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 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.
+
+- **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`.
+
+**`enrichment`** (optional): The success-path counterpart to `errors[]` — a `ZodRawShape` of agent-facing context (empty-result notices, query/filter echo, pagination totals) that must reach both client surfaces. Populate via `ctx.enrich(...)` (or `ctx.enrich.notice()` / `.total()` / `.echo()`) in the handler or service layer. The framework merges it into `structuredContent`, advertises `output.extend(enrichment)` as `outputSchema`, and mirrors it into a `content[]` trailer — so it reaches `structuredContent`-only and `content[]`-only clients alike, with no `format()` entry. Keys must be disjoint from `output`; a required field never populated fails the effective-output parse. See `api-context`'s `ctx.enrich`.
+
+**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.
+
+---
+
+## Adding a Resource
+
+**Tool coverage.** Not all MCP clients expose resources — many are tool-only. Verify that resource data is also reachable via the tool surface before relying on resources as an access path.
+
+```ts
+import { resource, z } from '@cyanheads/mcp-ts-core';
+
+export const myResource = resource('myscheme://{itemId}/data', {
+  description: 'Retrieve item data by ID.',
+  mimeType: 'application/json',
+  params: z.object({ itemId: z.string().describe('Item identifier') }),
+  auth: ['item:read'],
+  async handler(params, ctx) {
+    return { id: params.itemId, status: 'active' };
+  },
+  list: async () => ({
+    resources: [{ uri: 'myscheme://all', name: 'All Items', mimeType: 'application/json' }],
+  }),
+});
+```
+
+Handler receives `(params, ctx)` — URI on `ctx.uri` if needed. Optional `size` (bytes) for content size metadata. Large lists must use `extractCursor`/`paginateArray` from `/utils`.
+
+---
+
+## Context
+
+```ts
+interface Context {
+  readonly requestId: string;
+  readonly timestamp: string;
+  readonly tenantId?: string;
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly auth?: AuthContext;
+  readonly log: ContextLogger;                // auto-correlated: requestId, traceId, tenantId
+  readonly state: ContextState;               // tenant-scoped KV storage
+  readonly elicit?: (message: string, schema: z.ZodObject<any>) => Promise<ElicitResult>;
+  readonly sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
+  readonly notifyResourceListChanged?: (() => void) | undefined;   // resource list changed
+  readonly notifyResourceUpdated?: ((uri: string) => void) | undefined; // resource content changed
+  readonly signal: AbortSignal;               // cancellation
+  readonly progress?: ContextProgress;        // present when task: true
+  readonly uri?: URL;                         // present for resource handlers
+  readonly enrich: Enrich;                    // success-path agent context → structuredContent + content[]; typed on HandlerContext<R, E>
+  recoveryFor(reason: string): { recovery: { hint: string } } | {};  // opt-in contract resolver
+}
+```
+
+### `ctx.log`
+
+Opt-in domain-specific logging. Methods: `debug`, `info`, `notice`, `warning`, `error`. Auto-includes `requestId`, `traceId`, `tenantId`, `spanId`. Use `ctx.log` in handlers; global `logger` for startup/shutdown/background.
+
+### `ctx.state`
+
+Tenant-scoped KV. Accepts any serializable value — no manual `JSON.stringify`/`JSON.parse` needed.
+
+```ts
+await ctx.state.set('item:123', { name: 'Widget', count: 42 });
+await ctx.state.set('item:123', data, { ttl: 3600 });           // with TTL (seconds)
+const item = await ctx.state.get<Item>('item:123');              // T | null
+const safe = await ctx.state.get('item:123', ItemSchema);        // Zod-validated T | null
+await ctx.state.delete('item:123');
+const values = await ctx.state.getMany<Item>(['item:1', 'item:2']); // Map<string, T>
+const page = await ctx.state.list('item:', { cursor, limit: 20 });  // { items, cursor? }
+```
+
+Throws `McpError(InvalidRequest)` if `tenantId` missing. Tenant ID resolution:
+
+| Mode | `tenantId` source |
+|:-----|:------------------|
+| stdio (any auth) | `'default'` |
+| HTTP + `MCP_AUTH_MODE=none` | `'default'` (single-tenant by design) |
+| HTTP + `MCP_AUTH_MODE=jwt`/`oauth` | JWT `'tid'` claim — fail-closed if absent |
+
+### `ctx.elicit` / `ctx.sample`
+
+Check for presence before calling:
+
+```ts
+if (ctx.elicit) {
+  const result = await ctx.elicit('What format?', z.object({
+    format: z.enum(['json', 'csv']).describe('Output format'),
+  }));
+  if (result.action === 'accept') useFormat(result.content.format);
+}
+```
+
+### `ctx.progress`
+
+Present when `task: true`. Methods: `setTotal(n)`, `increment(amount?)`, `update(message)`.
+
+See `api-context` skill for full details.
+
+---
+
+## Error Handling
+
+**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, recovery, retryable? }]` to `tool()` / `resource()`. Handler gets `ctx.fail(reason, msg?, data?)` typed against the reason union — typos fail at compile time. Runtime auto-populates `data.reason` for observability; linter enforces conformance against the handler body. `recovery` is required (≥5 words, lint-validated) — the single source of truth for the wire hint. Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire (framework mirrors `data.recovery.hint` into `content[]` text); override with explicit `{ recovery: { hint: '...' } }` when runtime context matters.
+
+```ts
+errors: [
+  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+    when: 'No PMID returned data',
+    recovery: 'Try pubmed_search_articles to discover valid PMIDs first.' },
+  { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
+    when: 'Queue at capacity', retryable: true,
+    recovery: 'Wait 30 seconds before retrying or reduce batch size.' },
+],
+async handler(input, ctx) {
+  // Static recovery — pulled from the contract via ctx.recoveryFor.
+  if (queue.full()) throw ctx.fail('queue_full', undefined, { ...ctx.recoveryFor('queue_full') });
+  // Dynamic recovery — interpolate runtime context, override the contract default.
+  if (!matched) throw ctx.fail('no_match', `No data for ${input.pmids.length} PMIDs`, {
+    pmids: input.pmids,
+    recovery: { hint: `Use pubmed_search_articles to discover valid PMIDs.` },
+  });
+}
+```
+
+**`ctx.recoveryFor(reason)`** returns `{}` when no contract exists (spread-safe). Typed against the declared reason union on `HandlerContext<R>`. Works in services: `throw validationError(msg, { reason: 'X', ...ctx.recoveryFor('X') })`. Opt-in — author spreads explicitly.
+
+**Contracts are inline, per-tool.** Don't extract shared `errors[]` constants — locality is the point, and dynamic `recovery` hints need tool-specific context. Declare domain-specific failures only; **baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) are auto-allowed by conformance lint. The lint scans handler source only — service-layer throws still reach clients via auto-classification.
+
+**Fallback for ad-hoc throws** (no contract entry fits, prototype tools, service-layer code): use error factories.
+
+```ts
+import { notFound, validationError } from '@cyanheads/mcp-ts-core/errors';
+throw notFound('Item not found', { itemId: '123' });
+throw validationError('Missing required field: name', { field: 'name' });
+```
+
+Available factories: `invalidParams`, `invalidRequest`, `notFound`, `forbidden`, `unauthorized`, `validationError`, `conflict`, `rateLimited`, `timeout`, `serviceUnavailable`, `configurationError`, `internalError`, `serializationError`, `databaseError`. All accept `(message, data?, options?)` where `options` is `{ cause?: unknown }`.
+
+For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { service, data })` from `/utils` — maps the full status table (401/403/408/422/429/5xx) and captures body + `Retry-After`.
+
+**Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: `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: `content[]` carries markdown with `data.recovery.hint`; `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope.
+
+**Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`. See `api-linter` skill.
+
+See `api-errors` skill for the full pattern-matching table, error code reference, and detailed examples.
+
+---
+
+## Auth
+
+Inline `auth` on definitions (primary pattern): `auth: ['tool:my_tool:read']`. Handler factory checks scopes before calling handler. Dynamic scopes via `checkScopes(ctx, [...])` from `/auth`.
+
+**Scope naming:** colon-delimited strings. Conventions used in this codebase:
+
+| Surface | Pattern | Example |
+|:--------|:--------|:--------|
+| Tools | `tool:<snake_name>:<verb>` | `tool:inventory_search:read` |
+| Resources | `resource:<kebab-name>:<verb>` *or* domain-led `<domain>:<verb>` | `resource:echo-app-ui:read`, `inventory:read` |
+
+Pick one convention per server and stay consistent. Verbs are typically `read`, `write`, `admin`.
+
+**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** union `scp`, `scope`, and `mcp_tool_scopes` JWT claims. `mcp_tool_scopes` is the OIDC escape hatch (Authentik, Keycloak < 26.5, Zitadel). `MCP_AUTH_DISABLE_SCOPE_CHECKS=true` bypasses scope checks while preserving auth-context verification (signature/audience/issuer/expiry). Logs `WARNING` at startup.
+
+---
+
+## Configuration
+
+### Core config
+
+Managed by `@cyanheads/mcp-ts-core`. Validated via Zod. Precedence: `createApp()` overrides > env vars > `package.json` (reads `name` → `MCP_SERVER_NAME`, `version` → `MCP_SERVER_VERSION`).
+
+| 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`, `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_*` |
+
+### Server config (separate schema)
+
+Own Zod schema for domain-specific env vars. **Never merge with core's schema.** Lazy-parse — Workers inject env at request time via `injectEnvVars()`, so no top-level `process.env` reads. Prefer `parseEnvConfig(schema, envMap)` from `/config` over `schema.parse(...)` — it maps schema paths to env var names (`MY_API_KEY is missing` vs. `apiKey: expected string`). Raw `ZodError` from `setup()` is still caught and converted, but messages are worse. See `api-config` skill.
+
+---
+
+## Testing
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+import { myTool } from '@/mcp-server/tools/definitions/my-tool.tool.js';
+
+describe('myTool', () => {
+  it('returns expected output', async () => {
+    const ctx = createMockContext();
+    const result = await myTool.handler(myTool.input.parse({ query: 'hello' }), ctx);
+    expect(result.result).toBe('Found: hello');
+  });
+});
+```
+
+**`createMockContext` options:** `createMockContext()` (minimal), `{ tenantId: 'test-tenant' }` (enables state), `{ sample: vi.fn() }`, `{ elicit: vi.fn() }`, `{ progress: true }` (task progress).
+
+**Fuzz testing:** `fuzzTool`/`fuzzResource`/`fuzzPrompt` from `/testing/fuzz` generate valid and adversarial inputs from Zod schemas via `fast-check`, then assert handler invariants (no crashes, no prototype pollution, no stack trace leaks). Returns a `FuzzReport` for custom assertions.
+
+```ts
+import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';
+
+it('survives fuzz testing', async () => {
+  const report = await fuzzTool(myTool, { numRuns: 100 });
+  expect(report.crashes).toHaveLength(0);
+  expect(report.leaks).toHaveLength(0);
+  expect(report.prototypePollution).toBe(false);
+});
+```
+
+Options: `numRuns` (valid inputs, default 50), `numAdversarial` (adversarial inputs, default 30), `seed` (reproducibility), `timeout` (per-call ms, default 5000), `ctx` (`MockContextOptions` for stateful handlers). Also exports `zodToArbitrary(schema)` for custom property-based tests and `ADVERSARIAL_STRINGS` for targeted injection testing.
+
+**Vitest config:** Extend core config, add `@/` alias: `resolve: { alias: { '@/': new URL('./src/', import.meta.url).pathname } }`. Construct deps in `beforeEach`. Re-init services per suite.
+
+---
+
+## API Quick References
+
+Detailed method signatures, options, and examples live in skill files. Read the relevant skill before starting a task it covers.
+
+### Skill versioning
+
+Each `skills/<name>/SKILL.md` carries `metadata.version` in frontmatter. The `maintenance` skill's Phase A uses this to sync consumer copies — replaces the **entire skill directory** as one unit. Without a version bump, Phase A skips the skill (content-hash backstop catches drift, but noisier).
+
+**Policy:** Bump `metadata.version` when changing any file under `skills/<name>/` — SKILL.md is the single version knob for the directory. Typo/whitespace fixes exempt. One bump per release cycle suffices.
+
+Skills live in `skills/<name>/SKILL.md`. Read the relevant skill before starting a task it covers. The full list is discoverable via the agent's skill registry at session start.
+
+---
+
+## Code Style & Checklist
+
+- **Validation:** Zod schemas, all fields need `.describe()`. See Adding a Tool for the JSON-Schema-serializable constraint and form-client safety.
+- **Logging:** Framework auto-instruments all handler calls. `ctx.log` for domain-specific logging in handlers, global `logger` for lifecycle/background
+- **Errors:** handlers throw — error factories (`notFound()`, `validationError()`, etc.) when the code matters, plain `Error` for don't-care cases. Framework catches and classifies.
+- **Secrets:** server config only — no hardcoded credentials
+- **Naming:** kebab-case files, snake_case tool/resource/prompt names, correct suffix
+- **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:** 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
+- **Pagination:** large resource lists use `extractCursor`/`paginateArray`
+- **Registration:** definitions exported in `definitions/index.ts` barrel
+- **Tests:** `createMockContext()`, `.handler()` tested directly
+- **Gate:** `bun run devcheck` passes (includes MCP definition linting)
+- **Smoke-test:** `bun run rebuild && bun run start:stdio` (or `start:http`)
+
+---
+
+## Commands
+
+| Command | Purpose |
+|:--------|:--------|
+| `bun run build` | Build library output (`scripts/build.ts`) |
+| `bun run rebuild` | Clean and rebuild (`scripts/clean.ts` + `build`) |
+| `bun run devcheck` | **Use often.** Lint, format, typecheck, MCP definition linting, `bun audit`, `bun outdated` |
+| `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
+| `bun run lint:mcp` | Validate MCP definitions against spec |
+| `bun run format` | Auto-fix Biome lint/format issues (safe fixes only) |
+| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior, not just formatting |
+| `bun run test` | Unit/integration tests |
+| `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. Source of truth: `changelog/<major.minor>.x/<version>.md` — one file per release (e.g. `changelog/0.5.x/0.5.4.md`), shipped in the npm package for direct agent access. `changelog/template.md` is the format reference (never edited).
+
+`CHANGELOG.md` is a **navigation index** — clickable headers + one-line summaries from frontmatter. Regenerated by `bun run changelog:build`; `changelog:check` hard-fails on drift in devcheck. Never hand-edit — edit the per-version file and rerun the build.
+
+### Per-version file format
+
+```markdown
+---
+summary: "One-line headline, ≤350 chars, no markdown"  # required
+breaking: false                                         # optional, default false
+security: false                                         # optional, default false
+---
+
+# 0.5.4 — 2026-04-20
+
+## Added
+
+- ...
+```
+
+**Frontmatter fields:**
+
+| Field | Required | Purpose |
+|:------|:---------|:--------|
+| `summary` | yes | Rollup index line. ≤350 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. |
+| `agent-notes` | no | Free-form adoption notes for downstream `maintenance` agents — new files to create, fields to populate, skills to re-run, one-time migration steps. Not rendered in `CHANGELOG.md`; consumed only by agents running the `maintenance` skill on consumer projects. Omit when there's nothing to say. |
+
+Badge order when both set: `· ⚠️ Breaking · 🛡️ Security`. Summary > 350 chars or malformed boolean fails `changelog:check`.
+
+**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Omit empty sections. Pre-release versions consolidate as sub-headers inside the final version's file — no separate files per pre-release.
+
+---
+
+## Publishing
+
+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. After pushing, create a GitHub Release on the annotated tag (`gh release create v<VERSION> --verify-tag --notes-from-tag`) — no assets to attach, but the Release surfaces the tag's notes in the repo UI. **Skip the Docker build/push step** — this framework package is consumed via npm, not as a container image.
+
+**Tag annotations render as GitHub Release bodies** via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject must omit the version number (GitHub prepends `v<VERSION>:`). Body uses Keep a Changelog sections with bullets. See `changelog/template.md` for the full format reference including an example.

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.9.14
+**Version:** 0.9.16
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
 **Zod:** ^4.4.3
@@ -503,7 +503,8 @@ Skills live in `skills/<name>/SKILL.md`. Read the relevant skill before starting
 | `bun run devcheck` | **Use often.** Lint, format, typecheck, MCP definition linting, `bun audit`, `bun outdated` |
 | `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
 | `bun run lint:mcp` | Validate MCP definitions against spec |
-| `bun run format` | Auto-fix Biome lint/format issues |
+| `bun run format` | Auto-fix Biome lint/format issues (safe fixes only) |
+| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior, not just formatting |
 | `bun run test` | Unit/integration tests |
 | `bun run start:stdio` | Production mode (stdio, after build) |
 | `bun run start:http` | Production mode (HTTP, after build) |

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.9.14-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx)
+[![Version](https://img.shields.io/badge/Version-0.9.16-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-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/) [![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.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
@@ -73,7 +73,7 @@ cd my-mcp-server
 bun install
 ```
 
-You get a scaffolded project with `CLAUDE.md`, Agent Skills, plugin metadata (Codex + Claude Code), 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.
+You get a scaffolded project with `CLAUDE.md`/`AGENTS.md`, Agent Skills, plugin metadata (Codex + Claude Code), 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 (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.
 
@@ -166,7 +166,7 @@ my-mcp-server/
       prompts/definitions/                # Prompt definitions (.prompt.ts)
   package.json
   tsconfig.json                           # extends @cyanheads/mcp-ts-core/tsconfig.base.json
-  CLAUDE.md                               # Points to core's CLAUDE.md for framework docs
+  CLAUDE.md / AGENTS.md                   # Point to core's CLAUDE.md / AGENTS.md for framework docs
 ```
 
 No `src/utils/`, no `src/storage/`, no `src/types-global/`, no `src/mcp-server/transports/` — infrastructure lives in `node_modules`.
@@ -187,7 +187,7 @@ All core config is Zod-validated from environment variables. Server-specific con
 | `OTEL_ENABLED` | Enable OpenTelemetry | `false` |
 | `OPENROUTER_API_KEY` | OpenRouter LLM API key | — |
 
-See [CLAUDE.md](CLAUDE.md) for the full configuration reference.
+See [CLAUDE.md/AGENTS.md](CLAUDE.md) for the full configuration reference.
 
 ## API overview