@cyanheads/mcp-ts-core 0.10.3 → 0.10.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "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",
@@ -35,75 +35,98 @@
   "exports": {
     ".": {
       "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js"
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.js"
     },
     "./worker": {
       "types": "./dist/core/worker.d.ts",
-      "import": "./dist/core/worker.js"
+      "import": "./dist/core/worker.js",
+      "default": "./dist/core/worker.js"
     },
     "./tools": {
       "types": "./dist/mcp-server/tools/utils/toolDefinition.d.ts",
-      "import": "./dist/mcp-server/tools/utils/toolDefinition.js"
+      "import": "./dist/mcp-server/tools/utils/toolDefinition.js",
+      "default": "./dist/mcp-server/tools/utils/toolDefinition.js"
     },
     "./resources": {
       "types": "./dist/mcp-server/resources/utils/resourceDefinition.d.ts",
-      "import": "./dist/mcp-server/resources/utils/resourceDefinition.js"
+      "import": "./dist/mcp-server/resources/utils/resourceDefinition.js",
+      "default": "./dist/mcp-server/resources/utils/resourceDefinition.js"
     },
     "./prompts": {
       "types": "./dist/mcp-server/prompts/utils/promptDefinition.d.ts",
-      "import": "./dist/mcp-server/prompts/utils/promptDefinition.js"
+      "import": "./dist/mcp-server/prompts/utils/promptDefinition.js",
+      "default": "./dist/mcp-server/prompts/utils/promptDefinition.js"
     },
     "./tasks": {
       "types": "./dist/mcp-server/tasks/utils/taskToolDefinition.d.ts",
-      "import": "./dist/mcp-server/tasks/utils/taskToolDefinition.js"
+      "import": "./dist/mcp-server/tasks/utils/taskToolDefinition.js",
+      "default": "./dist/mcp-server/tasks/utils/taskToolDefinition.js"
     },
     "./errors": {
       "types": "./dist/types-global/errors.d.ts",
-      "import": "./dist/types-global/errors.js"
+      "import": "./dist/types-global/errors.js",
+      "default": "./dist/types-global/errors.js"
     },
     "./config": {
       "types": "./dist/config/index.d.ts",
-      "import": "./dist/config/index.js"
+      "import": "./dist/config/index.js",
+      "default": "./dist/config/index.js"
     },
     "./auth": {
       "types": "./dist/mcp-server/transports/auth/lib/checkScopes.d.ts",
-      "import": "./dist/mcp-server/transports/auth/lib/checkScopes.js"
+      "import": "./dist/mcp-server/transports/auth/lib/checkScopes.js",
+      "default": "./dist/mcp-server/transports/auth/lib/checkScopes.js"
     },
     "./storage": {
       "types": "./dist/storage/core/StorageService.d.ts",
-      "import": "./dist/storage/core/StorageService.js"
+      "import": "./dist/storage/core/StorageService.js",
+      "default": "./dist/storage/core/StorageService.js"
     },
     "./storage/types": {
       "types": "./dist/storage/core/IStorageProvider.d.ts",
-      "import": "./dist/storage/core/IStorageProvider.js"
+      "import": "./dist/storage/core/IStorageProvider.js",
+      "default": "./dist/storage/core/IStorageProvider.js"
     },
     "./canvas": {
       "types": "./dist/services/canvas/index.d.ts",
-      "import": "./dist/services/canvas/index.js"
+      "import": "./dist/services/canvas/index.js",
+      "default": "./dist/services/canvas/index.js"
     },
     "./mirror": {
       "types": "./dist/services/mirror/index.d.ts",
-      "import": "./dist/services/mirror/index.js"
+      "import": "./dist/services/mirror/index.js",
+      "default": "./dist/services/mirror/index.js"
     },
     "./utils": {
       "types": "./dist/utils/index.d.ts",
-      "import": "./dist/utils/index.js"
+      "import": "./dist/utils/index.js",
+      "default": "./dist/utils/index.js"
     },
     "./services": {
       "types": "./dist/services/index.d.ts",
-      "import": "./dist/services/index.js"
+      "import": "./dist/services/index.js",
+      "default": "./dist/services/index.js"
     },
     "./linter": {
       "types": "./dist/linter/index.d.ts",
-      "import": "./dist/linter/index.js"
+      "import": "./dist/linter/index.js",
+      "default": "./dist/linter/index.js"
     },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
-      "import": "./dist/testing/index.js"
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
     },
     "./testing/fuzz": {
       "types": "./dist/testing/fuzz.d.ts",
-      "import": "./dist/testing/fuzz.js"
+      "import": "./dist/testing/fuzz.js",
+      "default": "./dist/testing/fuzz.js"
+    },
+    "./testing/vitest": {
+      "types": "./dist/testing/vitest.d.ts",
+      "import": "./dist/testing/vitest.js",
+      "default": "./dist/testing/vitest.js"
     },
     "./tsconfig.base.json": "./tsconfig.base.json",
     "./vitest.config": "./vitest.config.base.mjs",
