@cyanheads/mcp-ts-core 0.13.6 → 0.13.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.13.6",
+  "version": "0.13.7",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for MCP servers. Includes runtime infrastructure and agent skills for building, testing, and shipping servers.",
   "files": [
@@ -156,7 +156,6 @@
     "devcheck": "bun run scripts/devcheck.ts",
     "rebuild": "bun run scripts/clean.ts && bun run build",
     "docs:generate": "bunx typedoc",
-    "depcheck": "bunx depcheck",
     "lint": "biome check",
     "lint:mcp": "bun run scripts/lint-mcp.ts",
     "lint:packaging": "bun run scripts/lint-packaging.ts",
@@ -199,9 +198,10 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
     "@cloudflare/vitest-pool-workers": "^0.22.0",
-    "@cloudflare/workers-types": "5.20260910.1",
+    "@cloudflare/workers-types": "5.20260922.1",
     "@duckdb/node-api": "^1.5.5-r.5",
     "@hono/otel": "^1.1.2",
+    "@modelcontextprotocol/client": "^2.0.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
     "@opentelemetry/instrumentation-http": "^0.222.0",
@@ -211,42 +211,39 @@
     "@opentelemetry/sdk-node": "^0.222.0",
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
-    "@socketsecurity/bun-security-scanner": "^1.1.2",
-    "@supabase/supabase-js": "^2.116.0",
+    "@socketsecurity/bun-security-scanner": "^1.1.3",
+    "@supabase/supabase-js": "^2.117.0",
     "@types/bun": "^1.4.2",
-    "@types/node": "26.5.1",
+    "@types/node": "26.6.2",
     "@types/papaparse": "^5.5.2",
     "@types/sanitize-html": "^2.16.1",
-    "@types/validator": "^13.15.10",
     "@vitest/coverage-istanbul": "4.1.11",
     "@vitest/ui": "4.1.11",
     "better-sqlite3": "^13.0.3",
-    "bun-types": "^1.4.2",
     "chrono-node": "^2.10.1",
     "clipboardy": "^5.3.2",
-    "defuddle": "^0.19.3",
+    "defuddle": "^0.19.4",
     "depcheck": "^1.4.7",
     "diff": "^9.0.0",
     "execa": "^10.0.1",
-    "fast-check": "^4.10.1",
+    "fast-check": "^4.10.2",
     "fast-xml-parser": "^5.11.1",
-    "ignore": "^7.0.9",
+    "ignore": "^7.0.10",
     "js-yaml": "^5.4.2",
     "linkedom": "^0.18.13",
     "node-cron": "^4.6.0",
-    "openai": "^7.15.0",
+    "openai": "^7.21.0",
     "papaparse": "^5.7.0",
     "partial-json": "^0.1.7",
     "pdf-lib": "^1.17.1",
     "pino-pretty": "^13.1.3",
-    "repomix": "^1.18.0",
+    "repomix": "^1.18.1",
     "sanitize-html": "^2.17.7",
     "tsc-alias": "^1.9.5",
     "typedoc": "^0.28.20",
     "typescript": "^7.0.2",
     "typescript-v6": "npm:typescript@^6.0.3",
     "unpdf": "^1.8.1",
-    "validator": "^13.15.35",
     "vite": "8.3.0",
     "vitest": "^4.1.11"
   },
@@ -280,32 +277,18 @@
       "url": "https://www.buymeacoffee.com/cyanheads"
     }
   ],
-  "packageManager": "bun@1.4.0",
+  "packageManager": "bun@1.4.2",
   "engines": {
     "bun": ">=1.4.0",
     "node": ">=24.0.0"
   },
-  "depcheck": {
-    "ignores": [
-      "bun",
-      "repomix",
-      "tsc-alias",
-      "@cyanheads/mcp-ts-core",
-      "@modelcontextprotocol/ext-apps",
-      "@socketsecurity/bun-security-scanner"
-    ],
-    "ignorePatterns": ["examples"]
-  },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@hono/node-server": "^2.1.1",
-    "@modelcontextprotocol/client": "^2.0.0",
-    "@modelcontextprotocol/ext-apps": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@opentelemetry/api": "^1.9.1",
-    "dotenv": "^17.4.2",
     "hono": "^4.13.8",
     "jose": "^6.2.12",
     "pino": "^10.3.1",
