@cyanheads/mcp-ts-core 0.11.5 → 0.12.1

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.8"
+  version: "1.9"
   audience: external
   type: reference
 ---
@@ -134,8 +134,8 @@ import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
 createMockContext()                                           // working ctx.state on tenant 'default'
 createMockContext({ tenantId: 'test-tenant' })               // explicit tenant scope for ctx.state
 createMockContext({ errors: myTool.errors })                 // attaches typed ctx.fail keyed by the contract reasons
-createMockContext({ elicit: vi.fn().mockResolvedValue(...) }) // with elicitation
-createMockContext({ progress: true })                        // with task progress (ctx.progress populated)
+createMockContext({ inputResponses: { confirm: { action: 'accept', content: { ok: true } } } }) // second round of a multi-round-trip handler
+createMockContext({ requestState: 'opaque-state' })          // seeds ctx.inputs.state()
 createMockContext({ requestId: 'my-id' })                    // override request ID (default: 'test-request-id')
 createMockContext({ notifyResourceListChanged: () => {} })   // with resource-list change notifier
 createMockContext({ notifyResourceUpdated: (_uri) => {} })   // with resource update notifier
@@ -149,15 +149,15 @@ createMockContext({ uri: new URL('myscheme://item/123') })   // for resource han
 ```ts
 interface MockContextOptions<TErrors extends readonly ErrorContract[] | undefined> {
   auth?: AuthContext;
-  elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
   errors?: TErrors | undefined;
+  inputResponses?: InputResponses | Record<string, unknown>;
   notifyPromptListChanged?: () => void;
   notifyResourceListChanged?: () => void;
   notifyResourceUpdated?: (uri: string) => void;
   notifyToolListChanged?: () => void;
-  progress?: boolean;
-  sessionId?: string;
   requestId?: string;
+  requestState?: unknown;
+  sessionId?: string;
   signal?: AbortSignal;
   tenantId?: string;
   uri?: URL;
@@ -166,17 +166,17 @@ interface MockContextOptions<TErrors extends readonly ErrorContract[] | undefine
 
 | Option | Effect |
 |:-------|:-------|
-| _(none)_ | Working `ctx.state` on tenant `'default'`; `ctx.elicit`/`ctx.progress` are `undefined` |
+| _(none)_ | Working `ctx.state` on tenant `'default'`; `ctx.inputs` is empty (first round) |
 | `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; the return type narrows to `HandlerContext<ReasonOf<…>>`, so the context is assignable to that definition's handler parameter. |
+| `inputResponses` | Seeds `ctx.inputs` with the responses a retried request would carry, keyed by the identifiers the handler's `ctx.requestInput(...)` assigned (see below) |
 | `notifyPromptListChanged` | Assigns `ctx.notifyPromptListChanged` for prompt-list change notification tests |
 | `notifyResourceListChanged` | Assigns `ctx.notifyResourceListChanged` for resource notification tests |
 | `notifyResourceUpdated` | Assigns `ctx.notifyResourceUpdated` for resource update notification tests |
 | `notifyToolListChanged` | Assigns `ctx.notifyToolListChanged` for tool-list change notification tests |
-| `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'`) |
+| `requestState` | Seeds `ctx.inputs.state()` — the opaque state a prior round attached |
+| `sessionId` | Sets `ctx.sessionId` for handlers that branch on session ID |
 | `signal` | Overrides `ctx.signal` — useful for cancellation testing |
 | `tenantId` | Scopes `ctx.state` to a specific tenant. Defaults to `'default'` — the value stdio (and HTTP with `MCP_AUTH_MODE=none`) resolves |
 | `uri` | Sets `ctx.uri` for resource handler testing |
@@ -200,28 +200,54 @@ await expect(ctx.state.set('cache:v1:abc', {})).rejects.toThrow(McpError);
 
 Reach for `createInMemoryStorage()` when a service takes a `StorageService` directly — it builds the same pair.
 
-### Mock progress
+### Mock inputs
 
