@cyanheads/mcp-ts-core 0.8.18 → 0.8.20

package/dist/mcp-server/transports/auth/lib/claimParser.js

@@ -1,10 +1,28 @@
 import { McpError, unauthorized } from '../../../../types-global/errors.js';
+/**
+ * Extracts a list of scope strings from a JWT claim value, accepting both
+ * array and space-delimited string forms. Non-string array entries cause
+ * the claim to be ignored entirely. Empty-string entries are dropped.
+ */
+function extractStringScopes(value) {
+    if (Array.isArray(value) && value.every((s) => typeof s === 'string')) {
+        return value.filter((s) => s.length > 0);
+    }
+    if (typeof value === 'string' && value.trim()) {
+        return value.split(' ').filter(Boolean);
+    }
+    return [];
+}
 /**
  * Builds an {@link AuthInfo} from a raw token string and decoded JWT payload.
  *
  * Claim resolution order:
  * - **clientId**: `cid` (Okta) → `client_id` (OAuth 2.1 standard)
- * - **scopes**: `scp` (Okta, array) → `scope` (standard, space-delimited string)
+ * - **scopes**: union of `scp` (Okta, array), `scope` (standard, space-delimited string),
+ *   and `mcp_tool_scopes` (custom claim for OIDC providers that cannot inject scopes
+ *   into `scope` during the `authorization_code` flow — Authentik, Keycloak < 26.5,
+ *   Zitadel). Operators add a property mapping returning
+ *   `{"mcp_tool_scopes": "tool:foo:read tool:bar:write"}` (string or array form accepted).
  * - **subject**: `sub` (standard)
  * - **tenantId**: `tid` (Azure AD / custom)
  * - **expiresAt**: `exp` (standard, seconds since epoch)
@@ -20,13 +38,11 @@ export function buildAuthInfoFromClaims(token, payload) {
     if (!clientId) {
         throw unauthorized("Invalid token: missing 'cid' or 'client_id' claim.");
     }
-    let scopes = [];
-    if (Array.isArray(payload.scp) && payload.scp.every((s) => typeof s === 'string')) {
-        scopes = payload.scp;
-    }
-    else if (typeof payload.scope === 'string' && payload.scope.trim()) {
-        scopes = payload.scope.split(' ').filter(Boolean);
-    }
+    const scopes = [
+        ...extractStringScopes(payload.scp),
+        ...extractStringScopes(payload.scope),
+        ...extractStringScopes(payload.mcp_tool_scopes),
+    ];
     if (scopes.length === 0) {
         throw unauthorized('Token must contain valid, non-empty scopes.');
     }

package/dist/mcp-server/transports/auth/lib/claimParser.js.map

@@ -1 +1 @@
-{"version":3,"file":"claimParser.js","sourceRoot":"","sources":["../../../../../src/mcp-server/transports/auth/lib/claimParser.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa,EAAE,OAAmB;IACxE,MAAM,QAAQ,GACZ,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ;QAC7B,CAAC,CAAC,OAAO,CAAC,GAAG;QACb,CAAC,CAAC,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ;YACrC,CAAC,CAAC,OAAO,CAAC,SAAS;YACnB,CAAC,CAAC,SAAS,CAAC;IAElB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,YAAY,CAAC,oDAAoD,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,MAAM,GAAa,EAAE,CAAC;IAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;QAClF,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IACvB,CAAC;SAAM,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QACrE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,YAAY,CAAC,6CAA6C,CAAC,CAAC;IACpE,CAAC;IAED,OAAO;QACL,KAAK;QACL,QAAQ;QACR,MAAM;QACN,GAAG,CAAC,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QACjE,GAAG,CAAC,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;KACnE,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAE,eAAuB;IAC3E,IAAI,KAAK,YAAY,QAAQ;QAAE,MAAM,KAAK,CAAC;IAE3C,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,eAAe,CAAC;IAEjG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"claimParser.js","sourceRoot":"","sources":["../../../../../src/mcp-server/transports/auth/lib/claimParser.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,KAAc;IACzC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;QACtE,OAAQ,KAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa,EAAE,OAAmB;IACxE,MAAM,QAAQ,GACZ,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ;QAC7B,CAAC,CAAC,OAAO,CAAC,GAAG;QACb,CAAC,CAAC,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ;YACrC,CAAC,CAAC,OAAO,CAAC,SAAS;YACnB,CAAC,CAAC,SAAS,CAAC;IAElB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,YAAY,CAAC,oDAAoD,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,MAAM,GAAG;QACb,GAAG,mBAAmB,CAAC,OAAO,CAAC,GAAG,CAAC;QACnC,GAAG,mBAAmB,CAAC,OAAO,CAAC,KAAK,CAAC;QACrC,GAAG,mBAAmB,CAAC,OAAO,CAAC,eAAe,CAAC;KAChD,CAAC;IAEF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,YAAY,CAAC,6CAA6C,CAAC,CAAC;IACpE,CAAC;IAED,OAAO;QACL,KAAK;QACL,QAAQ;QACR,MAAM;QACN,GAAG,CAAC,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QACjE,GAAG,CAAC,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;KACnE,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAE,eAAuB;IAC3E,IAAI,KAAK,YAAY,QAAQ;QAAE,MAAM,KAAK,CAAC;IAE3C,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,eAAe,CAAC;IAEjG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.8.18",
+  "version": "0.8.20",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -165,10 +165,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",
-    "@cloudflare/vitest-pool-workers": "^0.16.0",
-    "@cloudflare/workers-types": "^4.20260506.1",
+    "@cloudflare/vitest-pool-workers": "^0.16.3",
+    "@cloudflare/workers-types": "^4.20260509.1",
     "@duckdb/node-api": "^1.5.2-r.1",
-    "@hono/otel": "^1.1.1",
+    "@hono/otel": "^1.1.2",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.217.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.217.0",
     "@opentelemetry/instrumentation-http": "^0.217.0",
@@ -178,10 +178,10 @@
     "@opentelemetry/sdk-node": "^0.217.0",
     "@opentelemetry/sdk-trace-node": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.40.0",
-    "@supabase/supabase-js": "^2.105.3",
+    "@supabase/supabase-js": "^2.105.4",
     "@types/bun": "^1.3.13",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.6.2",
     "@types/papaparse": "^5.5.2",
     "@types/sanitize-html": "^2.16.1",
     "@types/validator": "^13.15.10",
@@ -195,11 +195,12 @@
     "diff": "^9.0.0",
     "execa": "^9.6.1",
     "fast-check": "^4.7.0",
+    "fast-xml-parser": "^5.7.3",
     "ignore": "^7.0.5",
     "js-yaml": "^4.1.1",
     "linkedom": "^0.18.12",
     "node-cron": "^4.2.1",
-    "openai": "^6.36.0",
+    "openai": "^6.37.0",
     "papaparse": "^5.5.3",
     "partial-json": "^0.1.7",
     "pdf-lib": "^1.17.1",
@@ -211,7 +212,7 @@
     "typescript": "^6.0.3",
     "unpdf": "^1.6.2",
     "validator": "^13.15.35",
-    "vite": "8.0.10",
+    "vite": "8.0.11",
     "vitest": "^4.1.5"
   },
   "keywords": [
@@ -219,13 +220,14 @@
     "agent-native",
     "ai",
     "ai-agent",
+    "bun",
     "cloudflare-workers",
     "declarative",
-    "edge",
     "framework",
     "llm",
     "mcp",
     "mcp-server",
+    "mcp-framework",
     "model-context-protocol",
     "observability",
     "opentelemetry",
@@ -246,8 +248,8 @@
   ],
   "packageManager": "bun@1.3.2",
   "engines": {
-    "bun": ">=1.2.0",
-    "node": ">=22.0.0"
+    "bun": ">=1.3.0",
+    "node": ">=24.0.0"
   },
   "depcheck": {
     "ignores": [
@@ -264,7 +266,7 @@
   },
   "dependencies": {
     "@hono/mcp": "^0.2.5",
-    "@hono/node-server": "^2.0.1",
+    "@hono/node-server": "^2.0.2",
     "@modelcontextprotocol/ext-apps": "^1.7.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentelemetry/api": "^1.9.1",

package/scripts/build-changelog.ts

@@ -6,23 +6,25 @@
  * YAML frontmatter declaring:
  *   • summary (required)  — ≤250-char headline, no markdown, one line
  *   • breaking (optional) — `true` flags releases with breaking changes
+ *   • security (optional) — `true` flags releases with security fixes
  *
  * The rollup is a thin **index**, not a copy of bodies — each entry is just a
  * clickable header + one-line summary. Full content stays in the per-version files.
  *
  * Rendered rollup entry:
- *   ## [X.Y.Z](changelog/N.N.x/X.Y.Z.md) — YYYY-MM-DD · ⚠️ Breaking
+ *   ## [X.Y.Z](changelog/N.N.x/X.Y.Z.md) — YYYY-MM-DD · ⚠️ Breaking · 🛡️ Security
  *
  *   <summary>
  *
- * (The `· ⚠️ Breaking` badge only appears when `breaking: true`.)
+ * Badges only render when their flag is `true`. Order is fixed: Breaking before
+ * Security when both are set.
  *
  * Modes:
  *   • default   → regenerate CHANGELOG.md
  *   • --check   → exit 1 if CHANGELOG.md differs from what would be generated
  *
  * Missing `summary`: warning (not failure) — the entry renders header-only.
- * Summary > 250 chars, or malformed `breaking`: hard error.
+ * Summary > 250 chars, or malformed `breaking` / `security`: hard error.
  *
  * @module scripts/build-changelog
  */