@@ -148,11 +171,14 @@
     "tree": "bun run scripts/tree.ts",
     "fetch-spec": "bun run scripts/fetch-openapi-spec.ts",
     "test": "bunx vitest run",
-    "test:all": "bun run test && bun run test:worker && bun run test:integration",
+    "test:all": "bun run test:coverage && bun run test:node && bun run test:worker && bun run test:integration",
     "test:integration": "bunx vitest run --config vitest.integration.ts",
+    "test:leaks": "bunx vitest run --detect-async-leaks",
+    "test:node": "sh -c 'NODE_BIN=$(which -a node | grep -v /bun-node- | head -n 1); \"$NODE_BIN\" ./node_modules/vitest/vitest.mjs run && \"$NODE_BIN\" ./node_modules/vitest/vitest.mjs run --config vitest.integration.ts'",
     "test:unit": "bunx vitest run --project unit",
     "test:smoke": "bunx vitest run --project smoke",
     "test:fuzz": "bunx vitest run --project fuzz",
+    "test:typecheck": "bunx vitest run --project typecheck",
     "test:compliance": "bunx vitest run --project compliance",
     "test:worker": "sh -c 'NODE_BIN=$(which -a node | grep -v /bun-node- | head -n 1); \"$NODE_BIN\" ./node_modules/vitest/vitest.mjs run --config vitest.worker.ts'",
     "test:ui": "bunx vitest --ui",
@@ -177,18 +203,18 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
-    "@cloudflare/vitest-pool-workers": "^0.16.14",
-    "@cloudflare/workers-types": "4.20260610.1",
+    "@cloudflare/vitest-pool-workers": "^0.16.15",
+    "@cloudflare/workers-types": "4.20260611.1",
     "@duckdb/node-api": "^1.5.3-r.3",
     "@hono/otel": "^1.1.2",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
-    "@opentelemetry/instrumentation-http": "^0.218.0",
-    "@opentelemetry/instrumentation-pino": "^0.64.0",
-    "@opentelemetry/resources": "^2.7.1",
-    "@opentelemetry/sdk-metrics": "^2.7.1",
-    "@opentelemetry/sdk-node": "^0.218.0",
-    "@opentelemetry/sdk-trace-node": "^2.7.1",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.219.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
+    "@opentelemetry/instrumentation-http": "^0.219.0",
+    "@opentelemetry/instrumentation-pino": "^0.65.0",
+    "@opentelemetry/resources": "^2.8.0",
+    "@opentelemetry/sdk-metrics": "^2.8.0",
+    "@opentelemetry/sdk-node": "^0.219.0",
+    "@opentelemetry/sdk-trace-node": "^2.8.0",
     "@opentelemetry/semantic-conventions": "^1.41.1",
     "@supabase/supabase-js": "^2.108.1",
     "@types/bun": "^1.3.14",