-When `progress: true`, `ctx.progress` is a real state-tracking object — not `vi.fn()` spies. It maintains internal state accessible via inspection properties:
+`ctx.requestInput` is the real implementation: it throws an `InputRequiredSignal` the production handler factories convert into an `input_required` result. In a unit test the handler is called directly, so that signal surfaces as a thrown value — which is exactly how you assert the first round.
 
 ```ts
-const ctx = createMockContext({ progress: true });
-// ctx.progress is typed as ContextProgress, but the mock exposes internal state:
-const progress = ctx.progress as ContextProgress & {
-  _total: number;
-  _completed: number;
-  _messages: string[];
-};
-
-await ctx.progress!.setTotal(10);
-await ctx.progress!.increment(3);
-await ctx.progress!.update('step message');
-
-expect(progress._total).toBe(10);
-expect(progress._completed).toBe(3);
-expect(progress._messages).toContain('step message');
+import { isInputRequiredSignal } from '@cyanheads/mcp-ts-core';
+
+it('asks for confirmation on the first round', async () => {
+  const ctx = createMockContext();
+  await expect(myTool.handler(myTool.input.parse({ path: '/tmp/x' }), ctx))
+    .rejects.toSatisfy(isInputRequiredSignal);
+});
 ```
 
+To assert on *what* was requested, catch it and read `error.result` — the `input_required` result the handler factory would have returned:
+
+```ts
+async function requestedInput(input: ToolInput, options: MockContextOptions = {}) {
+  try {
+    await myTool.handler(input, createMockContext(options));
+  } catch (error) {
+    if (isInputRequiredSignal(error)) return error.result;
+    throw error;
+  }
+  throw new Error('Expected the handler to request input.');
+}
+```
+
+`inputResponses` drives the second round. `ctx.inputs.accepted(key, schema)` and `.view(key)` read it with the same helpers production uses, so a wrong response shape fails in the test:
+
+```ts
+it('proceeds once the user accepts', async () => {
+  const ctx = createMockContext({
+    inputResponses: { confirm: { action: 'accept', content: { confirm: true } } },
+  });
+  await expect(myTool.handler(input, ctx)).resolves.toMatchObject({ deleted: '/tmp/x' });
+});
+
+it('stops when the user declines', async () => {
+  const ctx = createMockContext({
+    inputResponses: { confirm: { action: 'decline' } },
+  });
+  await expect(myTool.handler(input, ctx)).rejects.toThrow(McpError);
+});
+```
+
+`ctx.inputs.dropped` is always `[]` on a mock context — the drop only happens in the SDK's wire decoding, so cover it in an integration test rather than a unit one.
+
 ### Mock logger
 
 `ctx.log` captures all log calls for inspection. Import `MockContextLogger` from `@cyanheads/mcp-ts-core/testing` and cast `ctx.log` to access the `.calls` array (the cast is necessary because `createMockContext` returns `Context`, which types `log` as `ContextLogger`):
@@ -273,31 +299,6 @@ Parse input through `myTool.input.parse(...)` to validate against the Zod schema
 
 ---
 
-## Testing with optional capabilities
-
-```ts
-it('uses elicitation when available', async () => {
-  const elicit = vi.fn().mockResolvedValue({
-    action: 'accept',
-    content: { format: 'json' },
-  });
-  const ctx = createMockContext({ elicit });
-  const input = myTool.input.parse({ query: 'hello' });
-  await myTool.handler(input, ctx);
-  expect(elicit).toHaveBeenCalledOnce();
-});
-
-it('handles missing elicitation gracefully', async () => {
-  // ctx.elicit is undefined — handler must check before calling
-  const ctx = createMockContext();
-  const input = myTool.input.parse({ query: 'hello' });
-  // Should not throw even when ctx.elicit is absent
-  await expect(myTool.handler(input, ctx)).resolves.toBeDefined();
-});
-```
-
----
-
 ## Testing with form-based client payloads
 
 LLM clients only send populated fields. **Form-based clients** (MCP Inspector, web UIs) submit the full schema shape — optional object fields arrive with empty-string inner values instead of `undefined`. Both are valid MCP usage. Test that handlers handle both gracefully.

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.6"
+  version: "1.7"
   audience: external
   type: reference
 ---