@@ -50,6 +52,7 @@ interface VersionEntry {
 
 interface Frontmatter {
   breaking: boolean;
+  security: boolean;
   summary: string | null;
 }
 
@@ -75,13 +78,13 @@ function compareSemverDesc(a: string, b: string): number {
 }
 
 /**
- * Parse minimal YAML frontmatter. Only recognizes `summary` and `breaking` —
- * other keys are ignored, so the format stays extensible without touching the
- * parser. Throws on malformed values we actually care about.
+ * Parse minimal YAML frontmatter. Only recognizes `summary`, `breaking`, and
+ * `security` — other keys are ignored, so the format stays extensible without
+ * touching the parser. Throws on malformed values we actually care about.
  */
 function parseFrontmatter(content: string, fileLabel: string): Frontmatter {
   const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
-  if (!match) return { summary: null, breaking: false };
+  if (!match) return { summary: null, breaking: false, security: false };
 
   const block = match[1] as string;
 
@@ -101,18 +104,21 @@ function parseFrontmatter(content: string, fileLabel: string): Frontmatter {
     );
   }
 
-  // breaking: must be literal true/false if present
-  let breaking = false;
-  const breakingMatch = block.match(/^breaking:\s*(\S+)\s*$/m);
-  if (breakingMatch) {
-    const val = breakingMatch[1];
+  const parseBool = (key: string): boolean => {
+    const m = block.match(new RegExp(`^${key}:\\s*(\\S+)\\s*$`, 'm'));
+    if (!m) return false;
+    const val = m[1];
     if (val !== 'true' && val !== 'false') {
-      throw new Error(`${fileLabel}: breaking must be 'true' or 'false', got '${val}'.`);
+      throw new Error(`${fileLabel}: ${key} must be 'true' or 'false', got '${val}'.`);
     }
-    breaking = val === 'true';
-  }
+    return val === 'true';
+  };
 
-  return { summary, breaking };
+  return {
+    summary,
+    breaking: parseBool('breaking'),
+    security: parseBool('security'),
+  };
 }
 
 /** Extract the release date from the H1 heading. */