@@ -207,6 +233,7 @@
     "depcheck": "^1.4.7",
     "diff": "^9.0.0",
     "execa": "^9.6.1",
+    "fast-check": "^4.8.0",
     "fast-xml-parser": "^5.8.0",
     "ignore": "^7.0.5",
     "js-yaml": "^4.2.0",
@@ -257,7 +284,7 @@
       "url": "https://www.buymeacoffee.com/cyanheads"
     }
   ],
-  "packageManager": "bun@1.3.2",
+  "packageManager": "bun@1.3.11",
   "engines": {
     "bun": ">=1.3.0",
     "node": ">=24.0.0"
@@ -303,8 +330,9 @@
     "better-sqlite3": "^12.0.0",
     "chrono-node": "^2.9.0",
     "defuddle": "^0.18.1",
-    "diff": "latest",
-    "fast-check": "latest",
+    "diff": "^9.0.0",
+    "fast-check": "^4.0.0",
+    "vitest": ">=4.0.0",
     "fast-xml-parser": "^5.8.0",
     "js-yaml": "^4.1.1",
     "linkedom": "^0.18.12",
@@ -402,6 +430,9 @@
     },
     "validator": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   }
 }

package/skills/api-canvas/SKILL.md

@@ -4,7 +4,7 @@ description: >
   DataCanvas primitive reference — a Tier 3 SQL/analytical workspace for tabular MCP servers, backed by DuckDB. Use when registering tables from upstream APIs, running ad-hoc SQL across them, and exporting results. Covers the acquire → register → query → export flow, per-table TTL, the token-sharing pattern for multi-agent collaboration, env config, and Cloudflare Workers fail-closed behavior.
 metadata:
   author: cyanheads
-  version: "1.5"
+  version: "1.6"
   audience: external
   type: reference
 ---