@@ -212,6 +212,14 @@ export function getServerConfig() {
 
 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.
 
+**The default notification bus is per-isolate.** `core.notify` and the modern era's `subscriptions/listen` streams share a change-event bus that defaults to in-process — which on Workers means one bus per isolate, so a background emission reaches only the listeners that happen to live in the isolate that produced it. Handler-time `ctx.notify*` is unaffected (the listen stream and the handler are the same request). For fan-out that must cross isolates, supply a bus of your own, backed by a Durable Object or another shared channel:
+
+```ts
+createWorkerHandler({ tools, eventBus: myDurableObjectBackedBus });
+```
+
+The interface is the SDK's `ServerEventBus` — `publish(event)` and `subscribe(listener)`. See `api-context`'s notification section for what publishes onto it.
+
 ---
 
 ## Testing Workers with miniflare

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.2"
+  version: "1.3"
   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` — don't reach for global loggers or request-scoped storage directly. The `ctx` pattern carries tenant scope and OTel context.
+- **Ctx usage** — Use `ctx.log`, `ctx.state`, `ctx.enrich` — 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/design-mcp-server/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "2.21"
+  version: "2.22"
   audience: external
   type: workflow
 ---
@@ -141,7 +141,7 @@ Most tools follow the `{server}_{verb}_{noun}` default — one focused responsib
 
 | Shape | Purpose | Typical form | Examples |
 |:------|:--------|:-------------|:---------|
-| **Workflow** | Multi-step orchestration that replaces a common agent chain | N upstream calls (often parallelized); may elicit confirmation; may need mid-flow cleanup | `clinicaltrials_find_studies` (search → filter → rank) |
+| **Workflow** | Multi-step orchestration that replaces a common agent chain | N upstream calls (often parallelized); may request confirmation; may need mid-flow cleanup | `clinicaltrials_find_studies` (search → filter → rank) |
 | **Instruction** | State-aware procedural guidance — advice, not action | Static markdown + a few live-state fetches, `readOnlyHint: true`, outputs `nextToolSuggestions` pre-filling the recommended follow-up. No writes. | `git_wrapup_instructions` |
 | **Reference** | Decode opaque domain vocabulary — codes, enums, identifier formats, coverage windows — so agents can build valid inputs for the rest of the surface | Static tables or one cached fetch (often zero upstream calls); consolidate N lists under one `topic` enum; `readOnlyHint: true`, `openWorldHint: false` when offline | `medcode_list_systems`, `osv_list_ecosystems` |
 
@@ -269,20 +269,34 @@ A reference tool is the surface's decoder ring: which codes exist, what they mea
 
 Tools that perform multi-step mutations (the Workflow shape) have two safety considerations beyond single-call tools. Both are about giving the agent — and the human behind it — a chance to catch a bad invocation before it commits.
 
-**Elicit-guarded destructive modes with annotation fallback.** When a workflow's `mode` parameter switches between safe and destructive arms (`draft` vs `send`, `plan` vs `apply`), gate the destructive arm behind `ctx.elicit` when the client supports it, so a human confirms before the irreversible step fires. Elicitation isn't universally available — headless stdio sessions and many non-interactive clients don't expose it. Fall back on `destructiveHint: true` in annotations so those clients' approval flows still surface the risk. Document the fallback in the handler so maintainers don't assume elicit always runs:
+**Confirmation-gated destructive modes, with an annotation fallback.** When a workflow's `mode` parameter switches between safe and destructive arms (`draft` vs `send`, `plan` vs `apply`), gate the destructive arm on a confirmation the handler asks for via `ctx.requestInput(...)`, so a human approves before the irreversible step fires. The handler is re-entered with the answer on `ctx.inputs`; it does not `await` mid-call.
+
+The gate is always *reachable* — `ctx.requestInput` is present on every transport and both protocol eras — but it is not always *answerable*: a client that never fulfils the `input_required` result simply doesn't retry, and the destructive step never runs. Keep `destructiveHint: true` in annotations so those clients' own approval flows still surface the risk.
 
 ```ts
-annotations: { destructiveHint: true },        // fallback for clients without elicit
+annotations: { destructiveHint: true },        // client-side approval flows still see the risk
 // ...
-async handler(input, ctx) {
-  if (input.mode === 'apply' && ctx.elicit) {
-    const confirm = await ctx.elicit(
-      `Apply migration affecting ${affectedRowCount} rows in production? Cannot be rolled back automatically.`,
-      z.object({ confirmed: z.literal(true).describe('Type true to apply.') }),
-    );
-    if (confirm.action !== 'accept') throw new Error('Migration cancelled by user.');
+const Confirm = z.object({ confirmed: z.literal(true).describe('Type true to apply.') });
+
+handler(input, ctx) {
+  if (input.mode === 'apply') {
+    // A decline is terminal — re-asking would loop until the round budget runs out.
+    const view = ctx.inputs.view('confirm');
+    if (view.kind === 'elicit' && view.action !== 'accept') {
+      throw validationError('Migration cancelled by user.');
+    }
+    if (!ctx.inputs.accepted('confirm', Confirm)) {
+      return ctx.requestInput({
+        inputRequests: {
+          confirm: inputRequired.elicit({
+            message: `Apply migration affecting ${affectedRowCount} rows in production? Cannot be rolled back automatically.`,
+            requestedSchema: Confirm,
+          }),
+        },
+      });
+    }
   }
-  // destructive step proceeds; destructiveHint covers clients that skipped elicit
+  // destructive step proceeds
 }
 ```
 
@@ -622,13 +636,13 @@ Each step is independently testable.
 
 Keep it concise. The design doc is a working reference, not a spec document — enough to orient a developer (or agent) implementing the server, not more.
 
-**Workflow Analysis example.** For multi-step workflow tools, document the upstream call sequence in a table — it drives several downstream decisions during implementation: the service-layer method shape, retry boundaries, where cleanup or elicit belongs, and what post-action state to fetch for the response.
+**Workflow Analysis example.** For multi-step workflow tools, document the upstream call sequence in a table — it drives several downstream decisions during implementation: the service-layer method shape, retry boundaries, where cleanup or the confirmation round belongs, and what post-action state to fetch for the response.
 
-`deploy_release` (5–8 upstream calls, plus elicit):
+`deploy_release` (5–8 upstream calls, plus a confirmation round):
 
 | # | Call | Purpose | Mode gate |
 |:--|:-----|:--------|:----------|
-| 0 | `ctx.elicit` confirmation | Human approval before promote | `promote` (when available) |
+| 0 | `ctx.requestInput` confirmation | Human approval before promote | `promote` |
 | 1 | `POST /releases` | Create release record | always |
 | 2 | `PUT /releases/{id}/artifacts` | Attach build artifacts | always |
 | 3 | `GET /releases/{id}/preflight` | Health checks, smoke tests | always |
@@ -638,7 +652,7 @@ Keep it concise. The design doc is a working reference, not a spec document —
 | 7 | `GET /releases/{id}` | Post-action state for response | always |
 | — | `DELETE /releases/{id}/canary-traffic` | Cleanup canary if mid-flow error | on error + `cleanupOnError` |
 
-The table surfaces design questions early: should the elicit happen before or after the artifacts are attached? Does cleanup drop the canary on any failure, or only failures past the promote step? What does the response body need from the final GET — version, traffic percentage, health summary? Answering these during design is far cheaper than mid-implementation.
+The table surfaces design questions early: should the confirmation round happen before or after the artifacts are attached? Does cleanup drop the canary on any failure, or only failures past the promote step? What does the response body need from the final GET — version, traffic percentage, health summary? Answering these during design is far cheaper than mid-implementation.
 
 ### 9. Confirm and Proceed
 
@@ -687,7 +701,7 @@ Items without an `If …:` prefix apply to every design. Conditional items only
 - [ ] **If an upstream API has no native search but the relevant set is bounded:** MCP-side list filtering considered — a distinct local filter param (`filter`/`nameContains`, not `query`), filtering the full set, strict token match (fuzzy only when a caller needs typo tolerance)
 - [ ] **If the server has workflow tools:** call-flow documented (upstream sequence + mode arms) in design doc's Workflow Analysis
 - [ ] **If state-aware procedural guidance adds value:** instruction tool considered with `nextToolSuggestions` pre-filled from diagnostics
-- [ ] **If workflow tools have destructive modes:** destructive arm guarded by `ctx.elicit` when available, with `destructiveHint` annotation as fallback for non-interactive clients
+- [ ] **If workflow tools have destructive modes:** destructive arm gated on a `ctx.requestInput` confirmation read back from `ctx.inputs`, with `destructiveHint` annotation so clients that never fulfil the round still surface the risk
 - [ ] **If a parameter determines blast radius:** safe default set (e.g., `mode: 'preview'`, `dryRun: true`, `confirmCount` required)
 - [ ] **App tools default to no.** If one was proposed, verified there's a real human-in-the-loop in an MCP Apps-capable client justifying the iframe/CSP/`format()`-twin maintenance cost — otherwise dropped in favor of a standard tool
 - [ ] **If the server exposes resources:** URIs use `{param}` templates, pagination planned for large lists

package/skills/field-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
 metadata:
   author: cyanheads
-  version: "2.8"
+  version: "2.9"
   audience: external
   type: debug
 ---
@@ -243,7 +243,9 @@ mcp_init <url-from-mcp_start>
 
 Runs `initialize`, sends `notifications/initialized`, prints `sid=<id>` to capture for `mcp_call`, plus the protocol version the server negotiated.
 
-The helper requests the SDK's current protocol version. **If `protocol=` comes back older than `requested=`, the server capped it** — every call after that exercises an older protocol than a current client would negotiate. Note it as a `bug` finding and check the pinned `@modelcontextprotocol/sdk` version; don't quietly test the downgraded surface. To deliberately test an older version, set `MCP_FIELD_TEST_PROTOCOL`.
+The helper requests the newest `initialize`-negotiated revision the SDK supports (`2025-11-25`). **If `protocol=` comes back older than `requested=`, the server capped it** — every call after that exercises an older protocol than a current client would negotiate. Note it as a `bug` finding and check the pinned `@modelcontextprotocol/server` version; don't quietly test the downgraded surface. To deliberately test an older version, set `MCP_FIELD_TEST_PROTOCOL`.
+
+This exercises the **2025-era arm**: `initialize` negotiates the revision, the server mints an `Mcp-Session-Id`, and every later call rides that session. The [2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) is not in the `initialize` ladder at all — it is selected per request by the `io.modelcontextprotocol/protocolVersion` key in the request's own `_meta` envelope, and carries no session. Curl-based field testing therefore covers the sessionful leg; exercise the per-request leg from a real 2026-era client or an integration test.
 
 ### 3. Surface the catalog
 

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.11"
+  version: "2.12"
   audience: external
   type: workflow
 ---

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

@@ -31,7 +31,7 @@ Also check for stale framework references — servers migrated from `mcp-ts-temp
 Pick examples that:
 
 - Show the most common or important capability
-- Demonstrate any non-trivial patterns the server uses (e.g., `ctx.state`, `ctx.elicit`, `task: true`, services)
+- Demonstrate any non-trivial patterns the server uses (e.g., `ctx.state`, `ctx.requestInput` / `ctx.inputs`, `ctx.enrich`, services)
 - Include a handler with real business logic, not just passthrough
 
 Keep 1-2 examples per primitive type (tool, resource, prompt). Don't list every definition — the README handles that.
@@ -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` 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.
+Review the `ctx` feature table. Remove rows for features the server doesn't use (e.g., `ctx.requestInput` / `ctx.inputs` if no handler collects extra input). 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/polish-docs-meta/references/readme.md

@@ -78,7 +78,7 @@ The header tagline must match the `package.json` `description`.
 | Version | info | Always — link to `CHANGELOG.md` |
 | License | info | Always |
 | Docker | info | Published to ghcr.io or Docker Hub |
-| MCP SDK | info | Always — show the `@modelcontextprotocol/sdk` version |
+| MCP SDK | info | Always — show the `@modelcontextprotocol/server` version |
 | npm | info | Published to npm |
 | TypeScript | info | Always |
 | Bun | info | If using Bun (standard for this framework) |

package/skills/release-and-publish/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Ship a release end-to-end across every registry the project targets (npm, MCP Registry, GitHub Releases for `.mcpb` bundles, GHCR). Runs the final verification gate, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit, annotated tag) is already complete — this skill is the post-wrapup publish workflow. Retries transient network failures on publish steps; halts with a partial-state report when retries are exhausted or the failure is terminal.
 metadata:
   author: cyanheads
-  version: "2.11"
+  version: "2.12"
   audience: external
   type: workflow
 ---
@@ -199,6 +199,8 @@ Skip any destination that was skipped in its step.
 
 Confirm each published artifact is actually live — don't rely on a successful push exit code alone. For each destination that succeeded:
 
+**Never disable the sandbox to complete a verification.** A verification `curl` — most often the MCP Registry one — can come back blocked by a sandbox network restriction while npm and GHCR pass. Do **not** set `dangerouslyDisableSandbox` or otherwise route around the restriction; report the block and let the orchestrator verify from its own session. **A blocked verification is not evidence of a failed publish** — when the publish step itself reported success, report the two facts separately rather than treating the block as something to defeat.
+
 - **npm**: `npm view <package.json#name>@<version> version` — must return the version string
 - **MCP Registry**: `curl -s "https://registry.modelcontextprotocol.io/v0.1/servers/<mcpName>/versions/<version>"` — must return HTTP 200 with `server.version` matching `<version>` (`mcpName` is the `name` field from `server.json`; URL-encode `/` as `%2F`). The search endpoint (`/v0.1/servers?search=`) paginates and may not include the latest version for packages with many releases — always use the direct version lookup.
 - **GitHub Release**: `gh release view v<VERSION> -R <OWNER>/<REPO> --json assets --jq '.assets[].name'` — must list the `.mcpb` file

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.8"
+  version: "1.9"
   audience: external
   type: workflow
 ---
@@ -15,7 +15,7 @@ You've isolated a problem to `@cyanheads/mcp-ts-core` itself — not your server
 
 - Framework builder (`tool()`, `resource()`, `prompt()`) rejects valid input or produces incorrect output
 - `createApp()` or `createWorkerHandler()` fails on a valid config
-- `Context` properties (`ctx.log`, `ctx.state`, `ctx.elicit`, etc.) behave contrary to docs
+- `Context` properties (`ctx.log`, `ctx.state`, `ctx.inputs`, etc.) behave contrary to docs
 - A utility from `/utils`, `/errors`, `/auth`, `/storage`, `/services` returns wrong results or throws unexpectedly
 - Type exports are incorrect or missing (compile error on documented usage)
 - The definition linter (`bun run lint:mcp`) produces false positives or misses real violations

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

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against this MCP server's own repo. Use for server-specific issues — tool logic, service integrations, config problems, or domain bugs that aren't caused by the framework.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.7"
   audience: external
   type: workflow
 ---
@@ -277,7 +277,7 @@ Not sure where the bug lives? Quick checks:
 | Error in `src/mcp-server/tools/` or `src/services/` | | Yes |
 | Same bug reproduces with a bare `tool()` definition (no services) | Yes | |
 | Bug disappears when you swap in a dummy handler | | Yes |
-| `ctx.state`, `ctx.log`, `ctx.elicit` behave wrong on any tool | Yes | |
+| `ctx.state`, `ctx.log`, `ctx.inputs` behave wrong on any tool | Yes | |
 | Only one specific tool/resource is affected | | Yes |
 
 When genuinely ambiguous, file against this server's repo and note that it might be a framework issue. The maintainer can transfer it upstream.

package/skills/security-pass/SKILL.md

@@ -4,7 +4,7 @@ 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 / 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.6"
+  version: "1.7"
   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.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 request a consent round via `ctx.requestInput`, which services hold module-scope state, whether the server reads `roots`.
 
 **If transport is streamable HTTP or SSE**, also capture:
 
@@ -108,25 +108,27 @@ grep -rn "auth: \[" src/mcp-server/tools/definitions/
 
 **Smell:** every tool shares the same scope string. Or: `MCP_AUTH_DISABLE_SCOPE_CHECKS=true` set without a documented compensating ACL — confirm the deployment relies on a meaningful access control layer below the framework before approving.
 
-#### Axis 3 — Destructive ops without elicit
+#### Axis 3 — Destructive ops without a consent round
 
-`ctx.elicit` moves consent off the LLM and onto the user. Destructive tools without it trust the LLM not to be tricked.
+`ctx.requestInput` moves consent off the LLM and onto the user: the handler returns an `input_required` result and only runs the side effect once it is re-entered with an accepted response. Destructive tools without that round trust the LLM not to be tricked.
 
 **Look in:** handlers with `destructiveHint: true` or side-effecting verbs in names (`delete_*`, `send_*`, `pay_*`, `publish_*`, `drop_*`).
 
 ```bash
 grep -rn "destructiveHint" src/mcp-server/tools/definitions/
-grep -rn "ctx.elicit" src/mcp-server/tools/definitions/
+grep -rn "ctx.requestInput\|ctx.inputs" src/mcp-server/tools/definitions/
 ```
 
 **Check:**
 
-- Each destructive handler calls `ctx.elicit` before the side effect?
-- Fallback when elicit is unavailable — **proceeds on the tool annotations, and says so in the tool description?** Do NOT require a refusal here: `ctx.elicit` is `undefined` on *every* Streamable HTTP request (the transport builds a fresh `McpServer` per request, so the SDK never records the client's capabilities — mcp-ts-core#312), so a refusing fallback makes the gated tools permanently unusable on the hosted transport. That is an outage, not a hardening. What IS in scope: a **declined or unparseable** elicit response must never proceed, and any doc claiming the gate protects "clients that support elicitation" must name the HTTP limitation or it overstates the control.
-- Elicit **response** validated against a Zod schema before use? The returned payload is LLM-mediated, not user-direct — "user confirmed" does not mean "user authored these exact fields."
-- Consent is scoped to the specific target (e.g., record ID rendered in the prompt), not a generic "proceed?"
+- Each destructive handler reads `ctx.inputs` for the confirmation and returns `ctx.requestInput(...)` before the side effect?
+- The confirmation **response** is validated — `ctx.inputs.accepted(key, Schema)` with a schema, not the bare overload. The SDK never re-validates a response against the schema its request advertised, and the payload is LLM-mediated: "user confirmed" does not mean "user authored these exact fields."
+- A **declined or cancelled** response is terminal — checked via `ctx.inputs.view(key)` and thrown on, never re-asked (a re-ask loops until the round budget runs out) and never treated as consent.
+- Consent is scoped to the specific target (e.g., record ID rendered in the message), not a generic "proceed?"
+- Any `requestState` carried across rounds is integrity-protected if it influences authorization, resource access, or which target gets mutated. It round-trips through the client and comes back attacker-controlled; the SDK does not sign or verify it.
+- **The weak point is answerability, not availability.** `ctx.requestInput` is present on every transport and both protocol eras — the 2025-era shim issues the real `elicitation/create` round trip, the 2026-07-28 client fulfils the embedded request directly. A client that never retries simply leaves the destructive step un-run, which fails safe. Keep `destructiveHint: true` so client-side approval flows still surface the risk, and do not accept "proceed anyway when the round is unavailable" as a fallback — there is no such state to detect.
 
-**Smell:** `destructiveHint: true` file with no `ctx.elicit?.(...)` in it. Or: `const { confirmed } = await ctx.elicit(...)` without a schema — `confirmed` could be anything.
+**Smell:** `destructiveHint: true` file with no `ctx.requestInput` in it. Or `ctx.inputs.accepted('confirm')` with no schema argument — the content could be anything. Or a handler that re-issues the same request after a `decline`.
 
 #### Axis 4 — Upstream auth shape
 
@@ -295,7 +297,7 @@ Group by severity. Each 3–5 lines.
 | Severity | Meaning |
 |:---------|:--------|
 | **critical** | Exploitable now: auth bypass, exfiltration, arbitrary code/file/network access |
-| **high** | Structural gap with clear attacker benefit even without immediate PoC (destructive op without elicit, admin scope on read tool, SSRF-capable URL input) |
+| **high** | Structural gap with clear attacker benefit even without immediate PoC (destructive op without a consent round, admin scope on read tool, SSRF-capable URL input) |
 | **medium** | Defense-in-depth gap weakening a boundary (missing per-tenant rate limit, error carries upstream response) |
 | **low** | Hardening / polish (tighter output schema, narrower error data, minor comment) |
 
@@ -314,7 +316,7 @@ Numbered, cherry-pickable.
 
 ```
 1. Add SSRF guard to `fetch_url.tool.ts` — block private IPs + non-http schemes (critical, #1)
-2. Gate `delete_record.tool.ts` behind `ctx.elicit` (high, #3)
+2. Gate `delete_record.tool.ts` behind a `ctx.requestInput` confirmation round (high, #3)
 3. Split `admin` into `record:read` + `record:write` across 4 tools (high, #4)
 4. Move `const tokenCache = new Map()` out of module scope in `auth-service.ts` (medium, #7)
 5. Cap pagination loop in `list_all_tickets` at 1000 items (medium, #9)
@@ -328,12 +330,12 @@ End with:
 ## Checklist
 
 - [ ] Scope confirmed (whole server / module / diff)
-- [ ] Map built: tools / resources / prompts, services, upstream APIs, auth mode, elicit / roots usage
+- [ ] Map built: tools / resources / prompts, services, upstream APIs, auth mode, consent-round / 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 3 — destructive ops verified to gate on a `ctx.requestInput` round, the response schema-validated, decline/cancel terminal
 - [ ] Axis 4 — upstream auth + token passthrough reviewed
 - [ ] Axis 5 — input sinks (URL / path / roots / shell / proto / schema strictness / ReDoS) checked
 - [ ] Axis 6 — tenant isolation: module-scope state swept

package/skills/tool-defs-analysis/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: tool-defs-analysis
 description: >
-  Read-only audit of MCP definition language across an existing surface — tools, resources, prompts, server instructions. Walks every definition file and checks 15 categories the LLM reads to decide whether and how to call: voice & tense, internal leaks, audience leaks, defaults, recovery hints, field descriptions, cross-references, sparsity, examples, structure, mutator observability, unit-bearing numeric names, validator-enforced constraints, annotations truthfulness, single-line strings — then a cross-surface pass: naming taxonomy, parameter vocabulary, tool overlap, instructions drift, length outliers. Produces grouped findings with file:line citations and a numbered options list. Use during polish, after a refactor, or before a release. Complements `field-test` (behavior testing) and `security-pass` (security audit).
+  Read-only audit of MCP definition language across an existing surface — tools, resources, prompts, server instructions. Walks every definition file and checks 16 categories the LLM reads to decide whether and how to call: voice & tense, internal leaks, audience leaks, defaults, recovery hints, field descriptions, cross-references, sparsity, examples, structure, mutator observability, unit-bearing numeric names, validator-enforced constraints, annotations truthfulness, single-line strings, exclusive modes in the schema — then a cross-surface pass: naming taxonomy, parameter vocabulary, tool overlap, instructions drift, length outliers. Produces grouped findings with file:line citations and a numbered options list. Use during polish, after a refactor, or before a release. Complements `field-test` (behavior testing) and `security-pass` (security audit).
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: audit
 ---
@@ -22,7 +22,7 @@ This skill is the **review-time pass** for that drift. Read each definition the
 | `security-pass` | Injection, scopes, input sinks |
 | `tool-defs-analysis` (this) | LLM-facing language across the existing surface |
 
-`field-test` already audits descriptions for implementation leaks, meta-coaching, and consumer-aware phrasing during its catalog step — that's a fast shallow pass alongside live tool calls. This skill is the deeper review: 15 categories, every field, every recovery hint, every default value, with file:line citations — plus a cross-surface pass for the drift no single file shows.
+`field-test` already audits descriptions for implementation leaks, meta-coaching, and consumer-aware phrasing during its catalog step — that's a fast shallow pass alongside live tool calls. This skill is the deeper review: 16 categories, every field, every recovery hint, every default value, with file:line citations — plus a cross-surface pass for the drift no single file shows.
 
 **Read-only.** This skill produces a report; the maintainer applies fixes. While running it, do not run git, do not stage or commit, do not update the changelog, do not run `devcheck`, do not invoke wrapup or release workflows. Fixes flow through the normal authoring path (edit the definition, then re-run this skill if you want to verify).
 
@@ -57,7 +57,7 @@ The `*tool.ts` / `*resource.ts` patterns also catch `*.app-tool.ts` / `*.app-res
 
 Use `TaskCreate` — one task per file. Mark each complete after its findings are captured.
 
-### 2. Walk the 15 categories per file
+### 2. Walk the 16 categories per file
 
 Read each definition file in full. Apply every category — most files trip more than one. Capture each hit with `file:line`, the offending excerpt, and a one-line fix.
 
@@ -201,6 +201,16 @@ Field-test catches this in its leak audit; this skill is the more thorough pass.
 
 **Fix:** collapse to one single-line string literal.
 
+#### 16. Exclusive modes in the schema
+
+**Look in:** input schemas where two or more optional fields are alternatives rather than additions — the describes say "provide either X or Y", "ignored when Z is set", "one of".
+
+**Check:** the exclusivity is in the schema, as a `z.discriminatedUnion` on a mode literal, so each branch advertises its own `required` list and the model reads which arguments go together. A mutex that lives only in prose reaches a weaker model unreliably: it fills both, or neither, and the handler answers with a validation error for a rule the schema said nothing about.
+
+**Smell:** every field optional with a describe explaining when to omit it; a handler opening with `if (!a && !b) throw` / `if (a && b) throw`; a `mode`/`kind`/`by` enum whose value decides which *other* fields are required.
+
+**Fix:** `input: z.discriminatedUnion('mode', [...])` — see the `add-tool` skill. Not every all-optional schema qualifies: fields that genuinely compose (independent filters, pagination) stay flat.
+
 ### 3. Cross-surface pass
 
 The per-file walk misses drift that only shows between files. After it, sweep the whole surface:
@@ -260,7 +270,7 @@ End with:
 - [ ] Scope confirmed (whole server / module / specific files)
 - [ ] Severity floor applied — nits suppressed if user requested
 - [ ] Inventory built — every `*.tool.ts`, `*.app-tool.ts`, `*.resource.ts`, `*.app-resource.ts`, `*.prompt.ts` listed; server `instructions` located if set
-- [ ] Each file walked through all 15 categories (per-file, not 15 separate passes)
+- [ ] Each file walked through all 16 categories (per-file, not 16 separate passes)
 - [ ] Cross-surface pass run — naming taxonomy, parameter vocabulary, tool overlap, instructions drift, length outliers
 - [ ] **Read-only:** no git, no commits, no changelog edits, no `devcheck`, no wrapup invoked during the audit
 - [ ] Findings carry file:line citation, excerpt, issue, fix — excerpts verbatim, line numbers verified

package/templates/.env.example

@@ -15,6 +15,10 @@
 
 # ── Session ──────────────────────────────────────────────────────────
 # MCP_SESSION_MODE=stateful         # stateful | stateless (default: stateful)
+# MCP_HTTP_RESUMABILITY=false       # SSE replay on a dropped stateful stream. Default: true.
+                                    # Kill switch only — no effect on stateless serving.
+# MCP_HTTP_RESUMABILITY_MAX_EVENTS=512   # Retained per session, oldest evicted first
+# MCP_HTTP_RESUMABILITY_TTL_MS=300000    # How long a retained event stays replayable
 
 # ── Memory ───────────────────────────────────────────────────────────
 # MCP_GC_PRESSURE_INTERVAL_MS=0     # Opt-in forced Bun.gc(true) interval, ms (Bun only). Drains old-gen backlog