@ttoss/http-server-mcp 0.27.1 → 0.28.1

package/dist/index.mjs

@@ -5,7 +5,7 @@ import { Router } from "@ttoss/http-server";
 import { authMiddleware } from "@ttoss/http-server-auth";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { NodeStreamableHTTPServerTransport, toNodeHandler } from "@modelcontextprotocol/node";
-import { McpServer, classifyInboundRequest, createMcpHandler, fromJsonSchema } from "@modelcontextprotocol/server";
+import { McpServer, ProtocolErrorCode, SUPPORTED_PROTOCOL_VERSIONS, classifyInboundRequest, createMcpHandler, fromJsonSchema } from "@modelcontextprotocol/server";
 import { z } from "zod";
 
 //#region src/context.ts
@@ -33,41 +33,88 @@ var header = (ctx, name) => {
   const value = ctx.get(name);
   return value === "" ? void 0 : value;
 };
+/** The id to echo in an error answer, by the SDK's own rule. */
+var echoableRequestId = body => {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return null;
+  const {
+    id,
+    method
+  } = body;
+  if (typeof method !== "string") return null;
+  return typeof id === "string" || typeof id === "number" ? id : null;
+};
+/**
+* Writes a JSON-RPC error straight to the Node response: `createMcpRouter` sets
+* `ctx.respond = false` after serving, so Koa never writes `ctx.body`.
+*/
+var emitJsonRpcError = (ctx, answer, body) => {
+  ctx.res.writeHead(answer.httpStatus, {
+    "content-type": "application/json"
+  });
+  ctx.res.end(JSON.stringify({
+    jsonrpc: "2.0",
+    error: {
+      code: answer.code,
+      message: answer.message,
+      ...(answer.data !== void 0 && {
+        data: answer.data
+      })
+    },
+    id: echoableRequestId(body)
+  }));
+};
+/** The SDK's own ladder rejection, emitted with the status the SDK chose. */
+var rejectionAnswer = rejection => {
+  return {
+    httpStatus: rejection.httpStatus,
+    code: rejection.code,
+    message: rejection.message,
+    ...(rejection.data !== void 0 && {
+      data: rejection.data
+    })
+  };
+};
+/**
+* The answer to `2026-07-28` traffic without `createMcpServer`. `data.supported`
+* is what lets the client renegotiate onto a revision this endpoint serves.
+*/
+var REVISION_NOT_SERVED_ANSWER = {
+  httpStatus: 400,
+  code: ProtocolErrorCode.UnsupportedProtocolVersion,
+  message: "Unsupported protocol version: this endpoint serves the 2025-era MCP revisions only. Pass createMcpServer to createMcpRouter to serve protocol revision 2026-07-28.",
+  data: {
+    supported: [...SUPPORTED_PROTOCOL_VERSIONS]
+  }
+};
 /**
 * Builds the per-request serving function used by `createMcpRouter`, routing
-* each request to the protocol revision it actually speaks.
-*
-* Requests are classified once at the boundary with the SDK's own
-* `classifyInboundRequest`:
-*
-* - **2025-era traffic** (everything without a `2026-07-28` per-request
-*   envelope — which is all traffic from today's MCP clients) is served over
-*   `NodeStreamableHTTPServerTransport` with `enableJsonResponse: true`, the
-*   same wiring and the same plain-JSON responses this package has always
-*   produced.
-* - **`2026-07-28` traffic** is served by `createMcpHandler` with
-*   `legacy: 'reject'`, so the modern revision is handled by the SDK's
-*   stateless core rather than the transport above. Malformed requests are
-*   routed here too, so the SDK emits its own spec-defined rejection instead of
-*   this package inventing one.
-*
-* Splitting on the classifier — instead of letting `createMcpHandler` serve
-* both eras through its built-in legacy fallback — is what keeps 2025-era
-* responses byte-compatible. That fallback constructs its transport with only
-* `sessionIdGenerator: undefined` and no way to pass `enableJsonResponse`, so
-* every response it produces is SSE-framed (`text/event-stream`) regardless of
-* the handler's `responseMode`. Owning the legacy branch keeps `application/json`.
+* each request by the SDK's three-way `classifyInboundRequest` outcome.
+*
+* **Why the modern era needs `createMcpServer` rather than the `server` above.**
+* The negotiated revision is *instance* state: the SDK marks an instance modern
+* when it serves one modern request, and it then validates every later message
+* against `2026-07-28` — there is no per-request era consult. One instance
+* serving both eras is therefore pinned by the first client to speak the newer
+* revision, after which every 2025-era request is answered `-32602 Request is
+* missing the required _meta envelope…` at HTTP 200 for the life of the
+* process. The SDK's own entries take a factory and call it per request for
+* this reason (they also `close()` the instance, which a shared one cannot
+* survive). Without the factory, `2026-07-28` traffic gets
+* {@link REVISION_NOT_SERVED_ANSWER} and no other client is affected.
+*
+* **Why not `createMcpHandler`'s built-in legacy fallback.** It constructs its
+* transport with no way to pass `enableJsonResponse`, so every response it
+* produces is SSE-framed. Owning the legacy branch keeps `application/json`.
 */
 var createMcpRequestServer = ({
+  createMcpServer,
   server,
   sessionIdGenerator
 }) => {
   const isStateful = sessionIdGenerator !== void 0;
-  const modernHandler = toNodeHandler(createMcpHandler(() => {
-    return server;
-  }, {
+  const modernHandler = createMcpServer ? toNodeHandler(createMcpHandler(createMcpServer, {
     legacy: "reject"
-  }));
+  })) : void 0;
   let sharedTransport;
   if (isStateful) {
     sharedTransport = new NodeStreamableHTTPServerTransport({
@@ -84,17 +131,23 @@ var createMcpRequestServer = ({
     statelessQueue = result.catch(() => {});
     return result;
   };
-  const isLegacy = (ctx, body) => {
-    return classifyInboundRequest({
+  return async (ctx, body) => {
+    const outcome = classifyInboundRequest({
       httpMethod: ctx.method,
       protocolVersionHeader: header(ctx, "mcp-protocol-version"),
       mcpMethodHeader: header(ctx, "mcp-method"),
       mcpNameHeader: header(ctx, "mcp-name"),
       body
-    }).kind === "legacy";
-  };
-  return async (ctx, body) => {
-    if (!isLegacy(ctx, body)) {
+    });
+    if (outcome.kind === "reject") {
+      emitJsonRpcError(ctx, rejectionAnswer(outcome), body);
+      return;
+    }
+    if (outcome.kind === "modern") {
+      if (modernHandler === void 0) {
+        emitJsonRpcError(ctx, REVISION_NOT_SERVED_ANSWER, body);
+        return;
+      }
       await modernHandler(ctx.req, ctx.res, body);
       return;
     }
@@ -117,6 +170,160 @@ var createMcpRequestServer = ({
   };
 };
 
+//#endregion
+//#region src/registerAppResource.ts
+/**
+* Identifier of the MCP Apps extension (`io.modelcontextprotocol/ui`), used as
+* the key under `capabilities.extensions` on both sides of the handshake.
+*
+* A client declares Apps support with it; a server may advertise the same key
+* so a host can discover the support without inspecting tool metadata:
+*
+* ```typescript
+* new McpServer(
+*   { name: 'weather', version: '1.0.0' },
+*   {
+*     capabilities: {
+*       extensions: {
+*         [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] },
+*       },
+*     },
+*   }
+* );
+* ```
+*/
+var UI_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** MIME type every MCP Apps HTML resource is served as. */
+var UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+* Deprecated flat tool metadata key for the linked resource URI. Written
+* alongside `_meta.ui.resourceUri` because both forms are legal until the
+* extension reaches GA, at which point this key is removed from the spec.
+*/
+var LEGACY_RESOURCE_URI_KEY = "ui/resourceUri";
+/**
+* Registers an MCP Apps view: a `ui://` resource a tool result is rendered
+* with, per the `io.modelcontextprotocol/ui` extension.
+*
+* The extension asks nothing of the transport — a view is an ordinary MCP
+* resource, and the tool linkage is ordinary tool `_meta` — so this is
+* registration sugar over `registerResource`, not new protocol surface. What
+* it owns is the part that is easy to get wrong: the `ui://` scheme, the exact
+* MIME type, `_meta.ui` on both the declaration and the read result, and
+* writing the deprecated flat linkage key alongside the current one.
+*
+* **Register the linkage unconditionally.** The extension's negotiation is
+* per-request and only reliably readable on the `2026-07-28` revision; in this
+* package's default stateless 2025-era mode there is no remembered
+* `initialize` to read a client capability from. Gating registration on that
+* capability would therefore silently drop the view for every 2025-era client.
+* A host without Apps support simply ignores `_meta`, so keep each tool's
+* `content` meaningful on its own and let the text result be the fallback.
+*
+* @example
+* ```typescript
+* import {
+*   McpServer,
+*   registerAppResource,
+*   UI_EXTENSION_ID,
+*   UI_RESOURCE_MIME_TYPE,
+*   z,
+* } from '@ttoss/http-server-mcp';
+*
+* const server = new McpServer(
+*   { name: 'weather', version: '1.0.0' },
+*   {
+*     capabilities: {
+*       extensions: { [UI_EXTENSION_ID]: { mimeTypes: [UI_RESOURCE_MIME_TYPE] } },
+*     },
+*   }
+* );
+*
+* const dashboard = registerAppResource({
+*   server,
+*   name: 'weather_dashboard',
+*   uri: 'ui://weather/dashboard',
+*   description: 'Interactive weather dashboard',
+*   html: dashboardHtml,
+*   ui: {
+*     csp: { connectDomains: ['https://api.openweathermap.org'] },
+*     prefersBorder: true,
+*   },
+* });
+*
+* server.registerTool(
+*   'get-weather',
+*   {
+*     description: 'Get the weather for a location',
+*     inputSchema: { location: z.string() },
+*     _meta: dashboard.toolMeta(),
+*   },
+*   async ({ location }) => {
+*     const forecast = await fetchForecast(location);
+*     return {
+*       // Text stays meaningful: it is what a host without Apps renders.
+*       content: [{ type: 'text', text: summarise(forecast) }],
+*       structuredContent: forecast,
+*     };
+*   }
+* );
+* ```
+*/
+var registerAppResource = ({
+  server,
+  name,
+  uri,
+  description,
+  html,
+  ui
+}) => {
+  if (!uri.startsWith("ui://")) throw new Error(`An MCP Apps resource URI must use the ui:// scheme (received "${uri}").`);
+  const meta = ui === void 0 ? void 0 : {
+    ui
+  };
+  const resource = server.registerResource(name, uri, {
+    description,
+    mimeType: UI_RESOURCE_MIME_TYPE,
+    ...(meta === void 0 ? {} : {
+      _meta: meta
+    })
+  }, async requestedUri => {
+    const text = typeof html === "string" ? html : await html({
+      uri: requestedUri
+    });
+    return {
+      contents: [{
+        uri: requestedUri.href,
+        mimeType: UI_RESOURCE_MIME_TYPE,
+        text,
+        ...(meta === void 0 ? {} : {
+          _meta: meta
+        })
+      }]
+    };
+  });
+  const toolMeta = ({
+    visibility,
+    _meta
+  } = {}) => {
+    return {
+      ..._meta,
+      ui: {
+        resourceUri: uri,
+        ...(visibility === void 0 ? {} : {
+          visibility
+        })
+      },
+      [LEGACY_RESOURCE_URI_KEY]: uri
+    };
+  };
+  return {
+    uri,
+    resource,
+    toolMeta
+  };
+};
+
 //#endregion
 //#region src/registerToolFromSchema.ts
 /**
@@ -160,7 +367,7 @@ var toStandardSchema = ({
 *
 * @param server - The `McpServer` instance to register the tool on.
 * @param params - Tool configuration including name, description, inputSchema,
-*   validateArguments, and handler.
+*   validateArguments, `_meta`, and handler.
 *
 * @example
 * ```typescript
@@ -191,14 +398,16 @@ var registerToolFromSchema = (server, params) => {
       properties: {}
     },
     validateArguments = false,
-    handler
+    handler,
+    _meta
   } = params;
   server.registerTool(name, {
     description,
     inputSchema: toStandardSchema({
       inputSchema,
       validateArguments
-    })
+    }),
+    _meta
   }, async args => {
     return handler(args);
   });
@@ -313,7 +522,8 @@ var createGatedToolRegistrar = ({
     };
     server.registerTool(def.name, {
       description: def.description,
-      inputSchema: def.inputSchema
+      inputSchema: def.inputSchema,
+      _meta: def._meta
     }, handler);
   };
   return {
@@ -532,6 +742,7 @@ var createMcpRouter = (server, options = {}) => {
     path = "/mcp",
     aliases = [],
     sessionIdGenerator,
+    createMcpServer,
     apiBaseUrl,
     getApiHeaders,
     auth
@@ -539,7 +750,8 @@ var createMcpRouter = (server, options = {}) => {
   const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0 || auth !== void 0;
   const serveRequest = createMcpRequestServer({
     server,
-    sessionIdGenerator
+    sessionIdGenerator,
+    createMcpServer
   });
   const router = new Router();
   let authCheck;
@@ -633,4 +845,4 @@ var createMcpRouter = (server, options = {}) => {
 };
 
 //#endregion
-export { McpServer, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.27.1",
+  "version": "0.28.1",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",