@@ -135,7 +135,7 @@ await instance.registerTable('big_dataset', asyncRows, {
 await instance.registerTable('recent_fetch', rows, { ttlMs: 30 * 60 * 1000 });
 ```
 
-**Schema inference** when `schema` is omitted: sniffer materializes the first 100 rows, unions JS-side types per column, and maps to DuckDB types. Fall-backs to `VARCHAR` for ambiguous unions (string mixed with numerics). Numeric widening: `INTEGER + DOUBLE → DOUBLE`, `INTEGER + BIGINT → BIGINT`. Column ordering follows first-appearance.
+**Schema inference** when `schema` is omitted: sniffer materializes the first 100 rows, unions JS-side types per column, and maps to DuckDB types. All inferred columns are **always nullable** — a sample can prove a column is nullable, but can never prove NOT NULL (a null may appear past the sniff window). Pass an explicit `schema` when `NOT NULL` enforcement is required. Fall-backs to `VARCHAR` for ambiguous unions (string mixed with numerics). Numeric widening: `INTEGER + DOUBLE → DOUBLE`, `INTEGER + BIGINT → BIGINT`. Column ordering follows first-appearance.
 
 **Per-table TTL (`ttlMs`)** — optional sliding TTL for this table specifically. When set:
 - The sweep loop drops the table (and clears its bookkeeping) when its window expires.
@@ -146,7 +146,9 @@ await instance.registerTable('recent_fetch', rows, { ttlMs: 30 * 60 * 1000 });
 
 ### `instance.query(sql, options?)`
 
-Run SQL across registered tables. Returns at most `rowLimit` rows (default 10 000). For full result sets, pass `registerAs` — the result is materialized as a new canvas table; the response carries a `preview` slice plus the table reference.
+Run SQL across registered tables. Returns at most `rowLimit` rows (default 10 000). When the result exceeds `rowLimit`, the response carries `truncated: true` and `rowCount` reflects the number of materialized rows (not the full result set). For full result sets and exact counts, pass `registerAs` — the result is materialized as a new canvas table; the response carries a `preview` slice and the exact `rowCount`.
+
+Querying a table that does not exist throws `NotFound` (`data.reason: 'missing_table'`) with a recovery hint to re-stage the table or call `describe()`. This happens when a table has expired (per-table TTL), been dropped, or the name is mistyped. The error is `NotFound`, not `ValidationError` — agents should re-stage, not fix the SQL shape.
 
 ```ts
 const result = await instance.query(`
@@ -172,7 +174,9 @@ const chained = await instance.query(
 
 `ttlMs` on `query({ registerAs })` assigns a per-table TTL to the materialized table — the same sliding semantics as `registerTable({ ttlMs })`. The SQL text is also scanned for referenced table names; any tracked per-table TTL entry found is slid on each `query()` call.
 
-**Read-only enforcement** (four layers):
+`denySystemCatalogs?: boolean` (default `false`) — when `true`, the gate rejects any reference to system catalog namespaces (`information_schema`, `pg_catalog`, `sqlite_master`, `duckdb_<name>()` calls) at the text-scan layer before the query executes. Use on shared canvases where handle possession is the access boundary — catalog namespaces let callers enumerate every staged handle. Rejection throws `ValidationError` with `data.reason: 'system_catalog_access'`. Canvas-token servers that explicitly expose `describe()` to agents do not need this; only servers that intentionally hide the full catalog should opt in.
+
+**Read-only enforcement** (four layers + optional catalog layer):
 1. Text-level deny-list — pre-parse scan for file/HTTP-reading table functions (`read_csv*`, `read_json*`, `read_parquet*`, `read_text`, `read_blob`, `glob`, `iceberg_scan`, `delta_scan`, `postgres_scan`, `mysql_scan`, `sqlite_scan`, plus pre-staged spatial ones).
 2. Statement count (must be 1) via `extractStatements`.
 3. Statement type (must be `SELECT`) via `prepared.statementType`.
@@ -182,7 +186,7 @@ Any layer's rejection throws `ValidationError` with a structured `data.reason`.
 
 ### `instance.registerView(name, selectSql, options?)`
 
-Register a SQL view on the canvas. The `SELECT` runs through the same four-layer gate `query()` enforces, so a malicious definition fails at registration time, not later when the view is referenced.
+Register a SQL view on the canvas. The `SELECT` runs through the same gate `query()` enforces (four layers), so a malicious definition fails at registration time, not later when the view is referenced. Pass `{ denySystemCatalogs: true }` to also block catalog namespace references in the view definition — same semantics as the `query()` flag.
 
 ```ts
 await instance.registerView(
@@ -224,7 +228,7 @@ await instance.export('g_with_obs', { format: 'csv', stream: writableStream });
 
 ```ts
 const tables = await instance.describe();
-// [{ name: 'germplasm', kind: 'table', rowCount: 200, columns: [...] }, ...]
+// [{ name: 'germplasm', kind: 'table', rowCount: 200, approxSizeBytes: 8192, columns: [...] }, ...]
 
 // Filter by kind ('table' | 'view').
 const onlyViews = await instance.describe({ kind: 'view' });
@@ -235,6 +239,8 @@ await instance.clear();                  // returns count dropped (drops views b
 
 `TableInfo.kind` discriminates `'table'` vs `'view'`. For views, `rowCount` is materialized at describe time via `COUNT(*)` — not free; treat as an approximation if the view is expensive.
 
+`TableInfo.approxSizeBytes` is set for base tables (DuckDB's `estimated_size` from `duckdb_tables()`). It is `undefined` for views — views have no entry in `duckdb_tables()`. Use it to decide what to drop when a canvas approaches its memory limit.
+
 ### Cancellation
 
 `registerTable`, `query`, and `export` accept `options.signal: AbortSignal`. The provider opens a fresh DuckDB connection per query/export so `connection.interrupt()` cancels exactly the in-flight work without disturbing other ops on the same canvas.

package/skills/api-testing/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Testing patterns for MCP tool/resource handlers using `createMockContext` and Vitest. Covers mock context options, handler testing, McpError assertions, format testing, Vitest config setup, and test isolation conventions.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.5"
   audience: external
   type: reference
 ---
@@ -19,6 +19,52 @@ Tests target handler behavior directly — call `handler(input, ctx)`, assert on
 
 ---
 
+## `mcpTest` — fixture-based Vitest test
+
+`mcpTest` is a `test.extend`-based Vitest test that provides `ctx` and `storage` as **per-test fixtures** — fresh instances for every test, eliminating the `createMockContext()` boilerplate and enforcing the fresh-context-per-test convention automatically.
+
+```ts
+import { mcpTest } from '@cyanheads/mcp-ts-core/testing/vitest';
+
+mcpTest('echoes the message', async ({ ctx }) => {
+  const result = await echoTool.handler(echoTool.input.parse({ message: 'hi' }), ctx);
+  expect(result.message).toBe('hi');
+});
+
+mcpTest('uses storage fixture', async ({ ctx, storage }) => {
+  const svc = new MyService(config, storage);
+  const result = await svc.doWork(ctx);
+  expect(result).toBeDefined();
+});
+```
+
+### Fixtures
+
+| Fixture | Type | Per-test? | Notes |
+|:--------|:-----|:----------|:------|
+| `ctx` | `Context` | Yes | Fresh `createMockContext()` each test |
+| `storage` | `StorageService` | Yes | Fresh `createInMemoryStorage()` each test |
+
+### Extending with the function form
+
+Override fixtures using the **function form** (`async ({}, use) => { ... }`) to preserve per-test freshness. A bare-value override shares one mutable instance across the entire file — defeating the fixture's isolation guarantee.
+
+```ts
+import { createMockContext } from '@cyanheads/mcp-ts-core/testing/vitest';
+
+// Correct — function form gives each test a fresh context:
+const tenantTest = mcpTest.extend({
+  ctx: async ({}, use) => { await use(createMockContext({ tenantId: 'test-tenant' })); },
+});
+
+// Wrong — bare value shares one ctx across every test in the file:
+// const tenantTest = mcpTest.extend({ ctx: createMockContext({ tenantId: 'test-tenant' }) });
+```
+
+`createMockContext` and `createInMemoryStorage` are re-exported from `@cyanheads/mcp-ts-core/testing/vitest` so overrides don't need a second import.
+
+---
+
 ## `createMockContext` options
 
 ```ts
@@ -311,6 +357,22 @@ Use `.rejects.toThrow(McpError)` to assert type only. Use `.rejects.toMatchObjec
 
 ---
 
+## Output schema assertions
+
+`expect.schemaMatching` (Vitest 4, Standard Schema) validates a value against any Zod schema — including the definition's own `output`. Use it to assert schema conformance without duplicating the shape in the test:
+
+```ts
+it('output conforms to the declared output schema', async () => {
+  const ctx = createMockContext();
+  const result = await myTool.handler(myTool.input.parse({ query: 'x' }), ctx);
+  expect(result).toEqual(expect.schemaMatching(myTool.output));
+});
+```
+
+It composes as an asymmetric matcher anywhere a value is expected — e.g. `toHaveBeenCalledWith(expect.schemaMatching(schema))`. Prefer exact-value assertions when the expected output is fully known; reach for `schemaMatching` when the output is dynamic (timestamps, generated IDs) or the schema itself is the contract under test.
+
+---
+
 ## Testing handlers with `errors[]` (typed contract)
 
 Tools and resources that declare an `errors[]` contract receive a typed `ctx.fail` helper at runtime. Pass the definition's own `errors` to `createMockContext` and the mock wires `fail` the same way the production handler factory does:

package/skills/api-workers/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Cloudflare Workers deployment using `createWorkerHandler` from `@cyanheads/mcp-ts-core/worker`. Covers the full handler signature, binding types, CloudflareBindings extensibility, runtime compatibility guards, and wrangler.toml requirements.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: reference
 ---
@@ -198,3 +198,99 @@ export function getServerConfig() {
 > `DuckDB canvas requires Node.js or Bun. Set CANVAS_PROVIDER_TYPE=none or omit it for Cloudflare Workers deployment.`
 
 Leave the env unset (or set to `none`) for Worker deployments. Tools that conditionally use canvas should check the module-level accessor (`if (!getCanvas()) { ... }`) and surface a clear "feature unavailable on this deployment" message. See `api-canvas` for the full DataCanvas reference and setup wiring pattern.
+
+---
+
+## Testing Workers with miniflare
+
+`bun run test:worker` runs the worker suite under `vitest.worker.ts` (using `@cloudflare/vitest-pool-workers` + miniflare). Each test **file** gets its own fresh V8 isolate — module scope (including `createWorkerHandler`'s `appPromise` singleton) is reset between files.
+
+### vitest.worker.ts miniflare bindings
+
+Declare all storage bindings used in the suite:
+
+```ts
+cloudflareTest({
+  main: './tests/fixtures/worker-runtime.fixture.ts',
+  miniflare: {
+    bindings: { STORAGE_PROVIDER_TYPE: 'cloudflare-kv', ... },
+    kvNamespaces: ['KV_NAMESPACE', 'CUSTOM_KV'],
+    r2Buckets:    ['R2_BUCKET'],
+    d1Databases:  ['DB'],
+  },
+})
+```
+
+Binding names must match the hardcoded names in `storageFactory.ts` (`KV_NAMESPACE`, `R2_BUCKET`, `DB`).
+
+### Per-provider test isolation
+
+`bindings.STORAGE_PROVIDER_TYPE` is a global default. Per-provider test files override it by passing a modified env to `worker.fetch()`:
+
+```ts
+import { env } from 'cloudflare:workers';
+
+// Fresh isolate per file — appPromise starts null.
+// First fetch initialises the singleton with the overridden provider type.
+const r2Env = { ...env, STORAGE_PROVIDER_TYPE: 'cloudflare-r2' };
+await worker.fetch(request, r2Env, ctx);
+```
+
+Use `reset()` from `cloudflare:test` in `afterEach` to clear binding state between tests. For D1, re-apply migrations immediately after each `reset()` (reset wipes the schema):
+
+```ts
+import { applyD1Migrations, reset } from 'cloudflare:test';
+
+afterEach(async () => {
+  await reset();
+  await applyD1Migrations(env.DB, [{ name: '0001_schema', queries: [CREATE_TABLE_SQL] }]);
+});
+```
+
+### D1 schema setup
+
+The `cloudflare-d1` provider requires the `kv_store` table before any operations. Apply it in `beforeAll` via `applyD1Migrations`:
+
+```ts
+const KV_STORE_MIGRATION = `
+CREATE TABLE IF NOT EXISTS kv_store (
+  tenant_id TEXT NOT NULL,
+  key       TEXT NOT NULL,
+  value     TEXT NOT NULL,
+  expires_at INTEGER,
+  PRIMARY KEY (tenant_id, key)
+)`;
+
+beforeAll(async () => {
+  await applyD1Migrations(env.DB, [
+    { name: '0001_create_kv_store', queries: [KV_STORE_MIGRATION] },
+  ]);
+  sessionId = await openSession(d1Env);
+});
+```
+
+### R2 list limit
+
+The R2 provider fetches `limit + 1` objects to detect further pages. Miniflare caps R2 `MaxKeys` at 1000, so the default `limit=1000` → request 1001 → error. Pass `limit: 100` (or any value ≤ 999) to `ctx.state.list()` in test fixtures to stay under the cap:
+
+```ts
+const result = await ctx.state.list(prefix, { limit: 100 });
+```
+
+### Storage probe pattern
+
+Expose storage operations as MCP tools in the fixture to test them through the real HTTP surface:
+
+```ts
+const storageSetTool = tool('storage_set', {
+  input: z.object({ key: z.string().describe('...'), value: z.string().describe('...') }),
+  output: z.object({ ok: z.boolean().describe('Always true on success') }),
+  async handler(input, ctx) {
+    await ctx.state.set(input.key, input.value);
+    return { ok: true };
+  },
+  format: (r) => [{ type: 'text', text: `ok=${r.ok}` }],
+});
+```
+
+Call via `tools/call` over MCP JSON-RPC and assert on `structuredContent`. See `tests/worker/storage-r2.worker.test.ts` and `tests/worker/storage-d1.worker.test.ts` for the full pattern.

package/templates/Dockerfile

@@ -114,5 +114,8 @@ ENV MCP_FORCE_CONSOLE_LOGGING="true"
 # Expose the port the server listens on
 EXPOSE ${MCP_HTTP_PORT}
 
+# Health check using a bun-native fetch (slim image ships no curl/wget)
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD bun -e "fetch('http://localhost:'+(process.env.MCP_HTTP_PORT??'3010')+'/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
 # The command to start the server
 CMD ["bun", "run", "dist/index.js"]

package/templates/package.json

@@ -62,12 +62,12 @@
     "zod": "{{ZOD_VERSION}}"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.7",
-    "@types/node": "^25.6.0",
+    "@biomejs/biome": "2.4.16",
+    "@types/node": "25.9.3",
     "depcheck": "^1.4.7",
     "ignore": "^7.0.5",
-    "tsc-alias": "^1.8.16",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "tsc-alias": "^1.8.17",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
   }
 }

package/templates/tests/tools/echo.tool.test.ts

@@ -5,8 +5,29 @@
 
 import { describe, expect, it } from 'vitest';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+import { mcpTest } from '@cyanheads/mcp-ts-core/testing/vitest';
 import { echoTool } from '@/mcp-server/tools/definitions/echo.tool.js';
 
+// ---------------------------------------------------------------------------
+// Fixture-based tests (mcpTest) — fresh ctx per test, no manual construction
+// ---------------------------------------------------------------------------
+
+mcpTest('echoTool: echoes the message back (fixture)', async ({ ctx }) => {
+  const input = echoTool.input.parse({ message: 'hello world' });
+  const result = await echoTool.handler(input, ctx);
+  expect(result).toEqual({ message: 'hello world' });
+});
+
+mcpTest('echoTool: output conforms to declared schema (fixture)', async ({ ctx }) => {
+  const input = echoTool.input.parse({ message: 'hello world' });
+  const result = await echoTool.handler(input, ctx);
+  expect(result).toEqual(expect.schemaMatching(echoTool.output));
+});
+
+// ---------------------------------------------------------------------------
+// Classic describe/it tests (createMockContext) — shown for comparison
+// ---------------------------------------------------------------------------
+
 describe('echoTool', () => {
   it('echoes the message back', async () => {
     const ctx = createMockContext();
@@ -15,6 +36,13 @@ describe('echoTool', () => {
     expect(result).toEqual({ message: 'hello world' });
   });
 
+  it('output conforms to the declared output schema', async () => {
+    const ctx = createMockContext();
+    const input = echoTool.input.parse({ message: 'hello world' });
+    const result = await echoTool.handler(input, ctx);
+    expect(result).toEqual(expect.schemaMatching(echoTool.output));
+  });
+
   it('formats output as text content', () => {
     const blocks = echoTool.format!({ message: 'hello world' });
     expect(blocks).toEqual([{ type: 'text', text: 'hello world' }]);

package/tsconfig.base.json

@@ -20,7 +20,6 @@
     "declarationMap": true,
     "sourceMap": true,
 
-    "importHelpers": true,
     "incremental": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,

package/dist/logs/combined.log

@@ -1,4 +0,0 @@
-{"level":40,"time":1781133231939,"env":"testing","version":"0.10.3","pid":80401,"transport":"http","requestId":"PAZLD-YA82Z","timestamp":"2026-06-10T23:13:51.938Z","operation":"TransportManager.start","component":"HttpTransportSetup","msg":"MCP_ALLOWED_ORIGINS is not set — CORS is wildcard for CLI clients; browser Origin headers are restricted to loopback. Set MCP_ALLOWED_ORIGINS for production deployments accepting remote browser origins."}
-{"level":40,"time":1781133233685,"env":"testing","version":"0.10.3","pid":80401,"component":"HttpTransport","requestId":"2ISX1-LS2V4","timestamp":"2026-06-10T23:13:53.685Z","operation":"HttpRpcRequest","sessionId":"not-a-real-session-1781133233685","msg":"Session validation failed - invalid or hijacked session"}
-{"level":50,"time":1781133237889,"env":"testing","version":"0.0.0-test","pid":80550,"requestId":"RD4D8-H3QV1","timestamp":"2026-06-10T23:13:57.888Z","operation":"HandleToolRequest","critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"b6c3787ad9d5f6d3b11827959b7c06d08b23e57c3b1f8aee6dc7dbdb5d6ffa55","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"errorData":{"sessionId":"b6c3787ad9d5f6d3b11827959b7c06d08b23e57c3b1f8aee6dc7dbdb5d6ffa55","toolName":"scoped_echo","requestId":"RD4D8-H3QV1","timestamp":"2026-06-10T23:13:57.888Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n    at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n    at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:68:15)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:283:17)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n    at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:170:23)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:324:26)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}
-{"level":50,"time":1781133237899,"env":"testing","version":"0.0.0-test","pid":80550,"requestId":"GBWGR-X2TSW","timestamp":"2026-06-10T23:13:57.899Z","operation":"HandleToolRequest","critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"d540d7df1cdbaf04f12a646d555d508ac0db2e191d0a5282980a2327f57f727f","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["openid","email","profile","offline_access"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"errorData":{"sessionId":"d540d7df1cdbaf04f12a646d555d508ac0db2e191d0a5282980a2327f57f727f","toolName":"scoped_echo","requestId":"GBWGR-X2TSW","timestamp":"2026-06-10T23:13:57.899Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["openid","email","profile","offline_access"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n    at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n    at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:68:15)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:283:17)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n    at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:170:23)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:324:26)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}

package/dist/logs/error.log

@@ -1,2 +0,0 @@
-{"level":50,"time":1781133237889,"env":"testing","version":"0.0.0-test","pid":80550,"requestId":"RD4D8-H3QV1","timestamp":"2026-06-10T23:13:57.888Z","operation":"HandleToolRequest","critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"b6c3787ad9d5f6d3b11827959b7c06d08b23e57c3b1f8aee6dc7dbdb5d6ffa55","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"errorData":{"sessionId":"b6c3787ad9d5f6d3b11827959b7c06d08b23e57c3b1f8aee6dc7dbdb5d6ffa55","toolName":"scoped_echo","requestId":"RD4D8-H3QV1","timestamp":"2026-06-10T23:13:57.888Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n    at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n    at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:68:15)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:283:17)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n    at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:170:23)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:324:26)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}
-{"level":50,"time":1781133237899,"env":"testing","version":"0.0.0-test","pid":80550,"requestId":"GBWGR-X2TSW","timestamp":"2026-06-10T23:13:57.899Z","operation":"HandleToolRequest","critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"d540d7df1cdbaf04f12a646d555d508ac0db2e191d0a5282980a2327f57f727f","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["openid","email","profile","offline_access"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"errorData":{"sessionId":"d540d7df1cdbaf04f12a646d555d508ac0db2e191d0a5282980a2327f57f727f","toolName":"scoped_echo","requestId":"GBWGR-X2TSW","timestamp":"2026-06-10T23:13:57.899Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["openid","email","profile","offline_access"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n    at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n    at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:68:15)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:283:17)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n    at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:170:23)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:324:26)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}