@@ -128,8 +134,11 @@ function extractDate(body: string, fileLabel: string): string {
 
 function renderEntry(entry: VersionEntry, fm: Frontmatter, date: string): string {
   const link = `changelog/${entry.series}/${entry.version}.md`;
-  const breakingBadge = fm.breaking ? ' · ⚠️ Breaking' : '';
-  const header = `## [${entry.version}](${link}) — ${date}${breakingBadge}`;
+  const badges = [fm.breaking ? '⚠️ Breaking' : null, fm.security ? '🛡️ Security' : null].filter(
+    (b): b is string => b !== null,
+  );
+  const badgeSuffix = badges.length > 0 ? ` · ${badges.join(' · ')}` : '';
+  const header = `## [${entry.version}](${link}) — ${date}${badgeSuffix}`;
   if (fm.summary) {
     return `${header}\n\n${fm.summary}\n`;
   }

package/skills/api-auth/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Authentication, authorization, and multi-tenancy patterns for `@cyanheads/mcp-ts-core`. Use when implementing auth scopes on tools/resources, configuring auth modes (none/jwt/oauth), working with JWT/OAuth env vars, or understanding how tenantId flows through ctx.state.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: reference
 ---
@@ -94,10 +94,44 @@ Set via `MCP_AUTH_MODE` environment variable.
 | Claim | JWT Field | Purpose |
 |:------|:----------|:--------|
 | `clientId` | `cid` / `client_id` | Identifies the calling client |
-| `scopes` | `scp` / `scope` | Space-separated list of granted scopes |
+| `scopes` | union of `scp`, `scope`, `mcp_tool_scopes` | Granted scope list (see below) |
 | `sub` | `sub` | Subject (user or service identity) |
 | `tenantId` | `tid` | Tenant identifier — drives `ctx.state` scoping |
 
+`scopes` is the **union** of three claims, in this order:
+
+| Claim | Form | Source |
+|:------|:-----|:-------|
+| `scp` | array of strings | Okta-style |
+| `scope` | space-delimited string | OAuth 2.1 / OIDC standard |
+| `mcp_tool_scopes` | array of strings **or** space-delimited string | Custom claim for OIDC providers that cannot inject scopes into `scope` during the `authorization_code` flow (Authentik, Keycloak < 26.5, Zitadel) |
+
+Auth0/Okta-style providers that already populate `scp` or `scope` need no migration. Other deployments add a property mapping returning `{"mcp_tool_scopes": "tool:foo:read tool:bar:write"}` — the framework unions it into `ctx.auth.scopes` alongside the standard claims. Hardcoded claim name; deployments whose IdP cannot emit `mcp_tool_scopes` use the bypass flag below.
+
+### OIDC operator setup (Authentik / Keycloak / Zitadel)
+
+Standard OIDC providers compute the JWT `scope` claim from what the OAuth client requested at the authorization endpoint and ignore property mappings that try to override `scope` in the `authorization_code` flow. Property mappings that inject **other** claim names work fine. To grant per-tool scopes to a Claude.ai or ChatGPT custom connector that doesn't expose scope customization, configure your IdP to return the per-tool scopes under `mcp_tool_scopes` instead of overriding `scope`.
+
+| Provider | Where to configure |
+|:---------|:--------------------|
+| Authentik | Customization → Property Mappings → new "Scope Mapping" returning `{"mcp_tool_scopes": "tool:foo:read tool:bar:write"}`; bind to the OAuth2/OpenID provider |
+| Keycloak (< 26.5) | Client → Client Scopes → Mappers → new "Hardcoded claim" or "Script Mapper" emitting `mcp_tool_scopes` |
+| Zitadel | Project → Roles + Action returning `{"mcp_tool_scopes": "..."}` from a pre-token script |
+
+Keycloak ≥ 26.5 ships native MCP integration support; check its release notes before falling back to a custom claim.
+
+### Bypass flag
+
+For environments where no custom claim can be injected (managed services, restricted IdPs), set `MCP_AUTH_DISABLE_SCOPE_CHECKS=true` to bypass scope enforcement entirely.
+
+| Variable | Default | Effect |
+|:---------|:--------|:-------|
+| `MCP_AUTH_DISABLE_SCOPE_CHECKS` | `false` | When `true`, both `withRequiredScopes` (declared `auth: [...]`) and `checkScopes` (runtime-computed scopes inside handlers) early-return after the auth-context presence check. Token signature, audience, issuer, and expiry validation remain intact. |
+
+The flag bypasses **both** declared `auth: [...]` enforcement and runtime `checkScopes` calls — including tenant isolation patterns like `team:${input.teamId}:write`. Naming is deliberate: this disables all scope checks, not just per-tool ones. Applies to `MCP_AUTH_MODE=jwt` and `MCP_AUTH_MODE=oauth` (no effect under `none`).
+
+A `WARNING`-level log is emitted at startup whenever the flag is active so operators don't lose track of it. Combine with server-side ACLs (path filters, allowlists, tenant rules) — without an in-handler ACL, every authenticated user effectively has every scope.
+
 ---
 
 ## Endpoints
@@ -160,7 +194,7 @@ Available on `ctx.auth` inside handlers (when auth is enabled):
 ```ts
 interface AuthContext {
   clientId: string;        // Required — 'cid' or 'client_id' JWT claim
-  scopes: string[];        // Required — derived from 'scp' or 'scope' claim
+  scopes: string[];        // Required — union of 'scp', 'scope', and 'mcp_tool_scopes' claims
   sub: string;             // Required — 'sub' claim; falls back to clientId when absent
   token: string;           // Required — raw JWT or OAuth bearer token string
   tenantId?: string;       // Optional — 'tid' claim; present only for multi-tenant tokens

package/skills/api-config/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Reference for core and server configuration in `@cyanheads/mcp-ts-core`. Covers env var tables with defaults, priority order, server-specific Zod schema pattern, and Workers lazy-parsing requirement.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: reference
 ---
@@ -68,6 +68,7 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod from environment variable
 |:--------|:-----------------|:--------|:------|
 | `MCP_AUTH_MODE` | `mcpAuthMode` | `none` | `none` \| `jwt` \| `oauth` |
 | `MCP_AUTH_SECRET_KEY` | `mcpAuthSecretKey` | — | Required for `jwt` mode; min 32 chars |
+| `MCP_AUTH_DISABLE_SCOPE_CHECKS` | `mcpAuthDisableScopeChecks` | `false` | When `true`, bypasses both `withRequiredScopes` (declared `auth: [...]`) and `checkScopes` (runtime/tenant scopes). Token validation (sig/aud/iss/exp) intact. Logs a `WARNING` at startup. See `api-auth` skill. |
 | `OAUTH_ISSUER_URL` | `oauthIssuerUrl` | — | Required for `oauth` mode |
 | `OAUTH_AUDIENCE` | `oauthAudience` | — | Required for `oauth` mode |
 | `OAUTH_JWKS_URI` | `oauthJwksUri` | — | Override JWKS endpoint (otherwise derived from issuer) |

package/skills/api-telemetry/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: api-telemetry
+description: >
+  Catalog of OpenTelemetry instrumentation built into framework `@cyanheads/mcp-ts-core` — spans, metrics, completion logs, env config, runtime caveats, custom instrumentation patterns, and cardinality rules. Use when enabling OTel export, adding custom spans or metrics in services, debugging missing telemetry, looking up attribute names, or deciding what's safe to put on a metric attribute vs. a span.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+The framework auto-instruments every tool, resource, prompt, storage, LLM, speech, and graph call — each gets its own span and the standard counters/histograms. HTTP server requests pick up spans from `HttpInstrumentation` (or `@hono/otel` on the HTTP transport). Auth checks, session lifecycle, and task lifecycle are tracked as **metrics only** — auth decorates the active HTTP span with attributes, sessions and tasks emit counters.
+
+`requestId`, `traceId`, and `tenantId` correlate automatically across spans, metrics, and logs. Pino logs get `trace_id`/`span_id` injected when a span is active.
+
+For the helper API surface (`withSpan`, `createCounter`, `createHistogram`, `buildTraceparent`, etc.) — see the `api-utils` skill, `Telemetry` section. This skill is the catalog of **what** is emitted; that one is the reference for **how** to emit your own.
+
+---
+
+## Enabling export
+
+OTel is **off by default**. `OTEL_ENABLED=true` alone does nothing — you also need an OTLP endpoint. Without an endpoint the SDK is configured but nothing leaves the process.
+
+| Env var | Default | Purpose |
+|:--------|:--------|:--------|
+| `OTEL_ENABLED` | `false` | Master switch. Must be `true` to start the SDK. |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | — | OTLP/HTTP traces endpoint (e.g. `http://localhost:4318/v1/traces`). |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | — | OTLP/HTTP metrics endpoint (e.g. `http://localhost:4318/v1/metrics`). |
+| `OTEL_SERVICE_NAME` | `package.json` `name` | `service.name` resource attribute. |
+| `OTEL_SERVICE_VERSION` | `package.json` `version` | `service.version` resource attribute. |
+| `OTEL_TRACES_SAMPLER_ARG` | `1.0` | Trace sampling ratio (0–1) for `TraceIdRatioBasedSampler`. |
+| `OTEL_LOG_LEVEL` | `INFO` | OTel diagnostic logger level (`NONE`/`ERROR`/`WARN`/`INFO`/`DEBUG`/`VERBOSE`/`ALL`). |
+
+Metrics push via `PeriodicExportingMetricReader` every **15 seconds**. Traces use `BatchSpanProcessor`.
+
+---
+
+## Runtime support
+
+| Runtime | Behavior |
+|:--------|:---------|
+| **Node.js / Bun** | Full `NodeSDK`. Auto-instrumentations: HTTP server (Node http hooks; skips `/healthz`), Pino logs (`trace_id`/`span_id` injection). On the HTTP transport, when OTel is enabled and `@hono/otel` is installed, `httpInstrumentationMiddleware` is also wired onto the MCP endpoint — fills the gap on Bun, where the Node http auto-instrumentation silently no-ops. Manual spans, custom metrics, and OTLP export work on Bun regardless. |
+| **Cloudflare Workers / V8 isolates** | `NodeSDK` is unavailable. SDK init no-ops silently. `createCounter`/`createHistogram`/`withSpan` calls still work via the global OTel API but produce no output unless you wire a Worker-compatible exporter and `ctx.waitUntil()` for flush. |
+
+Cloud platform detection auto-populates resource attributes:
+
+| Detected | Attributes set |
+|:---------|:--------------|
+| Cloudflare Workers | `cloud.provider=cloudflare`, `cloud.platform=cloudflare_workers` |
+| AWS Lambda | `cloud.provider=aws`, `cloud.platform=aws_lambda`, `cloud.region` from `AWS_REGION` |
+| GCP Cloud Run / Functions | `cloud.provider=gcp`, `cloud.platform=gcp_cloud_run` (or `gcp_cloud_functions`), `cloud.region` from `GCP_REGION` |
+| All | `deployment.environment.name` from `config.environment` |
+
+---
+
+## Spans
+
+Every handler call gets a span. Nested operations (storage, graph, LLM) become child spans on the same trace. All spans carry `code.function.name` and `code.namespace` for code-attribution. Errors are recorded via `span.recordException()` and `SpanStatusCode.ERROR`; `McpError` codes surface as the `*.error_code` attribute.
+
+| Span name | Source | Key attributes |
+|:----------|:-------|:---------------|
+| `tool_execution:<tool>` | every tool call | `mcp.tool.input_bytes`, `mcp.tool.output_bytes`, `mcp.tool.duration_ms`, `mcp.tool.success`, `mcp.tool.error_code`, `mcp.tool.partial_success`, `mcp.tool.batch.{succeeded,failed}_count` |
+| `resource_read:<resource>` | every resource handler | `mcp.resource.uri`, `mcp.resource.mime_type`, `mcp.resource.size_bytes`, `mcp.resource.duration_ms`, `mcp.resource.success`, `mcp.resource.error_code` |
+| `prompt_generation:<prompt>` | every prompt handler | `mcp.prompt.input_bytes`, `mcp.prompt.output_bytes`, `mcp.prompt.message_count`, `mcp.prompt.duration_ms`, `mcp.prompt.success`, `mcp.prompt.error_code` |
+| `storage:<op>` | `StorageService` (every call) | `mcp.storage.operation`, `mcp.storage.duration_ms`, `mcp.storage.success`, `mcp.storage.key_count` (batch ops) |
+| `graph:<op>` | `GraphService` (every call) | `mcp.graph.operation`, `mcp.graph.duration_ms`, `mcp.graph.success` |
+| `gen_ai.chat_completion` | OpenRouter LLM provider | `gen_ai.system=openrouter`, `gen_ai.request.model`, `gen_ai.request.{max_tokens,temperature,top_p,streaming}`, `gen_ai.response.model`, `gen_ai.usage.{input,output,total}_tokens` |
+| `speech:tts` | ElevenLabs provider | `mcp.speech.provider`, `mcp.speech.operation`, `mcp.speech.input_bytes`, `mcp.speech.output_bytes`, `mcp.speech.duration_ms`, `mcp.speech.success` |
+| `speech:stt` | Whisper provider | same as `speech:tts` |
+
+Trace context propagates across boundaries via W3C `traceparent` headers. See `api-utils` → `telemetry/trace` for `withSpan`, `buildTraceparent`, `extractTraceparent`, `createContextWithParentTrace`, `injectCurrentContextInto`, `runInContext` signatures.
+
+---
+
+## Metrics
+
+All custom metrics are namespaced `mcp.*` (or `process.*` / `http.client.*` where standard semconv applies). Lazy-initialized on first emission; the universal ones are eagerly created at startup so series exist from the first export cycle.
+
+### Tools, resources, prompts
+
+| Metric | Type | Unit | Attributes |
+|:-------|:-----|:-----|:-----------|
+| `mcp.tool.calls` | counter | `{calls}` | `mcp.tool.name`, `mcp.tool.success` |
+| `mcp.tool.duration` | histogram | `ms` | `mcp.tool.name`, `mcp.tool.success` |
+| `mcp.tool.errors` | counter | `{errors}` | `mcp.tool.name`, `mcp.tool.error_category` (`upstream`/`server`/`client`) |
+| `mcp.tool.input_bytes` | histogram | `bytes` | `mcp.tool.name` |
+| `mcp.tool.output_bytes` | histogram | `bytes` | `mcp.tool.name` |
+| `mcp.tool.param.usage` | counter | `{uses}` | `mcp.tool.name`, `mcp.tool.param` (top-level keys supplied by caller) |
+| `mcp.resource.reads` | counter | `{reads}` | `mcp.resource.name`, `mcp.resource.success` |
+| `mcp.resource.duration` | histogram | `ms` | `mcp.resource.name`, `mcp.resource.success` |
+| `mcp.resource.errors` | counter | `{errors}` | `mcp.resource.name` |
+| `mcp.resource.output_bytes` | histogram | `bytes` | `mcp.resource.name` |
+| `mcp.prompt.generations` | counter | `{generations}` | `mcp.prompt.name`, `mcp.prompt.success` |
+| `mcp.prompt.duration` | histogram | `ms` | `mcp.prompt.name`, `mcp.prompt.success` |
+| `mcp.prompt.errors` | counter | `{errors}` | `mcp.prompt.name`, `mcp.prompt.error_category` |
+| `mcp.prompt.input_bytes` | histogram | `bytes` | `mcp.prompt.name` |
+| `mcp.prompt.output_bytes` | histogram | `bytes` | `mcp.prompt.name` |
+| `mcp.prompt.message_count` | histogram | `{messages}` | `mcp.prompt.name` |
+| `mcp.requests.active` | up/down counter | `{requests}` | — (in-flight handler executions, all three types) |
+
+### Storage, LLM, speech, graph
+
+| Metric | Type | Unit | Attributes |
+|:-------|:-----|:-----|:-----------|
+| `mcp.storage.operations` | counter | `{ops}` | `mcp.storage.operation`, `mcp.storage.success` |
+| `mcp.storage.duration` | histogram | `ms` | `mcp.storage.operation`, `mcp.storage.success` |
+| `mcp.storage.errors` | counter | `{errors}` | `mcp.storage.operation` |
+| `mcp.llm.requests` | counter | `{requests}` | `gen_ai.system`, `gen_ai.request.model` |
+| `mcp.llm.duration` | histogram | `ms` | `gen_ai.system`, `gen_ai.request.model` |
+| `mcp.llm.errors` | counter | `{errors}` | `gen_ai.system`, `gen_ai.request.model` |
+| `mcp.llm.tokens` | counter | `{tokens}` | `gen_ai.request.model`, `gen_ai.token.type` (`input`/`output`) |
+| `mcp.speech.operations` | counter | `{ops}` | `mcp.speech.operation` (`tts`/`stt`), `mcp.speech.provider`, `mcp.speech.success` |
+| `mcp.speech.duration` | histogram | `ms` | `mcp.speech.operation`, `mcp.speech.provider` |
+| `mcp.speech.errors` | counter | `{errors}` | `mcp.speech.operation`, `mcp.speech.provider` |
+| `mcp.graph.operations` | counter | `{ops}` | `mcp.graph.operation`, `mcp.graph.success` |
+| `mcp.graph.duration` | histogram | `ms` | `mcp.graph.operation`, `mcp.graph.success` |
+| `mcp.graph.errors` | counter | `{errors}` | `mcp.graph.operation` |
+
+### Transport, auth, sessions, tasks
+
+| Metric | Type | Unit | Attributes |
+|:-------|:-----|:-----|:-----------|
+| `mcp.auth.attempts` | counter | `{attempts}` | `mcp.auth.outcome` (`success`/`failure`/`missing`), `mcp.auth.failure_reason` |
+| `mcp.auth.duration` | histogram | `ms` | `mcp.auth.outcome`, `mcp.auth.failure_reason` |
+| `mcp.sessions.events` | counter | `{events}` | `mcp.session.event` (`created`/`terminated`/`rejected`/`stale_cleanup`) |
+| `mcp.session.duration` | histogram | `s` | — |
+| `mcp.sessions.active` | observable gauge | `{sessions}` | — |
+| `mcp.heartbeat.failures` | counter | `{failures}` | `mcp.connection.transport` (`stdio`/`http`) |
+| `mcp.http.close_failures` | counter | `{failures}` | `surface` (`transport`/`server`), `trigger` (`success`/`error`/`sse-abort`) — per-request close threw or timed out |
+| `mcp.http.per_request.created` | counter | `{instances}` | `kind` (`server`/`transport`) — per-request `McpServer` and `McpSessionTransport` instances created |
+| `mcp.http.per_request.finalized` | counter | `{instances}` | `kind` (`server`/`transport`) — per-request instances reclaimed by GC; persistent gap vs `created` indicates a leak |
+| `mcp.tasks.created` | counter | `{tasks}` | `mcp.task.store_type` (`in-memory`/`storage`) |
+| `mcp.tasks.status_changes` | counter | `{transitions}` | `mcp.task.status`, `mcp.task.store_type` |
+| `mcp.tasks.active` | observable gauge | `{tasks}` | — (in-memory store only) |
+
+### Errors, rate limits, HTTP client
+
+| Metric | Type | Unit | Attributes |
+|:-------|:-----|:-----|:-----------|
+| `mcp.errors.classified` | counter | `{errors}` | `mcp.error.classified_code` (JSON-RPC code), `operation` |
+| `mcp.ratelimit.rejections` | counter | `{rejections}` | `mcp.rate_limit.key` |
+| `http.client.request.duration` | histogram | `s` | `http.request.method`, `server.address`, `http.response.status_code` (when > 0; absent on network errors before a response is received) |
+
+### Process
+
+Auto-registered when `process.memoryUsage` / `process.uptime` / `perf_hooks` are available (Node/Bun, not Workers). The three memory gauges share a single `process.memoryUsage()` snapshot per collection cycle, refreshed at most every 100 ms.
+
+| Metric | Type | Unit | Notes |
+|:-------|:-----|:-----|:------|
+| `process.memory.rss` | observable gauge | `bytes` | Resident set size |
+| `process.memory.heap_used` | observable gauge | `bytes` | V8 heap used |
+| `process.memory.heap_total` | observable gauge | `bytes` | V8 total heap |
+| `process.uptime` | observable gauge | `s` | Process uptime |
+| `process.event_loop.delay` | observable gauge | `ms` | p99 delay (`monitorEventLoopDelay` resolution=20) |
+| `process.event_loop.utilization` | observable gauge | `1` | 0 = idle, 1 = saturated |
+
+---
+
+## Logs
+
+Pino logs are auto-instrumented by `@opentelemetry/instrumentation-pino`. When a span is active, `trace_id` and `span_id` are injected into the record. Combined with the framework logger's automatic `requestId`/`tenantId` correlation, every log line is searchable by trace.
+
+For domain logging inside handlers, use `ctx.log` (`debug`/`info`/`notice`/`warning`/`error`) — auto-includes `requestId`, `traceId`, `tenantId`, `spanId`. The completion log emitted at the end of every handler carries a `metrics` payload, with fields tuned to each surface:
+
+| Handler | Log message | `metrics` fields |
+|:--------|:------------|:-----------------|
+| Tool | `Tool execution finished.` | `durationMs`, `isSuccess`, `errorCode`, `inputBytes`, `outputBytes`, plus `partialSuccess` / `batchSucceeded` / `batchFailed` when the result is a partial-success batch |
+| Resource | `Resource read finished.` | `durationMs`, `isSuccess`, `errorCode`, `outputBytes`, `uri`, `mimeType` |
+| Prompt | `Prompt generation finished.` (or `failed.`) | `durationMs`, `isSuccess`, `errorCode`, `inputBytes`, `outputBytes`, `messageCount` |
+
+---
+
+## Custom instrumentation
+
+Need a span or metric for your own service? Use the helpers from `@cyanheads/mcp-ts-core/utils` (full signatures in `api-utils` → `Telemetry`):
+
+```ts
+import { withSpan, createCounter, createHistogram } from '@cyanheads/mcp-ts-core/utils';
+
+const myOps = createCounter('myservice.operations', 'My service ops', '{ops}');
+const myDuration = createHistogram('myservice.duration', 'My service duration', 'ms');
+
+export async function doWork() {
+  return withSpan('myservice.do_work', async (span) => {
+    const t0 = performance.now();
+    try {
+      const result = await reallyDoWork();
+      span.setAttribute('myservice.items', result.length);
+      return result;
+    } finally {
+      myDuration.record(performance.now() - t0);
+      myOps.add(1);
+    }
+  }, { 'myservice.region': 'us-west' });
+}
+```
+
+Span context propagates automatically — `withSpan` calls inside a `tool_execution:*` span appear as children. `runInContext(ctx, fn)` carries the active OTel context across async boundaries (`setTimeout`, `queueMicrotask`).
+
+For attribute keys, prefer the `ATTR_*` constants exported from `@cyanheads/mcp-ts-core/utils` (telemetry/attributes) over hand-typed strings — keeps you in step with framework conventions and avoids typos. Standard OTel semantic conventions (HTTP, cloud, service, network, etc.) are NOT re-exported — import those directly from `@opentelemetry/semantic-conventions`.
+
+---
+
+## Visualization
+
+An example Grafana dashboard JSON and vendor-agnostic query recipes (Prometheus, Datadog, New Relic, Honeycomb) live at [`docs/telemetry/`](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) in the framework source — not bundled in the npm package, so consult the GitHub repo.
+
+---
+
+## Cardinality discipline
+
+Series are cheap to emit but expensive to store and query. The framework deliberately keeps high-cardinality identifiers off metric attributes and on spans only. Follow the same rule when adding your own metrics.
+
+| On metrics | On spans / logs only |
+|:-----------|:---------------------|
+| `mcp.resource.name` (URI template) | `mcp.resource.uri` (full URI with IDs) |
+| `gen_ai.request.model` (bounded enum) | `mcp.tenant.id`, `mcp.client.id`, `mcp.auth.subject` |
+| Bounded enum / template strings | Per-request unique IDs, free-form user input, opaque tokens |
+
+When in doubt: if the attribute can take more than ~100 distinct values across a fleet's runtime, it belongs on the span, not the metric.

package/skills/api-utils/SKILL.md

@@ -4,7 +4,7 @@ description: >
   API reference for all utilities exported from `@cyanheads/mcp-ts-core/utils`. Use when looking up utility method signatures, options, peer dependencies, or usage patterns.
 metadata:
   author: cyanheads
-  version: "2.1"
+  version: "2.2"
   audience: external
   type: reference
 ---
@@ -136,6 +136,8 @@ Both functions throw `McpError(InternalError)` only on unexpected heuristic fail
 
 ## `@cyanheads/mcp-ts-core/utils` — Telemetry
 
+Helper API only. For the catalog of what the framework auto-emits (span names, metric names, attributes, completion log fields, env config, runtime support, cardinality rules), see the `api-telemetry` skill.
+
 ### `telemetry/instrumentation`
 
 | Export | Signature | Notes |

package/skills/maintenance/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Investigate, adopt, and verify dependency updates — with special handling for `@cyanheads/mcp-ts-core`. Captures what changed, understands why, cross-references against the codebase, adopts framework improvements, syncs project skills, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
 metadata:
   author: cyanheads
-  version: "2.0"
+  version: "2.1"
   audience: external
   type: workflow
 ---
@@ -120,9 +120,11 @@ For each agent directory that exists:
 
 If no agent directory exists, skip Phase B — the project hasn't opted in to per-agent skill copies.
 
-**Phase C — Package scripts → Project `scripts/`**
+**Phase C — Package framework files → Project**
 
-The `init` CLI scaffolds a fixed set of framework scripts into consumer projects — these underpin `bun run build`, `bun run devcheck`, `bun run lint:mcp`, `bun run tree`, and the changelog build. They drift silently when the framework updates them. Compare by content hash and overwrite on mismatch:
+Two categories of framework-authored files ship into consumer projects and drift silently as the framework updates them. Both follow the same hash-compare-and-overwrite mechanic.
+
+**Scripts** — `init` scaffolds a fixed set that underpin `bun run build`, `bun run devcheck`, `bun run lint:mcp`, `bun run tree`, and the changelog build. Iterate the package's shipped scripts directory:
 
 ```bash
 for src in node_modules/@cyanheads/mcp-ts-core/scripts/*.ts; do
@@ -140,9 +142,17 @@ done
 
 Scripts in `scripts/` that aren't present in the package directory are project-specific (custom deploy, codegen, etc.) — leave them alone. The package's `files:` field gates what ships into `node_modules/.../scripts/`, so enumerating that directory is the canonical "shipped scripts" set.
 
-If the consumer customized a framework script, the overwrite discards those changes. After the sync runs, diff `scripts/` to surface replacements — review before committing. If a specific local customization needs to be preserved, revert that file using your git tools.
+**Pristine reference files** — files explicitly documented as "never edit, rename, or move." The framework keeps the authoritative copy under `templates/`; the consumer's copy must track upstream as the format evolves (new frontmatter fields, section reorderings, etc.). Fixed src→dst mapping:
+
+| Source (in package) | Destination (in project) |
+|:--|:--|
+| `templates/changelog/template.md` | `changelog/template.md` |
+
+Apply the same compare-and-overwrite logic. Add new entries here only when a template is explicitly documented as pristine in the framework's CLAUDE.md or its own header.
+
+If the consumer customized a framework script or pristine reference (against guidance), the overwrite discards those changes. After the sync runs, diff `scripts/` and the affected template paths to surface replacements — review before committing. If a specific local customization needs to be preserved, revert that file using your git tools.
 
-**Report** which skills were added/updated in Phase A (with version deltas), which agent directories were refreshed in Phase B, and which scripts were resynced in Phase C. The user needs to know what new guidance and tooling is now in play.
+**Report** which skills were added/updated in Phase A (with version deltas), which agent directories were refreshed in Phase B, and which scripts and pristine reference files were resynced in Phase C. The user needs to know what new guidance and tooling is now in play.
 
 ### 6. Adopt changes in the codebase
 
@@ -212,7 +222,7 @@ Present a concise numbered summary to the user:
 - [ ] Every applicable framework adoption opportunity applied in this pass — no scope/effort/marginal-benefit deferrals; third-party adoptions evaluated on cost/benefit
 - [ ] Project `skills/` synced from package (Phase A), with a change report
 - [ ] Agent skill directories (`.claude/skills/`, `.agents/skills/`, etc.) refreshed from project `skills/` (Phase B)
-- [ ] Framework `scripts/` resynced from package via content-hash compare (Phase C), with a change report; `scripts/` diff reviewed before committing
+- [ ] Framework `scripts/` and pristine reference files resynced from package via content-hash compare (Phase C), with a change report; diffs reviewed before committing
 - [ ] `bun run rebuild` succeeds
 - [ ] `bun run devcheck` passes (includes audit + outdated)
 - [ ] `bun run test` passes