@cyanheads/mcp-ts-core 0.10.2 → 0.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "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",
@@ -193,7 +193,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",

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-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 |

package/skills/api-context/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: api-context
 description: >
-  Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.sample`, `ctx.progress`, `ctx.enrich`), and when to use each.
+  Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.progress`, `ctx.enrich`), and when to use each.
 metadata:
   author: cyanheads
-  version: "1.7"
+  version: "1.8"
   audience: external
   type: reference
 ---
 
 ## Overview
 
-Every tool and resource handler receives a single `Context` (`ctx`) argument. It provides request identity, structured logging, tenant-scoped storage, optional protocol capabilities (elicitation, sampling), cancellation, and task progress — all auto-correlated to the current request.
+Every tool and resource handler receives a single `Context` (`ctx`) argument. It provides request identity, structured logging, tenant-scoped storage, optional protocol capabilities (elicitation), cancellation, and task progress — all auto-correlated to the current request.
 
 The framework auto-instruments every handler call (OTel span, duration, payload metrics). Use `ctx.log` for domain-specific logging and `ctx.state` for storage inside handlers. Use the global `logger` and `StorageService` directly only in lifecycle/background code (`setup()`, services).
 
@@ -39,8 +39,7 @@ interface Context {
   readonly state: ContextState;
 
   // Optional protocol capabilities (undefined when client doesn't support them)
-  readonly elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
-  readonly sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
+  readonly elicit?: ElicitFn; // callable (message, schema) for form mode + .url(message, url) — see § ctx.elicit
 
   // List-changed / resource-updated notifications — wired in every handler ctx;
   // delivery is request-scoped (see § list-changed notifications)
@@ -254,9 +253,11 @@ await ctx.state.set(sessionKey, value);
 
 ---
 
-## `ctx.elicit` / `ctx.sample`
+## `ctx.elicit`
 
-Both are optional — `undefined` when the connected client doesn't support the capability. Check for presence before calling. A simple truthiness check is enough; no type guards needed.
+Optional — `undefined` when the connected client doesn't advertise the `elicitation` capability (checked per request, after the initialize handshake). Check for presence before calling. A simple truthiness check is enough; no type guards needed.
+
+`ctx.elicit` is an `ElicitFn` (exported from the main entry): directly callable for form-mode elicitation, with a `.url(message, url)` method for URL-mode. On the wire, the Zod schema is converted to the restricted flat JSON Schema the MCP spec requires — handlers never deal with that detail.
 
 ### `ctx.elicit` — ask the user for structured input
 
@@ -295,37 +296,23 @@ interface ElicitResult {
 
 > **Note:** `content` is not typed against the Zod schema you pass — it is a `Record` of primitives. Validate `content` against your schema manually (e.g. `MySchema.parse(result.content)`) when `action === 'accept'`.
 
-**Convention:** Only call `ctx.elicit` from tool handlers, not from services.
-
-### `ctx.sample` — request an LLM completion from the client
+### `ctx.elicit.url` — hand the user an external link
 
-Requests a completion from the client's LLM via the MCP sampling protocol. Useful for AI-assisted tool behavior without managing a separate LLM provider.
+URL-mode elicitation (MCP 2025-11-25): instead of an inline form, the client directs the user to an external URL — authorization flows, hosted forms. The framework generates the protocol-required `elicitationId` internally.
 
 ```ts
-if (ctx.sample) {
-  const result = await ctx.sample(
-    [
-      { role: 'user', content: { type: 'text', text: `Summarize: ${data}` } },
-    ],
-    { maxTokens: 500 },
+if (ctx.elicit) {
+  const result = await ctx.elicit.url(
+    'Authorize access to your account',
+    'https://example.com/oauth/authorize?state=...',
   );
-  return { summary: result.content.text };
+  if (result.action !== 'accept') throw forbidden('Authorization declined');
 }
 ```
 
-`SamplingOpts`:
+`result.content` is absent in URL mode — the interaction completes out-of-band; only `action` reports the outcome.
 
-```ts
-interface SamplingOpts {
-  includeContext?: 'none' | 'thisServer' | 'allServers';
-  maxTokens?: number;
-  modelPreferences?: ModelPreferences;
-  stopSequences?: string[];
-  temperature?: number;
-}
-```
-
-**Convention:** Only call `ctx.sample` from tool handlers, not from services.
+**Convention:** Only call `ctx.elicit` from tool handlers, not from services.
 
 ---
 
@@ -666,7 +653,6 @@ See `add-tool`'s **Tool Response Design** and `skills/api-linter` (`enrichment-*
 | `ctx.signal` | `AbortSignal` | Always |
 | `ctx.enrich` | `Enrich` | Always; typed on `HandlerContext<R, E>` when an `enrichment` block is declared |
 | `ctx.elicit` | `function \| undefined` | Client supports elicitation |
-| `ctx.sample` | `function \| undefined` | Client supports sampling |
 | `ctx.notifyResourceListChanged` | `function \| undefined` | Always in handler ctx; delivery request-scoped (see [§ list-changed notifications](#list-changed-notifications-ctxnotify)) |
 | `ctx.notifyResourceUpdated` | `function \| undefined` | Always in handler ctx; delivery request-scoped |
 | `ctx.notifyPromptListChanged` | `function \| undefined` | Always in handler ctx; delivery request-scoped |

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.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
@@ -27,7 +27,6 @@ import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
 createMockContext()                                           // minimal — ctx.state operations throw without tenantId
 createMockContext({ tenantId: 'test-tenant' })               // enables ctx.state (tenant-scoped in-memory storage)
 createMockContext({ errors: myTool.errors })                 // attaches typed ctx.fail keyed by the contract reasons
-createMockContext({ sample: vi.fn().mockResolvedValue(...) }) // with MCP sampling
 createMockContext({ elicit: vi.fn().mockResolvedValue(...) }) // with elicitation
 createMockContext({ progress: true })                        // with task progress (ctx.progress populated)
 createMockContext({ requestId: 'my-id' })                    // override request ID (default: 'test-request-id')
@@ -52,7 +51,6 @@ interface MockContextOptions {
   progress?: boolean;
   sessionId?: string;
   requestId?: string;
-  sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
   signal?: AbortSignal;
   tenantId?: string;
   uri?: URL;
@@ -61,7 +59,7 @@ interface MockContextOptions {
 
 | Option | Effect |
 |:-------|:-------|
-| _(none)_ | Minimal context — `ctx.state` operations throw without `tenantId`; `ctx.elicit`/`ctx.sample`/`ctx.progress` are `undefined` |
+| _(none)_ | Minimal context — `ctx.state` operations throw without `tenantId`; `ctx.elicit`/`ctx.progress` are `undefined` |
 | `auth` | Sets `ctx.auth` for scope-checking tests |
 | `elicit` | Assigns a function to `ctx.elicit` for testing elicitation calls |
 | `errors` | Attaches a typed `ctx.fail` against the contract — same wiring the production handler factory uses. Pass `myTool.errors` directly. |
@@ -72,7 +70,6 @@ interface MockContextOptions {
 | `sessionId` | Sets `ctx.sessionId` for handlers that branch on session ID |
 | `progress` | Populates `ctx.progress` with real state-tracking implementation (see below) |
 | `requestId` | Overrides `ctx.requestId` (default: `'test-request-id'`) |
-| `sample` | Assigns a function to `ctx.sample` for testing sampling calls |
 | `signal` | Overrides `ctx.signal` — useful for cancellation testing |
 | `tenantId` | Sets `ctx.tenantId` and enables `ctx.state` operations with in-memory storage |
 | `uri` | Sets `ctx.uri` for resource handler testing |
@@ -164,17 +161,6 @@ it('uses elicitation when available', async () => {
   expect(elicit).toHaveBeenCalledOnce();
 });
 
-it('uses sampling when available', async () => {
-  const sample = vi.fn().mockResolvedValue({
-    role: 'assistant',
-    content: { type: 'text', text: 'Summary text' },
-  });
-  const ctx = createMockContext({ sample });
-  const input = myTool.input.parse({ query: 'summarize this' });
-  const result = await myTool.handler(input, ctx);
-  expect(result.summary).toBeDefined();
-});
-
 it('handles missing elicitation gracefully', async () => {
   // ctx.elicit is undefined — handler must check before calling
   const ctx = createMockContext();

package/skills/code-simplifier/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Post-session code review and cleanup against a working tree of changes. Analyzes `git diff` to simplify, consolidate, and align changed code with the existing codebase — modernize syntax, remove unnecessary complexity, consolidate duplicated logic, catch efficiency issues. Use after a substantive working session, or when asked to clean up, simplify, reduce slop, consolidate, modernize, tighten up, or de-slop code. For `@cyanheads/mcp-ts-core` projects, includes specific transformations for tool/resource/prompt definitions, the ctx pattern, error factories, and framework idioms.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: workflow
 ---
@@ -62,7 +62,7 @@ Evaluate the changes across these dimensions. Not every dimension applies to eve
 
 - **Error throwing patterns** — Prefer framework error factories (`McpError`, `validationError`, `notFound`, `httpErrorFromResponse`) over raw `throw new Error()`. Tool handlers should throw — the framework catches, classifies, and instruments.
 - **Error codes** — `InvalidParams` only for malformed JSON-RPC params shape. `ValidationError` for domain validation. `NotFound` for missing entities. Don't conflate them.
-- **Ctx usage** — Use `ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.sample` — don't reach for global loggers, request-scoped storage, or sampling APIs directly. The `ctx` pattern carries tenant scope and OTel context.
+- **Ctx usage** — Use `ctx.log`, `ctx.state`, `ctx.elicit` — don't reach for global loggers or request-scoped storage directly. The `ctx` pattern carries tenant scope and OTel context.
 - **Zod schemas** — Every tool input/output field needs `.describe()`. Zod 4 requires `z.record(z.string(), z.string())` not `z.record(z.string())`. Use `.optional()` rather than `.nullish()` unless null is semantically distinct from absent.
 - **Tool annotations** — `readOnlyHint`, `idempotentHint`, `openWorldHint` should reflect reality. A read-only tool with `readOnlyHint: false` gives clients the wrong picture.
 - **`exactOptionalPropertyTypes` boundaries** — If a downstream type insists on the field being present-or-not-present (not present-as-undefined), use a mapped widening type at the boundary. The pattern is documented in the framework.

package/skills/polish-docs-meta/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "2.5"
+  version: "2.6"
   audience: external
   type: workflow
 ---

package/skills/polish-docs-meta/references/agent-protocol.md

@@ -46,7 +46,7 @@ Compare the structure diagram against the actual directory layout. If it still r
 
 ### 4. Update the Context Table
 
-Review the `ctx` feature table. Remove rows for features the server doesn't use (e.g., `ctx.elicit`, `ctx.sample` if no tools call them). Add any custom context usage that's become important. The table should reflect what this server actually uses, not the full framework surface.
+Review the `ctx` feature table. Remove rows for features the server doesn't use (e.g., `ctx.elicit` if no tools call it). Add any custom context usage that's become important. The table should reflect what this server actually uses, not the full framework surface.
 
 ### 5. Update Server Config Example
 

package/skills/report-issue-framework/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
 metadata:
   author: cyanheads
-  version: "1.7"
+  version: "1.8"
   audience: external
   type: workflow
 ---
@@ -148,7 +148,7 @@ Format: `bug(<scope>): concise description`
 | `tool` | Tool builder, handler, format, annotations |
 | `resource` | Resource builder, handler, list, params |
 | `prompt` | Prompt builder, generate, args |
-| `context` | Context, logger, state, progress, elicit, sample |
+| `context` | Context, logger, state, progress, elicit |
 | `config` | AppConfig, parseConfig, env parsing |
 | `errors` | McpError, error factories, typed contracts (`errors[]` / `ctx.fail`), conformance lint, `httpErrorFromResponse`, auto-classification |
 | `auth` | Auth modes, scope checking, JWT/OAuth |

package/skills/security-pass/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: security-pass
 description: >
-  Review an MCP server for common security gaps: LLM-facing surfaces as injection vector (tools, resources, prompts, descriptions), scope blast radius, destructive ops without consent, upstream auth shape, input sinks (URL / path / roots / shell / sampling / schema strictness / ReDoS), tenant isolation, leakage through errors and telemetry, unbounded resources, and HTTP-mode deployment surface. Use before a release, after a batch of handler changes, or when the user asks for a security review, audit, or hardening pass. Produces grouped findings and a numbered options list.
+  Review an MCP server for common security gaps: LLM-facing surfaces as injection vector (tools, resources, prompts, descriptions), scope blast radius, destructive ops without consent, upstream auth shape, input sinks (URL / path / roots / shell / schema strictness / ReDoS), tenant isolation, leakage through errors and telemetry, unbounded resources, and HTTP-mode deployment surface. Use before a release, after a batch of handler changes, or when the user asks for a security review, audit, or hardening pass. Produces grouped findings and a numbered options list.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: audit
 ---
@@ -44,7 +44,7 @@ find src/mcp-server/prompts/definitions -name "*.prompt.ts" 2>/dev/null | sort
 find src/services -maxdepth 1 -mindepth 1 -type d | sort
 ```
 
-Note: tool / resource / prompt counts, auth mode, storage provider, upstream APIs, which tools have `destructiveHint`, which handlers use `ctx.sample` or `ctx.elicit`, which services hold module-scope state, whether the server reads `roots`.
+Note: tool / resource / prompt counts, auth mode, storage provider, upstream APIs, which tools have `destructiveHint`, which handlers use `ctx.elicit`, which services hold module-scope state, whether the server reads `roots`.
 
 **If transport is streamable HTTP or SSE**, also capture:
 
@@ -162,9 +162,6 @@ grep -rnE "\b(exec|spawn|execSync|spawnSync)\b" src/
 # Merges — prototype pollution
 grep -rn "Object.assign\b\|structuredClone" src/
 
-# Sampling — LLM-generated content flowing back into server logic
-grep -rn "ctx.sample\|sampling/createMessage" src/
-
 # Roots — client-shared filesystem
 grep -rn "roots/list\|ctx.roots" src/
 
@@ -182,9 +179,7 @@ grep -rn "\.passthrough()\|\.catchall(" src/mcp-server/
 - User-JSON merges reject `__proto__`, `constructor`, `prototype` keys?
 - **Input schemas `.strict()`** — unknown fields rejected, not silently passed to downstream code that destructures with `...rest`?
 - **Output schemas without `.passthrough()` / `.catchall()`** — no accidental exfiltration of fields your schema didn't declare?
-- Sampling responses (`ctx.sample` result) treated as untrusted input — schema-validated before reaching any other sink, never concatenated into prompts, shells, or queries?
-
-**Smell:** `z.string().url()` with no allowlist; `readFile(input.path)` with no canonicalization; `await ctx.sample(...)` result interpolated into a shell, SQL, or URL.
+**Smell:** `z.string().url()` with no allowlist; `readFile(input.path)` with no canonicalization.
 
 #### Axis 6 — Tenant isolation
 
@@ -333,14 +328,14 @@ End with:
 ## Checklist
 
 - [ ] Scope confirmed (whole server / module / diff)
-- [ ] Map built: tools / resources / prompts, services, upstream APIs, auth mode, sampling / elicit / roots usage
+- [ ] Map built: tools / resources / prompts, services, upstream APIs, auth mode, elicit / roots usage
 - [ ] Deployment surface reviewed (if HTTP): bind address, Origin allowlist, session ID, unauth routes, auth-spec compliance
 - [ ] `fuzzTool` started in parallel
 - [ ] Axis 1 — LLM-facing surfaces (tool / resource / prompt output + descriptions) framed and static
 - [ ] Axis 2 — scope granularity audited
 - [ ] Axis 3 — destructive ops verified to elicit, elicit response schema-validated
 - [ ] Axis 4 — upstream auth + token passthrough reviewed
-- [ ] Axis 5 — input sinks (URL / path / roots / shell / proto / sampling / schema strictness / ReDoS) checked
+- [ ] Axis 5 — input sinks (URL / path / roots / shell / proto / schema strictness / ReDoS) checked
 - [ ] Axis 6 — tenant isolation: module-scope state swept
 - [ ] Axis 7 — leakage back: errors / outputs / `ctx.log` / `console.*` / telemetry / constant-time comparisons
 - [ ] Axis 8 — resource bounds on loops / retries / pagination / parse size+depth / per-tenant rate

package/templates/AGENTS.md

@@ -48,7 +48,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
 - **Use `ctx.log`** for request-scoped logging. No `console` calls.
 - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
-- **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
+- **Check `ctx.elicit`** for presence before calling.
 - **Secrets in env vars only** — never hardcoded.
 - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
 
@@ -156,9 +156,22 @@ export function getServerConfig() {
 
 For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
 
-### Server instructions
+### Server identity and instructions
 
-`createApp({ instructions })` — optional server-level orientation, sent to clients on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
+`createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`):
+
+```ts
+await createApp({
+  name: 'my-mcp-server',
+  title: 'My Server',                         // human-readable display name
+  websiteUrl: 'https://github.com/owner/repo', // canonical homepage URL
+  description: 'One-line description.',        // wins over MCP_SERVER_DESCRIPTION
+  icons: [{ src: 'https://example.com/icon.png', sizes: ['48x48'], mimeType: 'image/png' }],
+  instructions: 'Use shortcut alpha for the most common case.', // session-level context
+});
+```
+
+`instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
 
 ---
 
@@ -170,8 +183,7 @@ Handlers receive a unified `ctx` object. Key properties:
 |:---------|:------------|
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
 | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
-| `ctx.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
-| `ctx.sample` | Request LLM completion from the client. **Check for presence first:** `if (ctx.sample) { ... }` |
+| `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
 | `ctx.signal` | `AbortSignal` for cancellation. |
 | `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
 | `ctx.requestId` | Unique request ID. |

package/templates/CLAUDE.md

@@ -48,7 +48,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
 - **Use `ctx.log`** for request-scoped logging. No `console` calls.
 - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
-- **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
+- **Check `ctx.elicit`** for presence before calling.
 - **Secrets in env vars only** — never hardcoded.
 - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
 
@@ -156,9 +156,22 @@ export function getServerConfig() {
 
 For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
 
-### Server instructions
+### Server identity and instructions
 
-`createApp({ instructions })` — optional server-level orientation, sent to clients on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
+`createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`):
+
+```ts
+await createApp({
+  name: 'my-mcp-server',
+  title: 'My Server',                         // human-readable display name
+  websiteUrl: 'https://github.com/owner/repo', // canonical homepage URL
+  description: 'One-line description.',        // wins over MCP_SERVER_DESCRIPTION
+  icons: [{ src: 'https://example.com/icon.png', sizes: ['48x48'], mimeType: 'image/png' }],
+  instructions: 'Use shortcut alpha for the most common case.', // session-level context
+});
+```
+
+`instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
 
 ---
 
@@ -170,8 +183,7 @@ Handlers receive a unified `ctx` object. Key properties:
 |:---------|:------------|
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
 | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
-| `ctx.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
-| `ctx.sample` | Request LLM completion from the client. **Check for presence first:** `if (ctx.sample) { ... }` |
+| `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
 | `ctx.signal` | `AbortSignal` for cancellation. |
 | `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
 | `ctx.requestId` | Unique request ID. |

package/dist/mcp-server/roots/roots-registration.d.ts

@@ -1,22 +0,0 @@
-/**
- * @fileoverview Service for implementing MCP roots capability.
- * Roots provide filesystem/workspace context awareness for the server.
- *
- * MCP Roots Specification:
- * @see {@link https://modelcontextprotocol.io/specification/2025-06-18/basic/roots | MCP Roots}
- * @module src/mcp-server/roots/roots-registration
- */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { logger as defaultLogger } from '../../utils/internal/logger.js';
-export declare class RootsRegistry {
-    private logger;
-    constructor(logger: typeof defaultLogger);
-    /**
-     * Registers roots handlers on the given MCP server.
-     * Note: In MCP, roots are typically provided BY THE CLIENT to the server.
-     * This implementation provides a placeholder for demonstration.
-     * In production, roots would be received from the client via client.listRoots().
-     */
-    registerAll(_server: McpServer): void;
-}
-//# sourceMappingURL=roots-registration.d.ts.map

package/dist/mcp-server/roots/roots-registration.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"roots-registration.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/roots/roots-registration.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG1E,qBAAa,aAAa;IACZ,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,OAAO,aAAa;IAEhD;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI;CActC"}