@feniix/bridgekit 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -6,6 +6,60 @@ 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

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";
 ```
 
@@ -128,9 +128,8 @@ const echoTool = definePortableTool({
 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 modern MCP
-clients as-is; for legacy-era clients the MCP SDK wraps both the listed schema and
-the value as `{ result: ... }`. Pi receives the raw value on `structuredContent`
+`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
@@ -252,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" },
     },
   },
 });
@@ -259,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";
@@ -302,7 +313,7 @@ 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.
+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`,
@@ -311,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)
 

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

@@ -20,5 +20,36 @@ export interface CreateMcpServerOptions {
     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

@@ -30,12 +30,12 @@ function toMcpObjectSchema(schema) {
 }
 /**
  * Render an output schema for `tools/list` and for `projectCallToolResult`.
- * All-object `allOf` intersections still get `type: "object"` synthesized:
- * the SDK's legacy-era `{ result: ... }` wrap keys purely on the advertised
- * root `type`, so an unlowered intersection would silently change the wire
- * shape existing `Type.Intersect` outputs have today. Every other root
- * (array, primitive, union) passes through by reference and the SDK projects
- * it per era. The same object must feed both the listing and the projection.
+ * 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;
@@ -52,6 +52,24 @@ function toMcpOutputSchema(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)) {
@@ -98,21 +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 entries = options.tools.map((tool) => ({
-        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.
@@ -134,69 +163,102 @@ export function createMcpServer(options) {
             inputSchema: toMcpObjectSchema(tool.parameters),
             ...(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 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;
+    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/core/define-tool.d.ts

@@ -6,9 +6,9 @@ export interface PortableToolResult<TStructured = Record<string, unknown>> {
      * 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 on the modern
-     * era, are wrapped as `{ result: value }` by the SDK for legacy clients,
-     * and are wrapped the same way in pi's renderer-facing `details`.
+     * 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;
     /**
@@ -118,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.

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

@@ -7,7 +7,7 @@ export declare function schemaTypeLabel(schema: unknown): string;
 export declare function throwWithCode(message: string, code: string, ErrorType?: ErrorConstructor): never;
 /**
  * Output schemas may use any JSON Schema root (object, array, primitive,
- * union); the MCP SDK projects non-object roots for legacy clients. Only a
+ * 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.
  */

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

@@ -40,7 +40,7 @@ export function throwWithCode(message, code, ErrorType = Error) {
 }
 /**
  * Output schemas may use any JSON Schema root (object, array, primitive,
- * union); the MCP SDK projects non-object roots for legacy clients. Only a
+ * 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.
  */

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

@@ -272,11 +272,13 @@ MCP behavior:
 - Unexpected thrown errors become MCP tool errors with text content.
 - 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 are wrapped as `{ result }` for legacy clients.
+  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 legacy and modern `2026-07-28` clients through SDK v2.
-  It retains `Promise<void>` startup behavior; stdin EOF shuts down the connection.
+- 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.
 
 ---

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
 ```
 
@@ -63,7 +63,7 @@ export function createTools() {
   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
-  wrapped as `{ result }` for legacy MCP clients by the SDK and on pi `details`.
+  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
@@ -100,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.18.0",
+  "version": "0.19.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",
@@ -75,7 +75,7 @@
   "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"