@feniix/bridgekit 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -6,6 +6,108 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-10-14
+
+### Added
+
+- Forward tool `icons` and `_meta` from `hostExtras.mcp`, with construction-time
+  snapshots and no new wire keys when absent (#128).
+- Add `createMcpHttpHandler` for Web-standard HTTP serving of modern MCP.
+  Listener and security policy remain application-owned
+  (#126). HTTP options and handler types are exported from the MCP entrypoint.
+
+- Export `createMcpServerFactory(options)` from the MCP entrypoint: validates and
+  snapshots tools once and returns a per-call `Server` factory for the SDK's
+  `createMcpHandler` / `serveStdio`, replacing `createMcpServer` for custom
+  serving.
+
+### Changed (breaking)
+
+- Serve only the modern MCP `2026-07-28` era. `runMcpStdioServer` and
+  `createMcpHttpHandler` reject legacy-era openings (`2025-11-25` and earlier)
+  with `-32022` naming the supported revisions, and log one `[bridgekit-mcp]`
+  stderr line per rejected request. Clients limited to the legacy era (SDK v1, or
+  v2 in `legacy` negotiation mode) can no longer connect. The SDK v2 client
+  defaults to `versionNegotiation.mode: "legacy"`, so a default-constructed
+  client is rejected: pin `{ mode: { pin: "2026-07-28" } }` or use `"auto"`.
+  `legacy` is removed from `CreateMcpHttpHandlerOptions` and ignored at runtime
+  for untyped callers. `createMcpServer` is deprecated as a direct
+  `Server.connect` target (a directly connected `Server` is legacy-only); use the
+  new `createMcpServerFactory(options)` with the SDK's `createMcpHandler` to
+  compose custom serving. Both the `tools/list` `outputSchema` and the
+  `tools/call` `structuredContent` of non-object outputs are no longer
+  `{ result }`-wrapped for any served client. The SDK v1 dev dependency and its
+  stdio interop test were removed (#131 retired). See `docs/mcp-v2-migration.md`.
+- `runMcpStdioServer` now returns `Promise<McpStdioServerHandle>` with an
+  idempotent `close()` that aborts pending requests (#129). Awaiting startup
+  means stdio wiring is ready, not that a client has connected. Callers that
+  explicitly annotated `Promise<void>` must update their annotation; existing
+  callers that ignore the resolved value need no changes.
+
+### Fixed
+
+- Snapshot validated tool definitions once for HTTP and stdio serving, including
+  discarded discovery probes; later caller array/metadata mutations cannot leak onto the wire.
+- Reject invalid MCP icon shapes at construction with tool-attributed
+  `BRIDGEKIT_MCP_INVALID_ICONS` errors; HTTP serving defaults to stderr diagnostics.
+- Clarify that stdio `close()` aborts requests without awaiting asynchronous tool cleanup.
+
+### Documentation
+
+- Record the official conformance suite's HTTP-only server interface and the
+  resulting blocker for direct stdio conformance testing (#130).
+- Record four passing official HTTP scenarios and the pinned harness's rejection
+  of `2026-07-28`; direct stdio/full modern conformance remains unverified (#130).
+  Those legacy-filtered results predate modern-only serving and no longer reproduce.
+
+## [0.18.0] - 2026-10-06
+
+### Added
+
+- The MCP adapter forwards `ctx.progress?.(update)` as `notifications/progress` when the
+  `tools/call` request carries `_meta.progressToken`. `progress` is a per-call counter
+  starting at 1, `message` is `update.text`, `total` is omitted. Notifications are flushed
+  before the result and skipped once the request is cancelled; a failed send never fails
+  the call. Without a token `ctx.progress` stays `undefined`, matching previous behaviour.
+- `outputSchema` accepts any JSON Schema root except a top-level `$ref`: arrays, primitives,
+  `null` and unions join objects and object intersections. The MCP SDK projects non-object
+  values for legacy-era clients (`{ result: value }` on both `tools/list` and `tools/call`)
+  while modern `2026-07-28` clients receive the natural value. Pi forwards the raw value on
+  `structuredContent` and wraps non-object values as `details.result`. `definePortableTool`
+  checks array and primitive roots at compile time without the open-record intersection.
+
+### Changed
+
+- `PortableToolResult<TStructured>` drops the `Record<string, unknown>` constraint on its
+  generic (the default is unchanged), and bare `PortableTool` now defaults its result generic
+  to `PortableToolResult<unknown>` so adapter tool lists accept non-object outputs. A tool
+  annotated as bare `PortableTool` / `PortableTool<TSchema>` therefore yields
+  `structuredContent: unknown` from `executePortableTool` where it was `Record<string, unknown>`;
+  keep the inferred type from `definePortableTool` or annotate the result generic explicitly.
+  `PortableToolContext.progress`, the result guards and `PortableToolExecutionError` accept
+  `PortableToolResult<unknown>`. Custom adapters that declared `progress` with the narrower
+  object-only parameter need to widen it. Both adapters now test `structuredContent !== undefined`
+  instead of `??`, so a `null` structured value no longer falls back to `details`.
+- `BRIDGEKIT_MCP_NON_OBJECT_OUTPUT_SCHEMA` is gone; only `BRIDGEKIT_MCP_REF_OUTPUT_SCHEMA`
+  (and `BRIDGEKIT_REF_OUTPUT_SCHEMA` at the portable seam) remain.
+
+- Development, CI, and release installs use pnpm instead of npm. `package.json#packageManager`
+  pins `pnpm@12.9.1`, `pnpm-lock.yaml` replaces `package-lock.json`, and CI installs with
+  `pnpm install --frozen-lockfile`. The production audit gate is now
+  `pnpm audit --prod --audit-level high`. Publishing still uses
+  `npm publish --access public --provenance` for OIDC trusted publishing.
+  The lockfile resolves `typebox` to 1.3.35 rather than 1.3.36, because pnpm's default
+  `minimumReleaseAge` skips same-day releases; both satisfy `^1.1.31`.
+- The package smoke test packs with `pnpm pack` and installs the tarball into a strict pnpm
+  consumer, which now declares `@modelcontextprotocol/server` explicitly for the `Server` type.
+  A new invariant fails when `packageManager` is unpinned or an npm/yarn lockfile reappears.
+- CI and all release jobs run on Node 22 only, matching pi's workflows: the `22.19`/`24`
+  CI matrix is gone and the release no longer uses Node 24. The publish job upgrades to
+  `npm@11.16.0` (as pi does) because Node 22's bundled npm 10.x cannot do trusted publishing.
+  The `engines.node` floor stays `>=22.19.0`.
+- No runtime change: `runBinWrapper` still builds missing output with `npm run <buildScript>`,
+  since downstream consumers own their package manager.
+
 ## [0.17.0] - 2026-10-06
 
 ### Changed

package/README.md

@@ -94,7 +94,7 @@ import {
   type PortableValidationError,
 } from "@feniix/bridgekit";
 import { registerPiTools } from "@feniix/bridgekit/pi";
-import { createMcpServer, runMcpStdioServer } from "@feniix/bridgekit/mcp";
+import { createMcpHttpHandler, runMcpStdioServer } from "@feniix/bridgekit/mcp";
 import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper";
 ```
 
@@ -111,8 +111,8 @@ Do not deep-import from `dist/` or `src/` in consuming packages.
 
 #### Declared structured output
 
-Add an optional object-shaped `outputSchema` to a portable tool to describe its
-successful `structuredContent` for both Pi and MCP:
+Add an optional `outputSchema` to a portable tool to describe its successful
+`structuredContent` for both Pi and MCP:
 
 ```ts
 const echoTool = definePortableTool({
@@ -125,9 +125,12 @@ const echoTool = definePortableTool({
 });
 ```
 
-Inlined object schemas and intersections of objects are accepted. Success calls
-must return matching `structuredContent`; legacy `details` alone does not satisfy
-the schema. Missing/invalid output throws a tool-attributed `TypeError` at the
+Any JSON Schema root is accepted except a top-level `$ref` (`Type.Ref` /
+`Type.Cyclic`): objects, intersections of objects, arrays, primitives, `null` and
+unions all work. Success calls must return matching `structuredContent`; legacy
+`details` alone does not satisfy the schema. Non-object values reach MCP
+clients as-is (the served modern era; legacy-era clients are not served). Pi receives the raw value on `structuredContent`
+and `{ result: value }` on renderer-facing `details`. Missing/invalid output throws a tool-attributed `TypeError` at the
 portable seam and becomes an error result through the adapters. Argument/domain
 failures are exempt from success schemas. Without `outputSchema`, existing result
 behavior is unchanged.
@@ -248,6 +251,8 @@ export const generateSummaryTool = definePortableTool({
     },
     mcp: {
       annotations: { readOnlyHint: true },
+      icons: [{ src: "https://example.com/summary.svg", mimeType: "image/svg+xml" }],
+      _meta: { "example.com/category": "text" },
     },
   },
 });
@@ -255,10 +260,20 @@ export const generateSummaryTool = definePortableTool({
 
 `renderCall` is invoked by pi before execution to render the call line. `renderResult` is invoked by pi after execution to render the result; its `options.expanded` flag tracks the user's Ctrl+O collapsed/expanded toggle. BridgeKit forwards both functions by identity to `pi.registerTool`.
 
+MCP `icons` and `_meta` are forwarded only when supplied, including explicit empty
+arrays/objects. At server construction, BridgeKit copies icons (including their
+`sizes` arrays) and shallow-copies `_meta`; nested metadata values must remain
+immutable. BridgeKit never fetches icon URLs. The pi adapter ignores both fields.
+
 See `docs/rfc-host-extras.md` for the design rationale (which fields are in scope, why a top-level field beats a sidecar map, the closure rule for future additions). `PortableToolHostExtras` is module-augmentable for custom host adapters; declare your namespace via `declare module "@feniix/bridgekit"`.
 
 ### MCP adapter
 
+`await runMcpStdioServer(options)` returns a `McpStdioServerHandle` with
+idempotent `close(): Promise<void>` for explicit shutdown and cancellation of
+pending requests. Resolution signals startup wiring, not client negotiation or
+shutdown. Stdin EOF also cleans up the server.
+
 ```ts
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
@@ -298,6 +313,8 @@ Tool `parameters` must resolve to a JSON-Schema object at the top level. `Type.O
 
 Portable validation failures and portable `isError: true` results return `CallToolResult` with `isError: true`. `structuredContent` is preserved; `details` is used only as a fallback when `structuredContent` is absent. Exporting a server-options factory keeps MCP entrypoints import-passive and easy to test without starting stdio.
 
+When a client sends `_meta.progressToken` on `tools/call`, each `ctx.progress?.(update)` becomes a `notifications/progress` notification: `progress` is a per-call counter starting at 1 (the spec requires it to increase), `message` is `update.text`, and `total` is omitted. Without a token `ctx.progress` is `undefined`, so tools should keep calling it optionally. Notifications are flushed before the result and skipped once the request is cancelled. Caveat: the official SDK clients defer notification handlers while handling responses synchronously, so a burst of progress calls issued synchronously right before returning can be dropped by the client when it arrives in the same stdio chunk as the result. BridgeKit writes them in order regardless; tools that emit progress over time are unaffected. Upstream: [typescript-sdk#2580](https://github.com/modelcontextprotocol/typescript-sdk/issues/2580) (fix pending in [typescript-sdk#2967](https://github.com/modelcontextprotocol/typescript-sdk/pull/2967)), tracked in [#132](https://github.com/feniix/bridgekit/issues/132).
+
 The two adapters return `{ isError: true }` for argument/domain failures by default.
 Use result guards on portable values; both wire formats now preserve `structuredContent`,
 and Pi also exposes its renderer-facing `details`.
@@ -305,23 +322,55 @@ The guards match error/data shape, not provenance, so Pi wire failures also matc
 at runtime. Raw Pi values still lack portable `text`; do not cast them to
 `PortableToolResult` to use the typed guards.
 
+#### Streamable HTTP
+
+```ts
+import { createMcpHttpHandler } from "@feniix/bridgekit/mcp";
+
+const handler = createMcpHttpHandler(createMcpServerOptions(), {
+  responseMode: "auto", // preserves progress via SSE when needed
+});
+// Mount handler.fetch(request) in your Web-standard framework.
+// Await handler.close() when the application shuts down.
+```
+
+The handler serves the modern `2026-07-28` era only; legacy-era clients (`2025-11-25` and earlier)
+receive an unsupported-protocol-version error (`-32022`, HTTP 400) naming the
+supported revisions. It does not start a listener or install
+authentication, authorization, Host/Origin validation, CORS, or TLS. **Enforce
+those in your application before calling `fetch`**, especially before exposing a
+local server to a network. SDK HTTP options are accepted as the second argument.
+`responseMode: "json"` drops mid-call notifications; use `"auto"` for progress.
+
 #### MCP SDK v2 and modern stdio
 
-`runMcpStdioServer(options)` serves both legacy MCP revisions and modern
-`2026-07-28` through SDK v2's `serveStdio`. Its `Promise<void>` resolves after
-startup wiring, not at shutdown. Stdin EOF closes the connection; long-running
-tools must honor `ctx.signal` and release their own resources.
+`runMcpStdioServer(options)` serves modern `2026-07-28` through SDK v2's
+`serveStdio`; `2025-11-25` openings are answered with `-32022`. Its `Promise<McpStdioServerHandle>`
+resolves after startup wiring, not at shutdown. Stdin EOF or `handle.close()`
+closes the connection; long-running
+tools must honor `ctx.signal` and release their own resources. `close()` aborts
+requests but does **not** await handler completion or asynchronous abort cleanup;
+coordinate tool cleanup before disposing shared application resources.
 
 `createMcpServer` now returns `@modelcontextprotocol/server` SDK v2's low-level
 `Server`. This is a source-level breaking change for consumers using SDK methods
-or types, even though legacy clients work over the wire. A direct
-`server.connect(StdioServerTransport)` remains legacy-only; use the runner for
-modern serving. See [migration guidance](docs/mcp-v2-migration.md).
-
-Some SDK v1 clients validate error data against cached success output schemas
-in their convenience `callTool` method; their generic request API can preserve
-that data. SDK v2 clients correctly exempt error results. HTTP and tasks remain
-outside BridgeKit's runner support.
+or types. `createMcpServer` is deprecated: a directly connected `Server`
+can only speak the legacy era, which BridgeKit no longer serves. Use
+`runMcpStdioServer` or `createMcpHttpHandler`. See [migration guidance](docs/mcp-v2-migration.md).
+
+**Legacy clients are not served.** Clients limited to the legacy era
+(`2025-11-25` and earlier: SDK v1 clients, or v2 clients in `legacy` negotiation
+mode) cannot connect. The SDK v2 client defaults to
+`versionNegotiation.mode: "legacy"`, so a default-constructed client is rejected;
+pin `versionNegotiation: { mode: { pin: "2026-07-28" } }` or use `"auto"`.
+HTTP is exposed through `createMcpHttpHandler`; tasks remain pending.
+
+HTTP option and return types are available as `CreateMcpHttpHandlerOptions` and
+`McpHttpHandler` from `@feniix/bridgekit/mcp`; consumers need not import SDK types.
+HTTP errors default to `[bridgekit-mcp]` diagnostics on stderr; `onerror` overrides
+that reporter. Tool definitions are static (`tools.listChanged: false`); the SDK
+handler's `notify.toolsChanged()` is not supported by BridgeKit's static tools.
+Modern HTTP and stdio support request cancellation normally.
 
 ### bin-wrapper (since 0.11.0)
 
@@ -344,7 +393,7 @@ Options:
 
 - `metaUrl` (required): `import.meta.url` of the bin script. Used to locate the package root (the bin's parent directory).
 - `mcpEntry` (required): path to the compiled MCP entry, relative to the package root (e.g. `"dist/extensions/mcp-server.js"`). Absolute paths, `..` path segments, and NUL bytes are rejected.
-- `buildScript` (required): npm script to invoke when the entry is missing (e.g. `"build:mcp"`). Names must be literal script identifiers containing only letters, numbers, `:`, `_`, `@`, `.`, or `-`, and must not start with `-`.
+- `buildScript` (required): npm script to invoke when the entry is missing (e.g. `"build:mcp"`). The wrapper runs it with `npm run <buildScript> --silent` regardless of which package manager installed your package. Names must be literal script identifiers containing only letters, numbers, `:`, `_`, `@`, `.`, or `-`, and must not start with `-`.
 - `buildTimeoutMs` (optional, default `60_000`): timeout for the build subprocess. Distinct "Build timed out…" diagnostic fires when exceeded.
 - `logPrefix` (optional, default `"bridgekit-bin"`): prefix on the "Failed to build…" diagnostic.
 - `buildStdio` (optional, default `"inherit"`): `stdio` mode passed to `spawnSync` when the build script runs. **MCP stdio server bins should pass `["ignore", "inherit", "inherit"]`** so the build subprocess's stdout cannot contaminate the parent's JSON-RPC framing channel (`process.stdout`). stderr stays inherited so build diagnostics remain visible.
@@ -389,7 +438,7 @@ Package and release checklist:
 - If an npm-launched bin depends on generated output, use `runBinWrapper` from `@feniix/bridgekit/bin-wrapper` (since 0.11.0) — it resolves the package-local generated entry, runs the package-local build when output is missing in workspace/local execution, preserves build failures, and distinguishes timeout from build error in its diagnostic. The bin script becomes a three-line invocation; no hand-rolled wrapper needed.
 - If a package keeps a source-loaded host entrypoint (for example a pi extension source file), use a package-local MCP build behind that wrapper and narrow the build to the MCP entrypoint plus shared host-neutral modules.
 - Declare a compatible Node engine (`>=22.19.0`) in downstream packages that expose BridgeKit-powered MCP bins.
-- Run `npm run check`, `npm test`, `npm run pack:dry-run`, `npm run package-smoke`, and `npm audit --omit=dev --audit-level=high` before publishing.
+- BridgeKit itself is developed with pnpm (pinned via `packageManager`): run `pnpm run check`, `pnpm test`, `pnpm run pack:dry-run`, `pnpm run package-smoke`, and `pnpm audit --prod --audit-level high` before publishing.
 - Treat `docs/releasing.md` as the release handoff; publishing is manual via the Release workflow and npm trusted publishing.
 
 See `examples/README.md` for complete copyable examples.

package/dist/src/adapters/mcp-http.d.ts

@@ -0,0 +1,15 @@
+import { type CreateMcpHandlerOptions, type McpHttpHandler } from "@modelcontextprotocol/server";
+import { type CreateMcpServerOptions } from "./mcp.js";
+/**
+ * SDK handler options minus `legacy`: BridgeKit serves the modern
+ * `2026-07-28` era only, so legacy-era requests are always rejected.
+ */
+export type CreateMcpHttpHandlerOptions = Omit<CreateMcpHandlerOptions, "legacy">;
+export type { McpHttpHandler };
+/**
+ * Web-standard HTTP serving; no listener, authentication, or origin policy is
+ * installed. Applications must enforce those before calling `handler.fetch`.
+ * Serves the modern `2026-07-28` era only; `2025-11-25` clients receive the
+ * unsupported-protocol-version error naming the supported revisions.
+ */
+export declare function createMcpHttpHandler(options: CreateMcpServerOptions, httpOptions?: CreateMcpHttpHandlerOptions): McpHttpHandler;

package/dist/src/adapters/mcp-http.js

@@ -0,0 +1,16 @@
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { createMcpServerFactory } from "./mcp.js";
+/**
+ * Web-standard HTTP serving; no listener, authentication, or origin policy is
+ * installed. Applications must enforce those before calling `handler.fetch`.
+ * Serves the modern `2026-07-28` era only; `2025-11-25` clients receive the
+ * unsupported-protocol-version error naming the supported revisions.
+ */
+export function createMcpHttpHandler(options, httpOptions = {}) {
+    const factory = createMcpServerFactory(options);
+    return createMcpHandler(factory, {
+        ...httpOptions,
+        legacy: "reject",
+        onerror: httpOptions.onerror ?? ((error) => process.stderr.write(`[bridgekit-mcp] ${error.message}\n`)),
+    });
+}

package/dist/src/adapters/mcp.d.ts

@@ -1,6 +1,6 @@
 import { Server } from "@modelcontextprotocol/server";
 import type { TSchema } from "typebox";
-import type { PortableTool } from "../core/define-tool.js";
+import type { PortableTool, PortableToolResult } from "../core/define-tool.js";
 export interface CreateMcpServerOptions {
     name: string;
     version: string;
@@ -17,8 +17,39 @@ export interface CreateMcpServerOptions {
      * reference, not deep-cloned — treat `tool.parameters` and `tool.outputSchema` as immutable once
      * `createMcpServer` returns.
      */
-    tools: readonly PortableTool<TSchema>[];
+    tools: readonly PortableTool<TSchema, PortableToolResult<unknown>>[];
     instructions?: string;
 }
+/**
+ * Validate and snapshot the tools once, then return a factory that builds an
+ * isolated SDK `Server` per call. Pass it to the SDK's `createMcpHandler` or
+ * `serveStdio` for custom serving; unlike `createMcpServer`, validation and the
+ * tool snapshot happen at this call, not once per server.
+ */
+export declare function createMcpServerFactory(options: CreateMcpServerOptions): () => Server;
+/**
+ * Build a single low-level SDK `Server`.
+ *
+ * @deprecated A directly connected `Server` (`server.connect(transport)`) can
+ * only speak the legacy era, which BridgeKit's serving entrypoints no longer
+ * support. Use `runMcpStdioServer` or `createMcpHttpHandler`, or for custom
+ * serving pass `createMcpServerFactory(options)` to the SDK's
+ * `createMcpHandler(factory, { legacy: "reject" })`. Do not wrap this function
+ * in a factory: it revalidates and re-snapshots the tools on every call.
+ */
 export declare function createMcpServer(options: CreateMcpServerOptions): Server;
-export declare function runMcpStdioServer(options: CreateMcpServerOptions): Promise<void>;
+export interface McpStdioServerHandle {
+    /**
+     * Close the transport and abort in-flight requests. Safe to call repeatedly.
+     * Does not await tool handlers: asynchronous abort cleanup may outlive close().
+     * Coordinate shared-resource disposal with your tools before ending pools.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Install modern-era (`2026-07-28`) stdio serving and return a close handle.
+ * `2025-11-25` openings are answered with the unsupported-protocol-version
+ * error. Resolution means transport wiring is ready, not that a client has
+ * connected or shutdown.
+ */
+export declare function runMcpStdioServer(options: CreateMcpServerOptions): Promise<McpStdioServerHandle>;

package/dist/src/adapters/mcp.js

@@ -3,9 +3,10 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { executePortableTool } from "../core/execute-tool.js";
 import { assertPortableOutputSchema, isObjectSchema, schemaTypeLabel, throwWithCode } from "../core/output-schema.js";
 function toMcpResult(result) {
+    // `!== undefined` rather than `??`: `null` is a legal structured value.
     return {
         content: [{ type: "text", text: result.text }],
-        structuredContent: result.structuredContent ?? result.details,
+        structuredContent: result.structuredContent !== undefined ? result.structuredContent : result.details,
         isError: result.isError ?? false,
     };
 }
@@ -27,6 +28,22 @@ function toMcpObjectSchema(schema) {
     }
     return { type: "object", ...schema };
 }
+/**
+ * Render an output schema for `tools/list` and for `projectCallToolResult`.
+ * All-object `allOf` intersections still get `type: "object"` synthesized so
+ * existing `Type.Intersect` outputs keep their wire shape (the SDK's legacy-era
+ * `{ result: ... }` wrap, reachable only through a directly connected
+ * deprecated `createMcpServer`, keys purely on the advertised root `type`).
+ * Every other root (array, primitive, union) passes through by reference. The
+ * same object must feed both the listing and the projection.
+ */
+function toMcpOutputSchema(schema) {
+    const candidate = schema;
+    if (candidate.type === undefined && isObjectSchema(schema)) {
+        return { type: "object", ...candidate };
+    }
+    return candidate;
+}
 /**
  * Stable `error.code` values attached to `createMcpServer` construction
  * failures so consumers have a non-string anchor (the message text is
@@ -35,6 +52,24 @@ function toMcpObjectSchema(schema) {
 const ERROR_CODE_NON_OBJECT_PARAMETERS = "BRIDGEKIT_MCP_NON_OBJECT_PARAMETERS";
 const ERROR_CODE_REF_PARAMETERS = "BRIDGEKIT_MCP_REF_PARAMETERS";
 const ERROR_CODE_DUPLICATE_TOOL_NAME = "BRIDGEKIT_MCP_DUPLICATE_TOOL_NAME";
+function assertToolIcons(tool) {
+    const icons = tool.hostExtras?.mcp?.icons;
+    if (icons === undefined)
+        return;
+    if (!Array.isArray(icons) ||
+        icons.some((icon) => typeof icon !== "object" ||
+            icon === null ||
+            !("src" in icon) ||
+            typeof icon.src !== "string" ||
+            ("mimeType" in icon && icon.mimeType !== undefined && typeof icon.mimeType !== "string") ||
+            ("sizes" in icon &&
+                icon.sizes !== undefined &&
+                (!Array.isArray(icon.sizes) || icon.sizes.some((size) => typeof size !== "string"))) ||
+            ("theme" in icon && icon.theme !== undefined && icon.theme !== "light" && icon.theme !== "dark"))) {
+        throwWithCode(`createMcpServer: tool "${tool.name}" has invalid MCP icons; expected an array of icons with string src, ` +
+            "optional string mimeType, string[] sizes, and light or dark theme.", "BRIDGEKIT_MCP_INVALID_ICONS");
+    }
+}
 function assertObjectShapedParameters(tools) {
     for (const tool of tools) {
         if (!isObjectSchema(tool.parameters)) {
@@ -81,17 +116,32 @@ function assertUniqueToolNames(tools) {
         seen.add(tool.name);
     }
 }
-export function createMcpServer(options) {
-    for (const tool of options.tools)
+/**
+ * Validate and snapshot the tools once, then return a factory that builds an
+ * isolated SDK `Server` per call. Pass it to the SDK's `createMcpHandler` or
+ * `serveStdio` for custom serving; unlike `createMcpServer`, validation and the
+ * tool snapshot happen at this call, not once per server.
+ */
+export function createMcpServerFactory(options) {
+    const { name, version, instructions } = options;
+    for (const tool of options.tools) {
         assertPortableOutputSchema(tool, "createMcpServer", "BRIDGEKIT_MCP");
+        assertToolIcons(tool);
+    }
     assertObjectShapedParameters(options.tools);
     assertUniqueToolNames(options.tools);
     // Build the dispatch map and the listing payload at construction so
     // `tools/list` returns a pre-computed array and post-construction mutations
     // to the caller's array cannot leak unvalidated schemas onto the wire.
-    const byName = new Map(options.tools.map((tool) => [tool.name, tool]));
-    const mcpTools = options.tools.map((tool) => {
+    const entries = options.tools.map((tool) => ({
+        tool: { ...tool },
+        outputSchema: tool.outputSchema !== undefined ? toMcpOutputSchema(tool.outputSchema) : undefined,
+    }));
+    const byName = new Map(entries.map((entry) => [entry.tool.name, entry]));
+    const mcpTools = entries.map(({ tool, outputSchema }) => {
         const annotations = tool.hostExtras?.mcp?.annotations;
+        const icons = tool.hostExtras?.mcp?.icons;
+        const meta = tool.hostExtras?.mcp?._meta;
         // MCP advisory hints from `hostExtras.mcp.annotations`. Two gates:
         //   1. `annotations !== undefined` — a tool without hostExtras builds a
         //      Tool entry whose own-property keys are byte-identical to 0.8.x.
@@ -111,45 +161,104 @@ export function createMcpServer(options) {
             title: tool.title,
             description: tool.description,
             inputSchema: toMcpObjectSchema(tool.parameters),
-            ...(tool.outputSchema !== undefined && { outputSchema: toMcpObjectSchema(tool.outputSchema) }),
+            ...(outputSchema !== undefined && { outputSchema }),
             ...(hasAnnotations ? { annotations: { ...annotations } } : {}),
+            ...(icons !== undefined
+                ? { icons: icons.map(({ sizes, ...icon }) => ({ ...icon, ...(sizes !== undefined && { sizes: [...sizes] }) })) }
+                : {}),
+            ...(meta !== undefined ? { _meta: { ...meta } } : {}),
         };
     });
-    const server = new Server({ name: options.name, version: options.version }, {
-        capabilities: { tools: { listChanged: false } },
-        ...(options.instructions !== undefined && { instructions: options.instructions }),
-    });
-    server.setRequestHandler("tools/list", async () => ({ tools: mcpTools }));
-    server.setRequestHandler("tools/call", async (request, ctx) => {
-        const tool = byName.get(request.params.name);
-        if (!tool) {
-            return {
-                content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
-                isError: true,
-            };
-        }
-        try {
-            const result = await executePortableTool(tool, request.params.arguments ?? {}, {
-                host: "mcp",
-                signal: ctx.mcpReq.signal,
-            });
-            return server.projectCallToolResult(toMcpResult(result), tool.outputSchema !== undefined ? toMcpObjectSchema(tool.outputSchema) : undefined);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return {
-                content: [{ type: "text", text: message }],
-                isError: true,
-            };
-        }
-    });
-    return server;
+    return () => {
+        const server = new Server({ name, version }, {
+            capabilities: { tools: { listChanged: false } },
+            ...(instructions !== undefined && { instructions }),
+        });
+        server.setRequestHandler("tools/list", async () => ({ tools: mcpTools }));
+        server.setRequestHandler("tools/call", async (request, ctx) => {
+            const entry = byName.get(request.params.name);
+            if (!entry) {
+                return {
+                    content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+                    isError: true,
+                };
+            }
+            // `ctx.progress` is only wired when the client asked for progress by
+            // sending `_meta.progressToken`; otherwise the context is byte-identical
+            // to the pre-progress shape. `progress` is a monotonic per-call counter
+            // (the spec requires it to increase) and `message` is the update text.
+            // Sends are skipped once the request is cancelled and awaited before the
+            // result goes out, so a client never sees a notification for a token it
+            // has already released. A failed send never fails the tool call.
+            const progressToken = ctx.mcpReq._meta?.progressToken;
+            const pendingNotifications = [];
+            let progressCount = 0;
+            const progress = progressToken === undefined
+                ? undefined
+                : (update) => {
+                    if (ctx.mcpReq.signal.aborted)
+                        return;
+                    progressCount += 1;
+                    pendingNotifications.push(ctx.mcpReq
+                        .notify({
+                        method: "notifications/progress",
+                        params: { progressToken, progress: progressCount, message: update.text },
+                    })
+                        .catch(() => undefined));
+                };
+            try {
+                const result = await executePortableTool(entry.tool, request.params.arguments ?? {}, {
+                    host: "mcp",
+                    signal: ctx.mcpReq.signal,
+                    ...(progress !== undefined && { progress }),
+                });
+                await Promise.all(pendingNotifications);
+                return server.projectCallToolResult(toMcpResult(result), entry.outputSchema);
+            }
+            catch (error) {
+                await Promise.all(pendingNotifications);
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: "text", text: message }],
+                    isError: true,
+                };
+            }
+        });
+        return server;
+    };
+}
+/**
+ * Build a single low-level SDK `Server`.
+ *
+ * @deprecated A directly connected `Server` (`server.connect(transport)`) can
+ * only speak the legacy era, which BridgeKit's serving entrypoints no longer
+ * support. Use `runMcpStdioServer` or `createMcpHttpHandler`, or for custom
+ * serving pass `createMcpServerFactory(options)` to the SDK's
+ * `createMcpHandler(factory, { legacy: "reject" })`. Do not wrap this function
+ * in a factory: it revalidates and re-snapshots the tools on every call.
+ */
+export function createMcpServer(options) {
+    return createMcpServerFactory(options)();
 }
+/**
+ * Install modern-era (`2026-07-28`) stdio serving and return a close handle.
+ * `2025-11-25` openings are answered with the unsupported-protocol-version
+ * error. Resolution means transport wiring is ready, not that a client has
+ * connected or shutdown.
+ */
 export async function runMcpStdioServer(options) {
-    // Validate eagerly, but each discarded probe/connection must own its server:
-    // a modern probe installs era-specific handlers before it can be discarded.
-    createMcpServer(options);
-    serveStdio(() => createMcpServer(options), {
+    // Validate eagerly; the SDK asks the factory for a fresh server per
+    // discovery probe/connection, so none share handler state.
+    const factory = createMcpServerFactory(options);
+    const handle = serveStdio(factory, {
+        legacy: "reject",
         onerror: (error) => process.stderr.write(`[bridgekit-mcp] ${error.message}\n`),
     });
+    let closing;
+    return {
+        close: () => {
+            closing ??= handle.close();
+            return closing;
+        },
+    };
 }

package/dist/src/adapters/pi.d.ts

@@ -11,7 +11,7 @@ type PiToolUpdate = {
 type PiToolResult = {
     content: PiContent[];
     details: Record<string, unknown>;
-    structuredContent?: Record<string, unknown>;
+    structuredContent?: unknown;
     isError?: boolean;
 };
 type PiToolDefinition = {
@@ -55,7 +55,7 @@ export interface RegisterPiToolsOptions {
 }
 export declare class PortableToolExecutionError extends Error {
     readonly details: PortableToolErrorDetails;
-    constructor(result: PortableToolResult);
+    constructor(result: PortableToolResult<unknown>);
 }
 export declare function isPortableToolExecutionError(error: unknown): error is PortableToolExecutionError;
 /**
@@ -75,5 +75,5 @@ export declare function isPortableToolExecutionError(error: unknown): error is P
  * // Deprecated, but available through 0.x.
  * registerPiTools(pi, tools, { errorHandling: "throw" });
  */
-export declare function registerPiTools(pi: PiToolRegistration, tools: readonly PortableTool<TSchema>[], options?: RegisterPiToolsOptions): void;
+export declare function registerPiTools(pi: PiToolRegistration, tools: readonly PortableTool<TSchema, PortableToolResult<unknown>>[], options?: RegisterPiToolsOptions): void;
 export {};

package/dist/src/adapters/pi.js

@@ -1,8 +1,19 @@
 import { executePortableTool } from "../core/execute-tool.js";
 import { assertPortableOutputSchema } from "../core/output-schema.js";
 import { isValidationFailure } from "../core/result-guards.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Renderer-facing `details` is always an object. Non-object structured
+ * content (array, primitive, `null`) is wrapped as `{ result: value }`,
+ * mirroring the MCP SDK's legacy-era projection of the same values.
+ */
 function toPiDetails(result) {
-    return result.structuredContent ?? result.details ?? {};
+    if (result.structuredContent !== undefined) {
+        return isRecord(result.structuredContent) ? result.structuredContent : { result: result.structuredContent };
+    }
+    return result.details ?? {};
 }
 function toPortableToolErrorDetails(result) {
     if (isValidationFailure(result)) {

package/dist/src/core/define-tool.d.ts

@@ -1,8 +1,15 @@
 import type { Static, TSchema } from "typebox";
-export interface PortableToolResult<TStructured extends Record<string, unknown> = Record<string, unknown>> {
+export interface PortableToolResult<TStructured = Record<string, unknown>> {
     /** Plain text sent back to the model in every host. */
     text: string;
-    /** Structured data for hosts that support it. Preferred by both pi and MCP adapters. */
+    /**
+     * Structured data for hosts that support it. Preferred by both pi and MCP
+     * adapters. Any JSON value is accepted (object, array, primitive, `null`);
+     * the default type parameter keeps the common object case ergonomic.
+     * Non-object values reach MCP `structuredContent` directly (BridgeKit
+     * serves only the modern era) and are wrapped as `{ result: value }` in pi's
+     * renderer-facing `details`.
+     */
     structuredContent?: TStructured;
     /**
      * Legacy/adapter debug details used only when `structuredContent` is absent.
@@ -40,7 +47,12 @@ export type PortableToolBuiltInHost = "pi" | "mcp" | "test";
 export interface PortableToolContext {
     host: PortableToolBuiltInHost;
     signal?: AbortSignal;
-    progress?: (update: PortableToolResult) => void;
+    /**
+     * Host progress channel. Pi maps each update to `onUpdate`; MCP maps it to
+     * `notifications/progress` when the request carried a `progressToken`
+     * (`progress` is a monotonic per-call counter and `message` is `update.text`).
+     */
+    progress?: (update: PortableToolResult<unknown>) => void;
 }
 /**
  * Optional TUI renderer for the tool call line (before execution).
@@ -106,6 +118,21 @@ export interface PiHostExtras {
  * @see PortableToolHostExtras
  */
 export interface McpHostExtras {
+    /**
+     * Tool icons forwarded to tools/list. The array, icon objects, and sizes
+     * arrays are copied at server construction. BridgeKit does not fetch icons.
+     */
+    icons?: readonly {
+        src: string;
+        mimeType?: string;
+        sizes?: readonly string[];
+        theme?: "light" | "dark";
+    }[];
+    /**
+     * Opaque MCP tool metadata. Shallow-copied at server construction;
+     * nested values remain caller-owned and must be treated as immutable.
+     */
+    _meta?: Record<string, unknown>;
     /**
      * MCP tool annotations attached to `tools/list` entries. Hints clients may
      * surface to users; do not affect validation or execution.
@@ -153,23 +180,31 @@ export interface PortableToolHostExtras {
     pi?: PiHostExtras;
     mcp?: McpHostExtras;
 }
+/**
+ * Object-rooted outputs keep the open-record intersection so handlers may
+ * return extra keys beyond the schema; array and primitive roots are used as-is
+ * (neither is assignable to `Record<string, unknown>`).
+ */
+type SchemaOutput<T> = [T] extends [readonly unknown[]] ? T : [T] extends [object] ? T & Record<string, unknown> : T;
 /** Successes satisfy the output schema; literal domain failures retain arbitrary data. */
-type SchemaResult<TOutput extends TSchema> = (PortableToolResult & {
-    structuredContent: Exclude<Static<TOutput>, undefined> & Record<string, unknown>;
+type SchemaResult<TOutput extends TSchema> = (PortableToolResult<unknown> & {
+    structuredContent: SchemaOutput<Exclude<Static<TOutput>, undefined>>;
     isError?: false;
-}) | (PortableToolResult & {
+}) | (PortableToolResult<unknown> & {
     isError: true;
 });
-type CheckedResult<TResult extends PortableToolResult, TOutput extends TSchema | undefined> = [TOutput] extends [
-    TSchema
-] ? TResult & SchemaResult<NoInfer<Extract<TOutput, TSchema>>> : TResult;
-export interface PortableTool<TParams extends TSchema = TSchema, TResult extends PortableToolResult = PortableToolResult, TOutput extends TSchema | undefined = TSchema | undefined> {
+type CheckedResult<TResult extends PortableToolResult<unknown>, TOutput extends TSchema | undefined> = [
+    TOutput
+] extends [TSchema] ? TResult & SchemaResult<NoInfer<Extract<TOutput, TSchema>>> : TResult;
+export interface PortableTool<TParams extends TSchema = TSchema, TResult extends PortableToolResult<unknown> = PortableToolResult<unknown>, TOutput extends TSchema | undefined = TSchema | undefined> {
     name: string;
     title: string;
     description: string;
     parameters: TParams;
     /**
-     * Object-shaped TypeBox schema for successful structuredContent.
+     * TypeBox schema for successful structuredContent. Any JSON Schema root is
+     * accepted except a top-level `$ref` (`Type.Ref` / `Type.Cyclic`); objects,
+     * object intersections, arrays, primitives and unions are all valid.
      * Literal isError:true results are exempt. Treat this schema and parameters
      * as immutable after registration, including replacing either schema object.
      */
@@ -190,14 +225,14 @@ export declare function definePortableTool<TParams extends TSchema, TOutput exte
     outputSchema: TOutput;
     execute: TExecute;
 }): PortableTool<TParams, Awaited<ReturnType<TExecute>>, TOutput>;
-export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult>(tool: PortableTool<TParams, TResult> & {
+export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult<unknown>>(tool: PortableTool<TParams, TResult> & {
     outputSchema?: undefined;
 }): PortableTool<TParams, TResult, undefined>;
 export declare function definePortableTool<TParams extends TSchema, TOutput extends TSchema, TExecute extends (args: Static<TParams>, ctx: PortableToolContext) => SchemaResult<NoInfer<TOutput>> | Promise<SchemaResult<NoInfer<TOutput>>>>(tool: Omit<PortableTool<TParams, PortableToolResult, TOutput>, "execute" | "outputSchema"> & {
     outputSchema?: TOutput;
     execute: TExecute;
 }): PortableTool<TParams, Awaited<ReturnType<TExecute>>, TOutput>;
-export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult, TTool extends {
+export declare function definePortableTool<TParams extends TSchema, TResult extends PortableToolResult<unknown>, TTool extends {
     outputSchema?: TSchema | undefined;
 } = PortableTool<TParams, TResult>>(tool: PortableTool<TParams, TResult> & TTool & (TSchema extends NonNullable<NoInfer<TTool>["outputSchema"]> ? unknown : never)): TTool;
 export {};

package/dist/src/core/execute-tool.d.ts

@@ -1,7 +1,7 @@
 import type { Static, TSchema } from "typebox";
 import type { PortableTool, PortableToolContext, PortableToolResult, PortableValidationError } from "./define-tool.js";
 import type { PortableValidationFailure } from "./result-guards.js";
-type PortableToolSuccess<TResult extends PortableToolResult> = TResult & {
+type PortableToolSuccess<TResult extends PortableToolResult<unknown>> = TResult & {
     details?: Record<string, unknown>;
     isError?: boolean;
 } & (TResult extends {
@@ -11,12 +11,12 @@ type PortableToolSuccess<TResult extends PortableToolResult> = TResult & {
 } : {
     structuredContent?: Record<string, unknown>;
 });
-export declare function validatePortableToolArgs<TParams extends TSchema>(tool: PortableTool<TParams>, args: unknown): {
+export declare function validatePortableToolArgs<TParams extends TSchema>(tool: PortableTool<TParams, PortableToolResult<unknown>>, args: unknown): {
     ok: true;
     args: Static<TParams>;
 } | {
     ok: false;
     errors: PortableValidationError[];
 };
-export declare function executePortableTool<TParams extends TSchema, TResult extends PortableToolResult>(tool: PortableTool<TParams, TResult>, args: unknown, ctx: PortableToolContext): Promise<PortableToolSuccess<TResult> | PortableValidationFailure>;
+export declare function executePortableTool<TParams extends TSchema, TResult extends PortableToolResult<unknown>>(tool: PortableTool<TParams, TResult>, args: unknown, ctx: PortableToolContext): Promise<PortableToolSuccess<TResult> | PortableValidationFailure>;
 export {};

package/dist/src/core/output-schema.d.ts

@@ -1,7 +1,14 @@
-import type { PortableTool } from "./define-tool.js";
+import type { TSchema } from "typebox";
+import type { PortableTool, PortableToolResult } from "./define-tool.js";
 /** Follow JSON Schema structure rather than TypeBox-specific symbols. */
 export declare function isObjectSchema(schema: unknown): boolean;
 /** Identify the first unsupported root/branch for an actionable schema diagnostic. */
 export declare function schemaTypeLabel(schema: unknown): string;
 export declare function throwWithCode(message: string, code: string, ErrorType?: ErrorConstructor): never;
-export declare function assertPortableOutputSchema(tool: PortableTool, context?: string, codePrefix?: string): void;
+/**
+ * Output schemas may use any JSON Schema root (object, array, primitive,
+ * union); modern MCP clients receive non-object roots as-is. Only a
+ * top-level `$ref` is rejected: `tools/list` ships schemas by value and clients
+ * do not resolve references.
+ */
+export declare function assertPortableOutputSchema(tool: PortableTool<TSchema, PortableToolResult<unknown>>, context?: string, codePrefix?: string): void;

package/dist/src/core/output-schema.js

@@ -38,16 +38,16 @@ export function throwWithCode(message, code, ErrorType = Error) {
     error.code = code;
     throw error;
 }
+/**
+ * Output schemas may use any JSON Schema root (object, array, primitive,
+ * union); modern MCP clients receive non-object roots as-is. Only a
+ * top-level `$ref` is rejected: `tools/list` ships schemas by value and clients
+ * do not resolve references.
+ */
 export function assertPortableOutputSchema(tool, context, codePrefix = "BRIDGEKIT") {
-    if (tool.outputSchema !== undefined && !isObjectSchema(tool.outputSchema)) {
-        const label = schemaTypeLabel(tool.outputSchema);
-        let recipe = "Use an inlined object schema or an intersection of object schemas.";
-        if (label.includes("$ref")) {
-            recipe += " Top-level $ref / Type.Cyclic is unsupported; inline the referenced shape or split recursive shapes.";
-        }
-        else if (label.includes("anyOf") || label.includes("oneOf")) {
-            recipe += " Top-level unions are unsupported; flatten branches into one object or expose separate tools.";
-        }
-        throwWithCode(`${context ? `${context}: ` : ""}Invalid outputSchema for ${tool.name} (type="${label}"): ${recipe}`, `${codePrefix}_${label.includes("$ref") ? "REF" : "NON_OBJECT"}_OUTPUT_SCHEMA`, TypeError);
+    const schema = tool.outputSchema;
+    if (schema !== undefined && typeof schema.$ref === "string") {
+        throwWithCode(`${context ? `${context}: ` : ""}Invalid outputSchema for ${tool.name} (type="$ref"): ` +
+            "Top-level $ref / Type.Cyclic is unsupported; inline the referenced shape or split recursive shapes.", `${codePrefix}_REF_OUTPUT_SCHEMA`, TypeError);
     }
 }

package/dist/src/core/result-guards.d.ts

@@ -26,10 +26,10 @@ export type PortableValidationFailure = PortableToolResult & {
  * (The pi adapter's `PortableToolExecutionError.details` does synthesize that
  * discriminator for the deprecated `errorHandling: "throw"` path.)
  */
-export type PortableDomainFailure = PortableToolResult & {
+export type PortableDomainFailure = PortableToolResult<unknown> & {
     isError: true;
 };
-export declare function isValidationFailure(result: PortableToolResult): result is PortableValidationFailure;
+export declare function isValidationFailure(result: PortableToolResult<unknown>): result is PortableValidationFailure;
 /**
  * Type guard for handler-emitted `isError: true` results that are not
  * validation failures. Use after `result.isError` to branch between
@@ -41,4 +41,4 @@ export declare function isValidationFailure(result: PortableToolResult): result
  *   metrics.increment("tool.domain_error", { tool: tool.name });
  * }
  */
-export declare function isDomainFailure(result: PortableToolResult): result is PortableDomainFailure;
+export declare function isDomainFailure(result: PortableToolResult<unknown>): result is PortableDomainFailure;

package/dist/src/mcp.d.ts

@@ -1 +1,2 @@
-export { type CreateMcpServerOptions, createMcpServer, runMcpStdioServer, } from "./adapters/mcp.js";
+export { type CreateMcpServerOptions, createMcpServer, createMcpServerFactory, type McpStdioServerHandle, runMcpStdioServer, } from "./adapters/mcp.js";
+export { type CreateMcpHttpHandlerOptions, createMcpHttpHandler, type McpHttpHandler, } from "./adapters/mcp-http.js";

package/dist/src/mcp.js

@@ -1 +1,2 @@
-export { createMcpServer, runMcpStdioServer, } from "./adapters/mcp.js";
+export { createMcpServer, createMcpServerFactory, runMcpStdioServer, } from "./adapters/mcp.js";
+export { createMcpHttpHandler, } from "./adapters/mcp-http.js";

package/examples/README.md

@@ -270,10 +270,15 @@ MCP behavior:
 - `tools/call` validates arguments before invoking handlers.
 - Invalid arguments and portable `isError: true` results return MCP tool results with `isError: true`.
 - Unexpected thrown errors become MCP tool errors with text content.
-- Optional object-shaped `outputSchema` is listed for successful structured results;
-  matching `structuredContent` is required and validated. Error results are exempt.
-- The stdio runner serves legacy and modern `2026-07-28` clients through SDK v2.
-  It retains `Promise<void>` startup behavior; stdin EOF shuts down the connection.
+- Optional `outputSchema` (any root except top-level `$ref`) is listed for successful
+  structured results; matching `structuredContent` is required and validated. Error
+  results are exempt. Non-object values reach MCP clients as-is and are wrapped as `{ result }` on pi `details`.
+- `ctx.progress?.(...)` becomes `notifications/progress` when the client sent a
+  `progressToken`; otherwise `ctx.progress` is `undefined`.
+- The stdio runner serves modern `2026-07-28` clients through SDK v2; legacy-era clients (`2025-11-25` and earlier) are rejected.
+  It returns `Promise<McpStdioServerHandle>` after wiring is installed; stdin EOF or
+  `await handle.close()` shuts down the connection and aborts in-flight requests.
+  `close()` does not await asynchronous tool cleanup.
 - The module stays import-passive and testable: tests can import `createMcpServerOptions()` without starting stdio.
 
 ---
@@ -418,5 +423,5 @@ For publishable tool packages:
 - When a bin depends on generated output, prefer a checked-in wrapper under `bin/` over pointing directly at `dist/`; for MCP stdio bins set `buildStdio: ["ignore", "inherit", "inherit"]`; test existing output, missing output, failed builds, and successful builds that omit the expected file.
 - If only the MCP bin needs compiled output, narrow its tsconfig to the MCP entrypoint and shared host-neutral modules instead of compiling unrelated host adapters.
 - Add a packed-install smoke test that installs tarballs into a temporary project.
-- For BridgeKit itself, run `npm run check`, `npm run test`, `npm run pack:dry-run`, `npm run package-smoke`, and `npm audit --omit=dev --audit-level=high` before release.
+- For BridgeKit itself (a pnpm project), run `pnpm run check`, `pnpm test`, `pnpm run pack:dry-run`, `pnpm run package-smoke`, and `pnpm audit --prod --audit-level high` before release.
 - Keep imports side-effect free; registration and server startup should happen only in explicit entrypoints.

package/llms.txt

@@ -19,7 +19,7 @@ import {
   isValidationFailure,
 } from "@feniix/bridgekit";
 import { registerPiTools } from "@feniix/bridgekit/pi";
-import { createMcpServer, runMcpStdioServer } from "@feniix/bridgekit/mcp";
+import { createMcpHttpHandler, runMcpStdioServer } from "@feniix/bridgekit/mcp";
 import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper"; // optional: built-in bin wrapper for mixed source-loaded pi + compiled MCP packages
 ```
 
@@ -59,9 +59,11 @@ export function createTools() {
 - Keep portable tools host-neutral. Do not import pi or MCP SDKs from files that define tool behavior.
 - Tool `parameters` for MCP-compatible tools must resolve to a JSON-Schema object at the top level. `Type.Object(...)` is the common case; `Type.Intersect([Type.Object(...), Type.Object(...)])` is also accepted. Non-object top-level shapes throw at `createMcpServer` construction.
 - Return `{ text, structuredContent }` for successful results.
-- Optional `outputSchema` declares successful structured data for both hosts: use
-  an inlined TypeBox object or object intersection. Missing/invalid successful
-  `structuredContent` throws `TypeError`; argument/domain error results are exempt.
+- Optional `outputSchema` declares successful structured data for both hosts: any
+  TypeBox schema except a top-level `$ref` (objects, intersections, arrays,
+  primitives, unions). Missing/invalid successful `structuredContent` throws
+  `TypeError`; argument/domain error results are exempt. Non-object values are
+  passed as-is to MCP clients and wrapped as `{ result }` on pi `details`.
   Legacy `details` alone does not satisfy a declared output schema.
   `definePortableTool` infers/checks schema-linked success data at compile time;
   use literal `isError: true` for exempt domain failures. A third
@@ -75,6 +77,8 @@ export function createTools() {
 - Throw only for unexpected programmer, adapter, or runtime failures.
 - Respect `ctx.signal` in long-running tools.
 - Use `ctx.progress?.(...)` for incremental progress updates when the host supports them.
+  Pi maps them to `onUpdate`; MCP emits `notifications/progress` (counter + `update.text`)
+  only when the client sent `_meta.progressToken`, otherwise `ctx.progress` is `undefined`.
 - Wire hosts explicitly: pi registration and MCP server startup are separate adapter calls.
 - Keep modules import-passive. Do not register tools, start servers, read package metadata, read env vars, or touch files at import time.
 - For stateful tools, export a `createTools()` factory instead of a module-level `tools` singleton so each pi extension instance or MCP stdio process gets isolated state.
@@ -96,12 +100,42 @@ export function createTools() {
   Their runtime predicates are shape-based, so Pi structured failures also
   match; that does not make a raw Pi result a valid portable typed value.
 - MCP uses SDK v2's low-level `Server` and method-string handlers. Cancellation
-  reads `ctx.mcpReq.signal`. `runMcpStdioServer` serves legacy and modern
-  `2026-07-28` stdio; direct `Server.connect` remains legacy-only. The runner's
-  `Promise<void>` resolves at startup, not EOF. Migration details:
+  reads `ctx.mcpReq.signal`. `runMcpStdioServer` serves modern
+  `2026-07-28` stdio only (legacy-era openings are rejected with `-32022`);
+  `createMcpServer` is deprecated as a direct `Server.connect` target (legacy-only). The runner's
+  `Promise<McpStdioServerHandle>` resolves at startup, not EOF; call the
+  handle's idempotent `close()` to tear down explicitly. Migration details:
   `docs/mcp-v2-migration.md`.
+- `createMcpHttpHandler(options, httpOptions?)` returns the SDK's Web-standard
+  HTTP handler (`fetch`, `close`, `notify`, `bus`), modern era only.
+  It starts no listener. Applications must enforce authentication, authorization,
+  Host/Origin validation, TLS, and CORS before calling `fetch`.
 - `registerPiTools(pi, tools, { errorHandling: "throw" })` opts into the pre-0.7 behavior where `isError` results throw `PortableToolExecutionError`. Selecting this value emits a `DeprecationWarning` (code `BRIDGEKIT_PI_THROW_DEPRECATED`) once per process; only the `"throw"` value is deprecated, not the option itself. Scheduled for removal in 1.0; do not adopt it for new code.
-- `PortableTool.hostExtras` (0.9+) carries optional per-host metadata in namespaced sub-objects (`pi`, `mcp`, plus module-augmentable custom hosts). Each field is optional and zero-cost when absent — a tool without `hostExtras` produces byte-identical pi registration and MCP `tools/list` payloads to 0.8.x. `hostExtras.pi.pendingMessage` fires `onUpdate({ content, details: { status: "pending" } })` exactly once before TypeBox validation; `hostExtras.pi.promptSnippet` / `promptGuidelines` pass through to pi's `registerTool`; `hostExtras.pi.renderCall` / `renderResult` are opaque TUI callbacks typed by exported `PiToolCallRenderer` / `PiToolResultRenderer` aliases and forwarded by identity; `hostExtras.mcp.annotations` (`title` / `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`) attaches MCP advisory hints. Tool definitions stay host-neutral — host-specific metadata lives in its namespace, not on the tool's top-level fields.
+- `PortableTool.hostExtras` (0.9+) carries optional per-host metadata in namespaced sub-objects (`pi`, `mcp`, plus module-augmentable custom hosts). Each field is optional and zero-cost when absent — a tool without `hostExtras` produces byte-identical pi registration and MCP `tools/list` payloads to 0.8.x. `hostExtras.pi.pendingMessage` fires `onUpdate({ content, details: { status: "pending" } })` exactly once before TypeBox validation; `hostExtras.pi.promptSnippet` / `promptGuidelines` pass through to pi's `registerTool`; `hostExtras.pi.renderCall` / `renderResult` are opaque TUI callbacks typed by exported `PiToolCallRenderer` / `PiToolResultRenderer` aliases and forwarded by identity; `hostExtras.mcp.annotations` (`title` / `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`) attaches MCP advisory hints. `hostExtras.mcp.icons` carries `src`, optional `mimeType`, `sizes`, and `theme` (`light`/`dark`); malformed icons fail at construction with `BRIDGEKIT_MCP_INVALID_ICONS`. `hostExtras.mcp._meta` carries opaque MCP metadata. Both serving factories snapshot these fields once at construction: icons and sizes are copied, `_meta` is shallow-copied (nested values remain shared). Empty icons/`_meta` are forwarded, while empty annotations are omitted. Tool definitions stay host-neutral — host-specific metadata lives in its namespace, not on the tool's top-level fields.
+
+### Migrating from dual-era MCP serving
+
+BridgeKit serves only the modern MCP `2026-07-28` era. Legacy-era openings
+(`2025-11-25` and earlier) are rejected with `-32022`
+(`data.supported: ["2026-07-28"]`); stdio stays open for a modern opening.
+
+1. Pin clients: the SDK v2 client defaults to `versionNegotiation.mode: "legacy"`
+   and is rejected. Use `{ mode: { pin: "2026-07-28" } }` or `"auto"`.
+2. SDK v1 clients and v2 clients in `legacy` mode can no longer connect; there is
+   no compatibility switch.
+3. Replace `createMcpServer(options)` + `server.connect(transport)` with
+   `runMcpStdioServer(options)` or `createMcpHttpHandler(options, httpOptions?)`.
+   `createMcpServer` is deprecated for direct connection; for custom serving pass
+   `createMcpServerFactory(options)` to the SDK's `createMcpHandler(factory,
+   { legacy: "reject" })`. Do not wrap `createMcpServer` in a factory: it
+   revalidates and re-snapshots tools on every call.
+4. Remove `legacy` from HTTP options (removed from the type, ignored at runtime).
+5. Non-object structured output reaches clients as-is, not `{ result }`-wrapped.
+6. Each rejected request logs one `[bridgekit-mcp]` stderr line by default. The
+   HTTP handler's `onerror` option overrides it; `runMcpStdioServer` has no
+   reporter option and always writes to stderr.
+
+Details: `docs/mcp-v2-migration.md` ("Dropping legacy-era serving").
 
 ### Result-guard usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",
@@ -46,15 +46,15 @@
   "scripts": {
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "check": "npm run lint && npm run typecheck",
+    "check": "pnpm run lint && pnpm run typecheck",
     "clean": "node scripts/clean-package-dist.mjs",
     "typecheck": "tsc -b tsconfig.json --pretty false",
-    "build": "npm run clean && tsc -b tsconfig.json",
-    "test": "npm run build && node scripts/run-built-tests.mjs",
-    "test:coverage": "npm run build && node scripts/run-built-tests-coverage.mjs",
-    "pack:dry-run": "npm pack --dry-run --json",
+    "build": "pnpm run clean && tsc -b tsconfig.json",
+    "test": "pnpm run build && node scripts/run-built-tests.mjs",
+    "test:coverage": "pnpm run build && node scripts/run-built-tests-coverage.mjs",
+    "pack:dry-run": "pnpm pack --dry-run --json",
     "package-smoke": "node scripts/smoke-package.mjs",
-    "prepack": "npm run build"
+    "prepack": "pnpm run build"
   },
   "files": [
     "dist/**/*.js",
@@ -75,10 +75,11 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
     "@modelcontextprotocol/client": "^2.3.1",
-    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@modelcontextprotocol/node": "2.1.1",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/node": "^22.20.5",
     "typescript": "^6.0.3"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "packageManager": "pnpm@12.9.1"
 }