@cyanheads/mcp-ts-core 0.10.2 → 0.10.4

package/dist/testing/index.d.ts

@@ -5,16 +5,21 @@
  * `createInMemoryStorage()` for unit-testing services in isolation.
  * @module src/testing/index
  */
-import type { CreateMessageResult, ElicitResult, SamplingMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { ElicitResult } from '@modelcontextprotocol/sdk/types.js';
 import type { z } from 'zod';
-import type { AuthContext, Context, ContextLogger, SamplingOpts } from '../core/context.js';
+import type { AuthContext, Context, ContextLogger } from '../core/context.js';
 import { StorageService } from '../storage/core/StorageService.js';
 import { type InMemoryProviderOptions } from '../storage/providers/inMemory/inMemoryProvider.js';
 import type { ErrorContract } from '../types-global/errors.js';
 export interface MockContextOptions {
     /** Auth context. */
     auth?: AuthContext;
-    /** Mock elicitation handler. */
+    /**
+     * Mock elicitation handler for form-mode elicitation. When provided, the
+     * mock context's `ctx.elicit` is set to this function with a default no-op
+     * `.url(...)` stub attached — tests that only exercise form-mode elicitation
+     * don't need to supply `.url` explicitly.
+     */
     elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
     /**
      * Error contract to attach a typed `ctx.fail` against. Pass the definition's
@@ -35,8 +40,6 @@ export interface MockContextOptions {
     progress?: boolean;
     /** Request ID override. Defaults to 'test-request-id'. */
     requestId?: string;
-    /** Mock sampling handler. */
-    sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
     /**
      * HTTP session ID. Defaults to undefined. Set to exercise handlers that
      * branch on `ctx.sessionId` — mirrors what a stateful HTTP request would
@@ -84,15 +87,6 @@ export declare function createMockLogger(): MockContextLogger;
  * // With tenant (for tools that use ctx.state)
  * const ctx = createMockContext({ tenantId: 'test-tenant' });
  *
- * // With sampling capability
- * const ctx = createMockContext({
- *   sample: vi.fn().mockResolvedValue({
- *     role: 'assistant',
- *     content: { type: 'text', text: 'Response' },
- *     model: 'test',
- *   }),
- * });
- *
  * // With task progress
  * const ctx = createMockContext({ progress: true });
  * ```

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACZ,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAW,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EACP,aAAa,EAGb,YAAY,EACb,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAM9D,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,gCAAgC;IAChC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACxF;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,yCAAyC;IACzC,uBAAuB,CAAC,EAAE,MAAM,IAAI,CAAC;IACrC,2CAA2C;IAC3C,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,sCAAsC;IACtC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,uCAAuC;IACvC,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5F;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAMD,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG;IAC9C,mFAAmF;IACnF,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CAiBpD;AAwGD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAsC3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,cAAc,CAEvF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAW,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EACP,aAAa,EAId,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAM9D,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACxF;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,yCAAyC;IACzC,uBAAuB,CAAC,EAAE,MAAM,IAAI,CAAC;IACrC,2CAA2C;IAC3C,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,sCAAsC;IACtC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,uCAAuC;IACvC,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAMD,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG;IAC9C,mFAAmF;IACnF,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CAiBpD;AAwGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAgD3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,cAAc,CAEvF"}

package/dist/testing/index.js

@@ -140,15 +140,6 @@ function createMockProgress() {
  * // With tenant (for tools that use ctx.state)
  * const ctx = createMockContext({ tenantId: 'test-tenant' });
  *
- * // With sampling capability
- * const ctx = createMockContext({
- *   sample: vi.fn().mockResolvedValue({
- *     role: 'assistant',
- *     content: { type: 'text', text: 'Response' },
- *     model: 'test',
- *   }),
- * });
- *
  * // With task progress
  * const ctx = createMockContext({ progress: true });
  * ```
@@ -158,6 +149,15 @@ export function createMockContext(options = {}) {
     const state = createMockState(options.tenantId);
     const progress = options.progress ? createMockProgress() : undefined;
     const enrichmentStore = createEnrichmentStore();
+    // Wrap the caller's elicit mock into an ElicitFn so that tests calling
+    // ctx.elicit.url(...) don't throw TypeError. The default url stub returns a
+    // cancelled result and can be overridden by casting the mock to ElicitFn.
+    let elicit;
+    if (options.elicit) {
+        const base = options.elicit;
+        base.url = async (_message, _url) => ({ action: 'cancel' });
+        elicit = base;
+    }
     const ctx = {
         requestId: options.requestId ?? 'test-request-id',
         timestamp: new Date().toISOString(),
@@ -167,8 +167,7 @@ export function createMockContext(options = {}) {
         tenantId: options.tenantId,
         sessionId: options.sessionId,
         auth: options.auth,
-        elicit: options.elicit,
-        sample: options.sample,
+        elicit,
         notifyPromptListChanged: options.notifyPromptListChanged,
         notifyResourceListChanged: options.notifyResourceListChanged,
         notifyResourceUpdated: options.notifyResourceUpdated,

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "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,93 @@
   "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"
     },
     "./tsconfig.base.json": "./tsconfig.base.json",
     "./vitest.config": "./vitest.config.base.mjs",
@@ -148,8 +166,10 @@
     "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",
@@ -193,7 +213,7 @@
     "@supabase/supabase-js": "^2.108.1",
     "@types/bun": "^1.3.14",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.9.2",
+    "@types/node": "25.9.3",
     "@types/papaparse": "^5.5.2",
     "@types/sanitize-html": "^2.16.1",
     "@types/validator": "^13.15.10",
@@ -207,6 +227,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 +278,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 +324,8 @@
     "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",
     "fast-xml-parser": "^5.8.0",
     "js-yaml": "^4.1.1",
     "linkedom": "^0.18.12",

package/skills/add-prompt/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP prompt template. Use when the user asks to add a prompt, create a reusable message template, or define a prompt for LLM interactions.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
@@ -30,14 +30,18 @@ Prompts are pure message templates — no `Context`, no auth, no side effects. `
  * @module mcp-server/prompts/definitions/{{PROMPT_NAME}}
  */
 
-import { prompt, z } from '@cyanheads/mcp-ts-core';
+import { completable, prompt, z } from '@cyanheads/mcp-ts-core';
 
 export const {{PROMPT_EXPORT}} = prompt('{{prompt_name}}', {
   description: '{{PROMPT_DESCRIPTION}}',
+  // title is optional — human-readable display name surfaced in prompts/list.
+  // title: '{{PROMPT_DISPLAY_TITLE}}',
   // args is optional — omit entirely for prompts with no parameters.
   // When present, all fields need .describe(). Only JSON-Schema-serializable types allowed.
+  // Wrap any field with completable() to enable argument autocompletion.
   args: z.object({
     // All fields need .describe()
+    // language: completable(z.string().describe('Language'), async (partial) => matchingLanguages(partial)),
   }),
   generate: (args) => [
     {
@@ -92,13 +96,40 @@ If the repo already uses `src/mcp-server/prompts/definitions/index.ts`, add the
 export { {{PROMPT_EXPORT}} } from './{{prompt-name}}.prompt.js';
 ```
 
+## Argument autocompletion
+
+Wrap any `args` field with `completable()` (re-exported from `@cyanheads/mcp-ts-core`) to enable argument autocompletion. The SDK auto-installs `completion/complete` handling and advertises the `completions` capability when any registered prompt has a completable argument — no other changes are needed.
+
+```typescript
+import { completable, prompt, z } from '@cyanheads/mcp-ts-core';
+
+export const codeReview = prompt('code_review', {
+  description: 'Review code for issues.',
+  title: 'Code Review',
+  args: z.object({
+    language: completable(
+      z.string().describe('Programming language'),
+      async (partial) => ['typescript', 'python', 'rust'].filter((l) => l.startsWith(partial)),
+    ),
+    code: z.string().describe('Code to review'),
+  }),
+  generate: (args) => [
+    { role: 'user', content: { type: 'text', text: `Review this ${args.language} code:\n${args.code}` } },
+  ],
+});
+```
+
+`completable()` is transparent to the linter — it does not affect `describe-on-fields` or `schema-serializable` rules. All completable-wrapped fields still require `.describe()` on the underlying schema.
+
 ## Checklist
 
 - [ ] File created at `src/mcp-server/prompts/definitions/{{prompt-name}}.prompt.ts`
 - [ ] Prompt name passed to `prompt()` uses snake_case
 - [ ] `description` field set (lint warns if absent, but `devcheck` won't hard-fail — verify it's present)
+- [ ] `title` field set if a human-readable display name is needed in `prompts/list`
 - [ ] All Zod `args` fields have `.describe()` annotations — or `args` omitted entirely for no-parameter prompts
 - [ ] `args` fields use only JSON-Schema-serializable Zod types (no `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.custom()`, etc.)
+- [ ] If using `completable()`, the underlying schema still has `.describe()` on each wrapped field
 - [ ] JSDoc `@fileoverview` and `@module` header present
 - [ ] `generate` function present and returns at least one `{ role, content: { type: 'text', text } }` message
 - [ ] No side effects — prompts are pure templates

package/skills/add-resource/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP resource definition. Use when the user asks to add a resource, expose data via URI, or create a readable endpoint.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: reference
 ---
@@ -141,6 +141,29 @@ export const articleResource = resource('article://{pmid}', {
 
 Without `errors[]`, the handler receives plain `Context` (no `fail` method) and throws via error factories (`notFound`, `serviceUnavailable`, …) directly. The contract is opt-in. See `skills/api-errors/SKILL.md` for the full pattern, baseline codes, and conformance rules.
 
+### URI template variable completion
+
+Add a `complete` map to enable autocompletion for URI template variables. The SDK auto-installs `completion/complete` handling and advertises the `completions` capability when a registered resource template has completion callbacks — no other changes needed.
+
+```typescript
+import { resource, z } from '@cyanheads/mcp-ts-core';
+
+const ITEM_IDS = ['item-001', 'item-002', 'item-abc'];
+
+export const itemResource = resource('items://{itemId}', {
+  description: 'Retrieve an item by ID.',
+  params: z.object({ itemId: z.string().describe('Item identifier') }),
+  handler: (params) => ({ id: params.itemId }),
+  list: () => ({ resources: ITEM_IDS.map((id) => ({ uri: `items://${id}`, name: id })) }),
+  // Per-variable completion callbacks — keys must match URI template variable names.
+  complete: {
+    itemId: async (partial) => ITEM_IDS.filter((id) => id.startsWith(partial)),
+  },
+});
+```
+
+Only applies to templated resources (URI templates with `{variable}` syntax). Static URIs don't support completion.
+
 ### Other `resource()` options
 
 Beyond `description`, `params`, `handler`, and `list`, the builder also supports:
@@ -153,6 +176,7 @@ Beyond `description`, `params`, `handler`, and `list`, the builder also supports
 | `annotations` | Resource annotations (e.g., `audience`, `priority`) — see `ResourceAnnotations`. |
 | `title` | Human-readable display title (defaults to `name`). |
 | `examples` | Array of `{ name, uri }` example entries surfaced in `resources/list` for discoverability. |
+| `complete` | Per-variable completion callbacks for URI template variables. Keys match template variable names. Enables `completion/complete` and the `completions` capability. |
 
 ## Checklist
 

package/skills/add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
 metadata:
   author: cyanheads
-  version: "1.7"
+  version: "1.8"
   audience: external
   type: reference
 ---
@@ -13,7 +13,7 @@ metadata:
 
 Services use the init/accessor pattern: initialized once in `createApp`'s `setup()` callback, then accessed at request time via a lazy getter. Each service lives in `src/services/[domain]/` with an init function and accessor.
 
-Service methods receive `Context` for correlated logging (`ctx.log`) and tenant-scoped storage (`ctx.state`). Convention: `ctx.elicit` and `ctx.sample` should only be called from tool handlers, not from services.
+Service methods receive `Context` for correlated logging (`ctx.log`) and tenant-scoped storage (`ctx.state`). Convention: `ctx.elicit` should only be called from tool handlers, not from services.
 
 For the full service pattern, `CoreServices`, and `Context` interface, read the framework's `CLAUDE.md`/`AGENTS.md` (loaded at session start).
 

package/skills/add-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a test file for an existing tool, resource, or service. Use when the user asks to add tests, improve coverage, or when a definition exists without a matching test file.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: reference
 ---
@@ -36,7 +36,7 @@ Read the handler and identify:
 | **Input variations** | Optional fields omitted, defaults applied, boundary values |
 | **Error paths** | Invalid state, missing resources, service failures → correct error thrown |
 | **`ctx.state` usage** | Use `createMockContext({ tenantId: 'test' })` to enable storage |
-| **`ctx.elicit` / `ctx.sample`** | Mock with `vi.fn()`, also test the absent case (undefined) |
+| **`ctx.elicit`** | Mock with `vi.fn()`, also test the absent case (undefined) |
 | **`ctx.progress`** | Use `createMockContext({ progress: true })` for task tools |
 | **`ctx.fail` (typed contract)** | Definitions with `errors[]` need `fail` attached to the mock ctx — `createMockContext({ errors: myTool.errors })` does it for you. Assert on `data.reason` (stable per-contract entry), not just `code`. |
 | **`format` function** | Test separately if defined — it's pure, no ctx needed. Verify it renders the IDs and fields the model needs, not just a count or title. For projection-style tools, test non-default field selections. |
@@ -286,7 +286,7 @@ When scaffolding tests for an existing handler, use the Zod schemas to generate
 - [ ] Happy path tested with valid input → expected output
 - [ ] Error paths tested (at least one `.rejects.toThrow()`)
 - [ ] `format` function tested if defined
-- [ ] `createMockContext` options match handler's ctx usage (`tenantId`, `progress`, `elicit`, `sample`)
+- [ ] `createMockContext` options match handler's ctx usage (`tenantId`, `progress`, `elicit`)
 - [ ] Service re-initialized in `beforeEach` if handler depends on a service singleton
 - [ ] If handler has optional fields: tested with empty-string inner values (form-client simulation)
 - [ ] If wrapping external API: sparse-payload case tested — fixture omits at least one optional upstream field; output still validates and `format()` renders uncertainty honestly instead of inventing values

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-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.6"
+  version: "1.7"
   audience: external
   type: reference
 ---
@@ -23,7 +23,7 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod from environment variable
 
 **Priority (highest to lowest):**
 
-1. `name`/`version` overrides passed to `createApp()` or `createWorkerHandler()`
+1. `name`/`version`/`title`/`websiteUrl`/`description`/`icons` options passed to `createApp()` or `createWorkerHandler()`
 2. Environment variables
 3. `package.json` fields
 
@@ -35,9 +35,18 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod from environment variable
 |:--------|:-----------------|:--------|:------|
 | `MCP_SERVER_NAME` | `mcpServerName` | `package.json` `name` | Overrides package name |
 | `MCP_SERVER_VERSION` | `mcpServerVersion` | `package.json` `version` | Overrides package version |
-| `MCP_SERVER_DESCRIPTION` | `mcpServerDescription` | `package.json` `description` | Optional |
+| `MCP_SERVER_DESCRIPTION` | `mcpServerDescription` | `package.json` `description` | Optional; `createApp({ description })` wins when set |
 | `PACKAGE_NAME` | `pkg.name` | `package.json` `name` | Rarely needed |
 | `PACKAGE_VERSION` | `pkg.version` | `package.json` `version` | Rarely needed |
+
+**SDK identity fields** (API-only, no env var equivalent — passed to `createApp()` / `createWorkerHandler()`, forwarded to `initialize` and `/.well-known/mcp.json`):
+
+| Option | Type | Notes |
+|:-------|:-----|:------|
+| `title` | `string?` | Human-readable display name shown in client listings |
+| `websiteUrl` | `string?` | Canonical homepage / repository URL |
+| `description` | `string?` | One-line description; wins over `MCP_SERVER_DESCRIPTION` when set |
+| `icons` | `Implementation['icons']?` | Array of icon objects: `{ src, mimeType?, sizes?: string[], theme?: 'light'\|'dark' }` |
 | `NODE_ENV` | `environment` | `development` | Aliases: `dev`→`development`, `prod`→`production`, `test`→`testing` |
 | `MCP_LOG_LEVEL` | `logLevel` | `debug` | Aliases: `warn`→`warning`, `err`→`error`, `fatal`/`silent`→`emerg`, `trace`→`debug`, `information`→`info` |
 | `LOGS_DIR` | `logsPath` | `<project-root>/logs` | Node.js only; absolute or relative to project root |