@@ -314,9 +297,9 @@
   "peerDependencies": {
     "@duckdb/node-api": "^1.5.5-r.1",
     "@hono/otel": "^1.1.2",
-    "@opentelemetry/instrumentation-http": "^0.222.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
+    "@opentelemetry/instrumentation-http": "^0.222.0",
     "@opentelemetry/instrumentation-pino": "^0.68.0",
     "@opentelemetry/resources": "^2.10.0",
     "@opentelemetry/sdk-metrics": "^2.10.0",
@@ -329,7 +312,6 @@
     "defuddle": "^0.19.2",
     "diff": "^9.0.0",
     "fast-check": "^4.9.0",
-    "vitest": ">=4.0.0",
     "fast-xml-parser": "^5.10.1",
     "js-yaml": "^5.2.2",
     "linkedom": "^0.18.13",
@@ -340,8 +322,8 @@
     "pdf-lib": "^1.17.1",
     "sanitize-html": "^2.17.6",
     "unpdf": "^1.6.2",
-    "validator": "^13.15.35",
-    "zod": "^4.4.3"
+    "vitest": ">=4.0.0",
+    "zod": "^4.6.5"
   },
   "peerDependenciesMeta": {
     "@duckdb/node-api": {
@@ -425,9 +407,6 @@
     "unpdf": {
       "optional": true
     },
-    "validator": {
-      "optional": true
-    },
     "vitest": {
       "optional": true
     }

package/templates/.env.example

@@ -34,7 +34,9 @@ MCP_SESSION_MODE=stateless          # stateful | stateless | auto. Set here, not
 
 # ── Telemetry ─────────────────────────────────────────────────────────
 # OTEL_ENABLED=false                          # Enable OpenTelemetry (default: false)
-# OTEL_EXPORTER_OTLP_ENDPOINT=               # OTLP endpoint URL (e.g., http://localhost:4318)
+# OTEL_EXPORTER_OTLP_ENDPOINT=               # OTLP base URL (e.g., http://localhost:4318); traces → /v1/traces, metrics → /v1/metrics
+# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=        # Overrides the base for traces; used as-is
+# OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=       # Overrides the base for metrics; used as-is
 
 # ── Server-specific ──────────────────────────────────────────────────
 # Add your server's environment variables below

package/templates/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -10,7 +10,7 @@ body:
         **Secondary labels.** `enhancement` is applied automatically — also add one or more of the following in the sidebar if they apply:
         - `performance` — improves memory, CPU, latency, or resource usage
         - `security` — hardens the security posture
-        - `breaking-change` — will break public API; requires a major bump
+        - `breaking-change` — will break public API or an existing tool contract
         - `surplus-token-idea` — worth exploring when token budget allows
 
   - type: textarea

package/templates/AGENTS.md

@@ -67,7 +67,7 @@ export const searchItems = tool('search_items', {
   annotations: { readOnlyHint: true },
   input: z.object({
     query: z.string().describe('Search terms'),
-    limit: z.number().default(10).describe('Max results'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
   }),
   output: z.object({
     items: z.array(z.object({
@@ -199,7 +199,7 @@ Handlers receive a unified `ctx` object. Key properties:
 | Property | Description |
 |:---------|:------------|
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
-| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
 | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
 | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
 | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |

package/templates/CLAUDE.md

@@ -67,7 +67,7 @@ export const searchItems = tool('search_items', {
   annotations: { readOnlyHint: true },
   input: z.object({
     query: z.string().describe('Search terms'),
-    limit: z.number().default(10).describe('Max results'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Max results (1–100)'),
   }),
   output: z.object({
     items: z.array(z.object({
@@ -199,7 +199,7 @@ Handlers receive a unified `ctx` object. Key properties:
 | Property | Description |
 |:---------|:------------|
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
-| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |
 | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
 | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |
 | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |

package/templates/Dockerfile

@@ -14,7 +14,7 @@
 # output. A stage that compiles a native addon needs the target-arch toolchain
 # and cannot cross-compile this way — drop the flag there.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
 
 WORKDIR /usr/src/app
 
@@ -40,7 +40,7 @@ RUN bun run build
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1.4.0-slim AS production
+FROM oven/bun:1.4.2-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -70,8 +70,8 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
     bun install --production --omit=peer --frozen-lockfile --ignore-scripts
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
-# These are not bundled by default to keep the base image lean. Enable at build time
-# with: docker build --build-arg OTEL_ENABLED=true
+# Installed by default. Omit them for a leaner image at build time
+# with: docker build --build-arg OTEL_ENABLED=false
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \

package/templates/package.json

@@ -52,7 +52,7 @@
     "url": ""
   },
   "license": "Apache-2.0",
-  "packageManager": "bun@1.4.0",
+  "packageManager": "bun@1.4.2",
   "engines": {
     "bun": ">=1.4.0",
     "node": ">=24.0.0"
@@ -67,8 +67,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
-    "@socketsecurity/bun-security-scanner": "^1.1.2",
-    "@types/node": "26.5.1",
+    "@socketsecurity/bun-security-scanner": "^1.1.3",
+    "@types/node": "26.6.2",
     "@vitest/coverage-istanbul": "4.1.11",
     "depcheck": "^1.4.7",
     "fast-check": "^4.9.0",

package/templates/src/mcp-server/prompts/definitions/echo.prompt.ts

@@ -8,11 +8,9 @@ import { prompt, z } from '@cyanheads/mcp-ts-core';
 // Prompts are pure message templates — no Context, no auth, no side effects.
 // They generate conversation messages that clients can use to start interactions.
 export const echoPrompt = prompt('template_echo_message', {
-  description: 'Generates a simple echo message. Replace this with your first real prompt.',
+  description: 'Generate a simple echo message. Replace this with your first real prompt.',
   args: z.object({
     message: z.string().describe('The message to echo.'),
   }),
-  generate: (args) => [
-    { role: 'user', content: { type: 'text', text: `Echo: ${args.message}` } },
-  ],
+  generate: (args) => [{ role: 'user', content: { type: 'text', text: `Echo: ${args.message}` } }],
 });

package/templates/src/mcp-server/resources/definitions/echo-app-ui.app-resource.ts

@@ -18,31 +18,69 @@ const APP_HTML = `<!DOCTYPE html>
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>Echo App</title>
   <style>
+    /*
+     * Local tokens are the pre-connect baseline: light by default, dark when the
+     * OS prefers it, and pinned by the data-theme attribute applyDocumentTheme sets.
+     * Every rule reads the host's variable first (installed by applyHostStyleVariables)
+     * and falls back to the local token until host context arrives.
+     */
+    :root {
+      color-scheme: light dark;
+      --bg: #ffffff; --surface: #f8fafc; --fg: #0f172a; --muted: #64748b;
+      --border: #e2e8f0; --accent: #2563eb; --accent-fg: #ffffff;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root:not([data-theme="light"]) {
+        --bg: #0f172a; --surface: #1e293b; --fg: #e2e8f0; --muted: #94a3b8;
+        --border: #334155; --accent: #3b82f6; --accent-fg: #ffffff;
+      }
+    }
+    :root[data-theme="dark"] {
+      --bg: #0f172a; --surface: #1e293b; --fg: #e2e8f0; --muted: #94a3b8;
+      --border: #334155; --accent: #3b82f6; --accent-fg: #ffffff;
+    }
     * { margin: 0; padding: 0; box-sizing: border-box; }
     body {
-      font-family: system-ui, -apple-system, sans-serif;
-      background: #0f172a; color: #e2e8f0;
+      font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
+      background: var(--color-background-primary, var(--bg));
+      color: var(--color-text-primary, var(--fg));
       padding: 1.5rem; min-height: 100vh;
       display: flex; flex-direction: column; align-items: center; gap: 1rem;
     }
-    h1 { font-size: 1.25rem; font-weight: 600; }
+    h1 {
+      font-size: var(--font-heading-sm-size, 1.25rem);
+      font-weight: var(--font-weight-semibold, 600);
+    }
     .card {
-      background: #1e293b; border: 1px solid #334155; border-radius: 0.5rem;
+      background: var(--color-background-secondary, var(--surface));
+      border: 1px solid var(--color-border-primary, var(--border));
+      border-radius: var(--border-radius-lg, 0.5rem);
       padding: 1rem 1.25rem; width: 100%; max-width: 480px;
     }
-    .label { font-size: 0.75rem; color: #94a3b8; text-transform: uppercase; letter-spacing: 0.05em; }
-    .value { font-size: 1rem; margin-top: 0.25rem; word-break: break-word; }
+    .label {
+      font-size: var(--font-text-xs-size, 0.75rem);
+      color: var(--color-text-secondary, var(--muted));
+      text-transform: uppercase; letter-spacing: 0.05em;
+    }
+    .value { font-size: var(--font-text-md-size, 1rem); margin-top: 0.25rem; word-break: break-word; }
     .controls { display: flex; gap: 0.5rem; width: 100%; max-width: 480px; }
     input[type="text"] {
-      flex: 1; padding: 0.5rem 0.75rem; background: #1e293b; border: 1px solid #334155;
-      border-radius: 0.375rem; color: #e2e8f0; font-size: 0.875rem; outline: none;
+      flex: 1; padding: 0.5rem 0.75rem;
+      background: var(--color-background-secondary, var(--surface));
+      border: 1px solid var(--color-border-primary, var(--border));
+      border-radius: var(--border-radius-md, 0.375rem);
+      color: var(--color-text-primary, var(--fg));
+      font: inherit; font-size: var(--font-text-sm-size, 0.875rem); outline: none;
     }
-    input[type="text"]:focus { border-color: #3b82f6; }
+    input[type="text"]:focus { border-color: var(--color-ring-primary, var(--accent)); }
     button {
-      padding: 0.5rem 1rem; background: #3b82f6; color: #fff; border: none;
-      border-radius: 0.375rem; font-size: 0.875rem; cursor: pointer;
+      padding: 0.5rem 1rem; border: none;
+      background: var(--color-background-inverse, var(--accent));
+      color: var(--color-text-inverse, var(--accent-fg));
+      border-radius: var(--border-radius-md, 0.375rem);
+      font: inherit; font-size: var(--font-text-sm-size, 0.875rem); cursor: pointer;
     }
-    button:hover { background: #2563eb; }
+    button:hover { opacity: 0.9; }
     button:disabled { opacity: 0.5; cursor: not-allowed; }
   </style>
 </head>
@@ -138,8 +176,7 @@ export const echoAppUiResource = appResource('ui://template-echo-app/app.html',
   name: 'echo-app-ui',
   title: 'Echo App UI',
   description:
-    'Interactive HTML app for the echo app tool. Displayed as a sandboxed iframe ' +
-    'by MCP Apps-capable hosts.',
+    'Interactive HTML app for the echo app tool. Displayed as a sandboxed iframe by MCP Apps-capable hosts.',
   params: ParamsSchema,
   auth: ['resource:echo-app-ui:read'],
   _meta: {

package/templates/src/mcp-server/resources/definitions/echo.resource.ts

@@ -9,7 +9,7 @@ import { resource, z } from '@cyanheads/mcp-ts-core';
 // Like tools, prefix names with your server name: template-echo, tasks-status, etc.
 export const echoResource = resource('echo://{message}', {
   name: 'template-echo-resource',
-  description: 'Echoes a message from the URI. Replace this with your first real resource.',
+  description: 'Echo a message from the URI. Replace this with your first real resource.',
   mimeType: 'application/json',
   params: z.object({
     message: z.string().describe('The message to echo back.'),

package/templates/src/mcp-server/tools/definitions/echo-app.app-tool.ts

@@ -15,15 +15,14 @@ export const echoAppTool = appTool('template_echo_app', {
   resourceUri: UI_RESOURCE_URI,
   title: 'Echo App',
   description:
-    'Echoes a message with an interactive UI. Demonstrates MCP Apps — hosts that support ' +
-    'the extension render an HTML interface; others receive a text fallback.',
+    'Echo a message back with an interactive UI. Hosts that support MCP Apps render an HTML interface; other hosts receive a text fallback.',
   annotations: { readOnlyHint: true },
   input: z.object({
     message: z.string().describe('The message to echo.'),
   }),
   output: z.object({
     message: z.string().describe('The echoed message.'),
-    timestamp: z.string().describe('ISO 8601 timestamp of the echo.'),
+    timestamp: z.iso.datetime().describe('ISO 8601 timestamp of the echo.'),
   }),
 
   handler(input, ctx) {

package/templates/src/mcp-server/tools/definitions/echo.tool.ts

@@ -9,7 +9,7 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 // Tool names are snake_case, prefixed with your server name to avoid collisions across servers.
 // e.g. for a "tasks" server: tasks_fetch_list, tasks_create_item.
 export const echoTool = tool('template_echo_message', {
-  description: 'Echoes a message back. Replace this with your first real tool.',
+  description: 'Echo a message back. Replace this with your first real tool.',
   annotations: { readOnlyHint: true },
   input: z.object({
     message: z.string().describe('The message to echo back.'),

package/dist/utils/telemetry/index.d.ts

@@ -1,12 +0,0 @@
-/**
- * @fileoverview Barrel for telemetry utilities.
- * Provides OpenTelemetry instrumentation, MCP attribute keys, trace helpers,
- * and metrics creation utilities for observability.
- *
- * @module src/utils/telemetry
- */
-export * from './attributes.js';
-export * from './instrumentation.js';
-export * from './metrics.js';
-export * from './trace.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/utils/telemetry/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/utils/telemetry/index.js

@@ -1,12 +0,0 @@
-/**
- * @fileoverview Barrel for telemetry utilities.
- * Provides OpenTelemetry instrumentation, MCP attribute keys, trace helpers,
- * and metrics creation utilities for observability.
- *
- * @module src/utils/telemetry
- */
-export * from './attributes.js';
-export * from './instrumentation.js';
-export * from './metrics.js';
-export * from './trace.js';
-//# sourceMappingURL=index.js.map

package/dist/utils/telemetry/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}