@ttoss/http-server-mcp 0.27.0 → 0.28.0

package/README.md

@@ -371,7 +371,7 @@ The `WWW-Authenticate: Bearer resource_metadata="…"` header is how MCP clients
 
 The two behaviors the [MCP authorization spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/) requires for client bootstrapping are built into the `auth` option, so you no longer need the hand-rolled middleware shown above:
 
-- **`publicMethods`** — JSON-RPC methods that bypass verification, read from the request body's `method` field. Defaults to `['initialize']`, which the spec sanctions so a client can complete the lifecycle handshake before it can discover the authorization server. Pass `[]` to require a token for every method, or a custom list to change the exempt set. Adding `tools/list` serves the full tool catalogue — every tool name, description, and input schema — to unauthenticated callers; see [`publicMethods` and OAuth clients](#publicmethods-and-oauth-clients) before doing so.
+- **`publicMethods`** — JSON-RPC methods that bypass verification, read from the request body's `method` field. Defaults to `['initialize', 'server/discover']` — the lifecycle handshake of each protocol era, which the spec sanctions so a client can complete it before it can discover the authorization server. Pass `[]` to require a token for every method, or a custom list to change the exempt set. Adding `tools/list` serves the full tool catalogue — every tool name, description, and input schema — to unauthenticated callers; see [`publicMethods` and OAuth clients](#publicmethods-and-oauth-clients) before doing so.
 - **`resourceMetadataUrl`** — the URL a `401` advertises as `WWW-Authenticate: Bearer resource_metadata="<url>"` (RFC 9728) instead of a bare `Bearer`, pointing MCP clients at the protected-resource metadata document. **You normally do not set it**: when the document is served — i.e. both `resourceServerUrl` and `authorizationServerUrl` are configured — it defaults to the RFC 9728 location this router serves it at, so the header and the routes cannot drift apart. When the document is not served, the header stays a bare `Bearer` rather than naming a location with no route. The field exists for the one configuration where this router deliberately does not serve the document — an `oauthServer()` in the same deployment already answers that path, so this router is mounted without `resourceServerUrl`/`authorizationServerUrl` to avoid two routers on one path, and has nothing to derive from. Compute the value with `protectedResourceMetadataUrl` from [`@ttoss/auth-core`](https://ttoss.dev/docs/modules/packages/auth-core) rather than typing it, so both halves apply the same §3.1 rule.
 
 ```typescript
@@ -383,7 +383,7 @@ createMcpRouter(mcpServer, {
     resourceServerUrl: 'https://mcp.example.com',
     authorizationServerUrl:
       'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx',
-    // publicMethods defaults to ['initialize'].
+    // publicMethods defaults to ['initialize', 'server/discover'].
   },
 });
 ```
@@ -478,6 +478,78 @@ register({
 
 **`buildContext`** injects request-scoped values (DB clients, tenant IDs) into every handler call without threading them through each individual tool. It receives the full `ToolCallContext` so context can vary by identity or by call args.
 
+## MCP Apps (interactive UIs)
+
+The [`io.modelcontextprotocol/ui`](https://github.com/modelcontextprotocol/ext-apps) extension lets a tool result render as an interactive view instead of text. The view is a `ui://` resource holding an HTML document, which the host loads into a sandboxed iframe and talks to over `postMessage`; the tool points at it through its `_meta`.
+
+The extension asks nothing of the transport, so `createMcpRouter` serves it as-is on both protocol revisions. `registerAppResource` owns the parts that are easy to get wrong — the `ui://` scheme, the exact MIME type, `_meta.ui` on both the declaration and the read result, and the deprecated flat linkage key that is still legal until the extension reaches GA.
+
+```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, // a string, or ({ uri }) => string built per read
+  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,
+    };
+  }
+);
+```
+
+`toolMeta()` is the linkage for **every** registration path — `registerTool`, [`registerToolFromSchema`](#registertoolfromschemaserver-params), and a [`GatedToolDef`](#creategatedtoolregistraroptions) all take `_meta`:
+
+```typescript
+registerToolFromSchema(server, {
+  name: 'refresh-dashboard',
+  description: 'Refresh dashboard data',
+  // Callable by the view, hidden from the model.
+  _meta: dashboard.toolMeta({ visibility: ['app'] }),
+  handler: async () => ({ content: [{ type: 'text', text: 'refreshed' }] }),
+});
+```
+
+### Register the linkage unconditionally
+
+The spec suggests checking the client's declared capability before registering UI-enabled tools. Do not: that read is only reliable on the `2026-07-28` revision, where the capability arrives in each request's envelope. In this package's default [stateless mode](#stateless-vs-stateful-mode) there is no remembered `initialize` for a 2025-era client, so a capability-gated registration silently drops the view for every one of them.
+
+Declaring it always is also strictly more compatible — a host without Apps support ignores `_meta` and renders the tool's `content`, which is the extension's own graceful-degradation contract. Keep every tool's text result meaningful on its own and the fallback takes care of itself.
+
 ## Issuing tokens for MCP clients
 
 The `auth` option above covers the **resource-server** half of MCP authorization — it verifies tokens issued by an external authorization server (Cognito, Auth0, …). To make your own first-party server _issue_ the tokens an MCP client runs the full OAuth flow against, add the [`@ttoss/http-server-auth`](https://ttoss.dev/docs/modules/packages/http-server-auth) plugin's `oauthServer()` and pair it with `createMcpRouter({ auth: { verifyToken } })` so one deployment both issues and verifies tokens. See the [OAuth Authorization Server](https://ttoss.dev/docs/engineering/guidelines/oauth-authorization-server) guideline.
@@ -502,7 +574,7 @@ Creates a Koa router configured to handle MCP protocol requests.
     - `auth.verifyToken` — Custom async token verifier `(token: string) => Promise<unknown>`
     - `auth.requiredScopes` — Router-level scope guard; returns 403 if any scope is missing
     - `auth.resourceServerUrl` + `auth.authorizationServerUrl` — Enable the protected-resource metadata document, served at both `/.well-known/oauth-protected-resource` and the RFC 9728 path-derived `/.well-known/oauth-protected-resource<path>`; the metadata `resource` is set to `resourceServerUrl + path` so clients following `resource` land on the actual MCP endpoint
-    - `auth.publicMethods` — JSON-RPC methods that bypass verification (default `['initialize']`)
+    - `auth.publicMethods` — JSON-RPC methods that bypass verification (default `['initialize', 'server/discover']`)
     - `auth.resourceMetadataUrl` — URL advertised in the RFC 9728 `WWW-Authenticate: Bearer resource_metadata="…"` header on a 401. Defaults to the location derived from `resourceServerUrl` + `path` (the one this router serves), so the header cannot drift from the routes; set it only when a separate `oauthServer()` serves the document and this router is mounted without `resourceServerUrl`/`authorizationServerUrl`
     - `auth.resourceIndicator` — Expected `aud` value(s) (RFC 8707); rejects tokens minted for a different resource. See [Resource indicator validation](#resource-indicator-validation-rfc-8707)
 
@@ -582,6 +654,7 @@ The `GatedToolDef` passed to `register` has:
 - `requiredScope` — Single scope that must appear in `identity.scopes`.
 - `inputSchema` — Zod field map or `ZodObject`, forwarded to `server.registerTool`.
 - `gates` (`Array<(ctx: ToolCallContext) => void | Promise<void>>`, optional) — Per-tool guards appended after the global `gates`. Receive the full `ToolCallContext` enabling arg-conditional authorization.
+- `_meta` (`Record<string, unknown>`, optional) — Tool metadata forwarded verbatim on `tools/list`; how a gated tool links to an [MCP Apps](#mcp-apps-interactive-uis) view.
 - `method` — Async handler. Receives merged call args + `buildContext` output.
 
 **`ToolCallContext`** is the object passed to gates, `buildContext`, and `onError`:
@@ -590,6 +663,33 @@ The `GatedToolDef` passed to `register` has:
 - `args` (`Record<string, unknown>`) — The validated tool input (post SDK parse).
 - `handler` (`string`) — The tool name, for error attribution.
 
+### `registerAppResource(params)`
+
+Registers an [MCP Apps](#mcp-apps-interactive-uis) view: a `ui://` resource whose HTML a host renders for a linked tool's result.
+
+**Parameters (`params`):**
+
+- `server` (`McpServer`) — The MCP server to register the resource on.
+- `name` (`string`) — Resource name, as listed by `resources/list`.
+- `uri` (`string`) — Resource URI. Must use the `ui://` scheme, or the call throws.
+- `description` (`string`, optional) — What the view does and when a host should render it.
+- `html` (`string | ({ uri: URL }) => string | Promise<string>`) — The view's HTML5 document, or a builder invoked per `resources/read`.
+- `ui` (`UiResourceMeta`, optional) — Rendering and security configuration relayed to the host as `_meta.ui`:
+  - `csp` (`UiResourceCsp`) — Origins the view may reach, mapped onto the iframe's Content Security Policy: `connectDomains` (`connect-src`), `resourceDomains` (scripts/styles/images/fonts/media), `frameDomains` (`frame-src`), `baseUriDomains` (`base-uri`). An omitted list is the restrictive default, not "no restriction".
+  - `permissions` (`UiResourcePermissions`) — Browser capabilities requested for the view (`camera`, `microphone`, `geolocation`, `clipboardWrite`), each as `{}`. A host _may_ grant them, so feature-detect in the view rather than assuming.
+  - `domain` (`string`) — Dedicated sandbox origin, for views needing a stable one (OAuth callbacks, CORS, API key allowlists). The format is host-specific.
+  - `prefersBorder` (`boolean`) — Whether the host should draw a border and background around the view.
+
+**Returns:** `RegisteredAppResource`
+
+- `uri` (`string`) — The URI tools link to.
+- `resource` (`RegisteredResource`) — The SDK's registration handle, for `update`/`disable`/`remove`.
+- `toolMeta(params?)` — Builds the `_meta` bag linking a tool to this view, writing both `_meta.ui.resourceUri` and the deprecated flat `_meta['ui/resourceUri']`. Takes `visibility` (`Array<'model' | 'app'>`, optional — the spec's default is both) and `_meta` (`Record<string, unknown>`, optional) to merge further entries in.
+
+### `UI_EXTENSION_ID` / `UI_RESOURCE_MIME_TYPE`
+
+`'io.modelcontextprotocol/ui'` and `'text/html;profile=mcp-app'`. Use the first as the `capabilities.extensions` key when advertising Apps support on the `McpServer`, and the second as the MIME type a host negotiates.
+
 ### `registerToolFromSchema(server, params)`
 
 Registers a tool using a **plain JSON Schema** object for `inputSchema` instead of a Zod shape.
@@ -603,6 +703,7 @@ Use this when tool definitions are shared between the MCP server and an AI SDK a
 - `params.description` (`string`, optional) — Human-readable description
 - `params.inputSchema` (`JsonObjectSchema`, optional) — Plain JSON Schema object (defaults to `{ type: 'object', properties: {} }`)
 - `params.validateArguments` (`boolean`, optional) — Enforce `inputSchema` on `tools/call` (default: `false`); see [Argument validation](#argument-validation)
+- `params._meta` (`Record<string, unknown>`, optional) — Tool metadata forwarded verbatim on `tools/list`; how a tool links to an [MCP Apps](#mcp-apps-interactive-uis) view
 - `params.handler` (`(args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>`) — Tool handler receiving the raw request arguments
 
 **Returns:** `void`
@@ -873,7 +974,7 @@ expect(call.status).toBe(200);
 
 ### `publicMethods` and OAuth clients
 
-`auth.publicMethods` defaults to `['initialize']`: the handshake is reachable without a token, nothing else is.
+`auth.publicMethods` defaults to `['initialize', 'server/discover']`: the lifecycle handshake is reachable without a token, nothing else is. There are two entries because the exemption is about _the handshake_, not the method name — `initialize` is the 2025-era handshake and `server/discover` its `2026-07-28` replacement, since that revision removed `initialize` outright. Naming only one leaves the other era unable to negotiate at all.
 
 **Adding `tools/list` is a deliberate exposure.** It serves the full tool catalogue — every name, description, and input schema — to anyone who can reach the endpoint. Those leak internal resource names and domain vocabulary, and for an OpenAPI-derived server the schemas mirror the REST surface, so the catalogue becomes an unauthenticated map of the whole API including operations the caller could never invoke. It buys an OAuth client nothing, because the `401` is what starts the authorization flow and a client that lists tools anonymously still cannot call one. Open it only to serve callers that will never authenticate:
 
@@ -885,7 +986,7 @@ publicMethods: ['initialize', 'tools/list'],
 
 Either way the authorization flow works. Driving the official MCP client SDK against this router shows the RFC 9728 challenge resolving to the protected-resource document, the authorization server, and the redirect, whether the `401` arrives on `initialize` (`publicMethods: []`) or on the request after it (the default). `tests/unit/tests/oauth-client-flow.test.ts` asserts it.
 
-On the `2026-07-28` revision `initialize` does not exist — discovery is `server/discover`, which is not in the default set and therefore always requires a token. That is deliberate: RFC 9728 discovery is driven by the challenge itself.
+**Whether the handshake should be public at all is a separate question.** `publicMethods: []` closes both eras, and the authorization flow still works — RFC 9728 discovery is driven by the challenge itself, so a client authenticates from its very first request instead of one step later.
 
 ## AWS Lambda Deployment
 
@@ -954,3 +1055,4 @@ newest first.
 - [MCP Documentation](https://modelcontextprotocol.io)
 - [MCP Specification](https://spec.modelcontextprotocol.io/)
 - [MCP SDK TypeScript](https://github.com/modelcontextprotocol/typescript-sdk)
+- [MCP Apps extension (`io.modelcontextprotocol/ui`)](https://github.com/modelcontextprotocol/ext-apps)

package/dist/index.cjs

@@ -120,6 +120,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
 /**
@@ -163,7 +317,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
@@ -194,14 +348,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);
   });
@@ -316,7 +472,8 @@ var createGatedToolRegistrar = ({
     };
     server.registerTool(def.name, {
       description: def.description,
-      inputSchema: def.inputSchema
+      inputSchema: def.inputSchema,
+      _meta: def._meta
     }, handler);
   };
   return {
@@ -327,13 +484,23 @@ var createGatedToolRegistrar = ({
 //#endregion
 //#region src/index.ts
 /**
-* MCP lifecycle methods reachable before a client authenticates.
+* MCP lifecycle handshakes reachable before a client authenticates.
+*
+* One entry per protocol era, because the exemption the MCP authorization spec
+* sanctions is about *the handshake* — a client has to complete it before it
+* can discover the authorization server — not about a method name:
+*
+* - `initialize` is the 2025-era handshake.
+* - `server/discover` is its `2026-07-28` replacement. That revision removed
+*   `initialize` entirely, so naming only `initialize` left the modern era
+*   with no public method at all — the asymmetry ttoss/ttoss#1222 fixed.
+*
+* A future revision that renames the handshake again needs a matching entry
+* here; nothing detects that automatically.
 *
-* Only `initialize`, which the MCP authorization spec sanctions: a client has
-* to complete the handshake before it can discover the authorization server.
-* `tools/list` is not here — see {@link McpAuthOptions.publicMethods}.
+* `tools/list` is deliberately absent — see {@link McpAuthOptions.publicMethods}.
 */
-var DEFAULT_PUBLIC_METHODS = ["initialize"];
+var DEFAULT_PUBLIC_METHODS = ["initialize", "server/discover"];
 /**
 * Asserts that a verified token's `aud` claim includes at least one of the
 * expected resource indicator values. `aud` may be a single string or an
@@ -632,11 +799,14 @@ Object.defineProperty(exports, 'McpServer', {
     return _modelcontextprotocol_server.McpServer;
   }
 });
+exports.UI_EXTENSION_ID = UI_EXTENSION_ID;
+exports.UI_RESOURCE_MIME_TYPE = UI_RESOURCE_MIME_TYPE;
 exports.apiCall = apiCall;
 exports.checkScopes = checkScopes;
 exports.createGatedToolRegistrar = createGatedToolRegistrar;
 exports.createMcpRouter = createMcpRouter;
 exports.getIdentity = getIdentity;
+exports.registerAppResource = registerAppResource;
 exports.registerToolFromSchema = registerToolFromSchema;
 Object.defineProperty(exports, 'z', {
   enumerable: true,

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 
 /// <reference types="node" />
-import { CallToolResult, McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/server";
+import { CallToolResult, McpServer, McpServer as McpServer$1, RegisteredResource } from "@modelcontextprotocol/server";
 import { Router } from "@ttoss/http-server";
 import accepts from "accepts";
 import { AsyncLocalStorage } from "async_hooks";
@@ -675,6 +675,197 @@ declare namespace Application {
  */
 declare const getIdentity: <T = unknown>() => T | undefined;
 //#endregion
+//#region src/registerAppResource.d.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] },
+ *       },
+ *     },
+ *   }
+ * );
+ * ```
+ */
+declare const UI_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** MIME type every MCP Apps HTML resource is served as. */
+declare const UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+ * Origins an app's view is allowed to reach, mapped by the host onto the
+ * iframe's Content Security Policy. Anything not declared is blocked: an
+ * omitted list is the restrictive default, not "no restriction".
+ */
+interface UiResourceCsp {
+  /** Origins for network requests (`connect-src`). */
+  connectDomains?: string[];
+  /**
+   * Origins for scripts, styles, images, fonts and media (`script-src`,
+   * `style-src`, `img-src`, `font-src`, `media-src`).
+   */
+  resourceDomains?: string[];
+  /** Origins for nested iframes (`frame-src`). */
+  frameDomains?: string[];
+  /** Allowed document base URIs (`base-uri`). */
+  baseUriDomains?: string[];
+}
+/**
+ * Browser capabilities the view asks for. A host *may* grant them, so a view
+ * should feature-detect rather than assume: each key is a request, not a
+ * guarantee.
+ */
+interface UiResourcePermissions {
+  camera?: Record<string, never>;
+  microphone?: Record<string, never>;
+  geolocation?: Record<string, never>;
+  clipboardWrite?: Record<string, never>;
+}
+/** Rendering and security configuration for an app's view (`_meta.ui`). */
+interface UiResourceMeta {
+  /** Origins the view may reach; omitted means none. */
+  csp?: UiResourceCsp;
+  /** Browser capabilities requested for the view. */
+  permissions?: UiResourcePermissions;
+  /**
+   * Dedicated sandbox origin for the view, for cases needing a stable origin
+   * (OAuth callbacks, CORS, API key allowlists). The accepted format is
+   * host-specific; consult the host's documentation rather than deriving one.
+   */
+  domain?: string;
+  /** Whether the host should draw a border and background around the view. */
+  prefersBorder?: boolean;
+}
+/** Who may reach a tool. Defaults to both when left unset. */
+type UiToolVisibility = 'model' | 'app';
+/** Parameters for {@link registerAppResource}. */
+interface RegisterAppResourceParams {
+  /** The `McpServer` instance to register the app resource on. */
+  server: McpServer$1;
+  /** Resource name, as listed by `resources/list`. */
+  name: string;
+  /** Resource URI. Must use the `ui://` scheme. */
+  uri: string;
+  /** What the view does and when a host should render it. */
+  description?: string;
+  /**
+   * The view's HTML5 document, or a builder invoked per `resources/read`.
+   * A builder receives the requested URI so one registration can serve
+   * variants of a document.
+   */
+  html: string | ((args: {
+    uri: URL;
+  }) => string | Promise<string>);
+  /** Rendering and security configuration relayed to the host as `_meta.ui`. */
+  ui?: UiResourceMeta;
+}
+/** Parameters for {@link RegisteredAppResource.toolMeta}. */
+interface ToolMetaParams {
+  /**
+   * Who may reach the tool. Left unset, the spec's default applies — visible
+   * to the model *and* callable by the app.
+   */
+  visibility?: UiToolVisibility[];
+  /** Further `_meta` entries to merge in, e.g. vendor-namespaced keys. */
+  _meta?: Record<string, unknown>;
+}
+/** An app resource registered by {@link registerAppResource}. */
+interface RegisteredAppResource {
+  /** The URI tools link to. */
+  uri: string;
+  /** The SDK's registration handle, for `update`/`disable`/`remove`. */
+  resource: RegisteredResource;
+  /**
+   * Builds the `_meta` bag that links a tool to this view. Pass it to
+   * `registerTool`, {@link registerToolFromSchema}, or a `GatedToolDef` —
+   * whichever registration path the tool uses.
+   */
+  toolMeta: (params?: ToolMetaParams) => Record<string, unknown>;
+}
+/**
+ * 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,
+ *     };
+ *   }
+ * );
+ * ```
+ */
+declare const registerAppResource: ({
+  server,
+  name,
+  uri,
+  description,
+  html,
+  ui
+}: RegisterAppResourceParams) => RegisteredAppResource;
+//#endregion
 //#region src/registerToolFromSchema.d.ts
 /**
  * A plain JSON Schema object (draft-07 compatible) describing the shape of a
@@ -721,6 +912,19 @@ interface RegisterToolFromSchemaParams {
    * @default false
    */
   validateArguments?: boolean;
+  /**
+   * Tool metadata forwarded verbatim on `tools/list`.
+   *
+   * The MCP Apps extension links a tool to the view its result is rendered
+   * with through this field; build the bag with `toolMeta()` from
+   * `registerAppResource` rather than writing the keys by hand.
+   *
+   * @example
+   * ```typescript
+   * _meta: dashboard.toolMeta({ visibility: ['app'] }),
+   * ```
+   */
+  _meta?: Record<string, unknown>;
   /**
    * Tool handler invoked when the AI client calls the tool.
    * Receives the request arguments, validated against `inputSchema` only when
@@ -744,7 +948,7 @@ interface RegisterToolFromSchemaParams {
  *
  * @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
@@ -801,7 +1005,12 @@ type GatedToolDef = {
    * Each gate receives the full {@link ToolCallContext} (identity + args).
    * Throw to reject the call; return (or resolve) to continue.
    */
-  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>; /** The tool handler. Receives merged call args + `buildContext` output. */
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>;
+  /**
+   * Tool metadata forwarded verbatim on `tools/list` — how a gated tool links
+   * to an MCP Apps view (`registerAppResource(...).toolMeta()`).
+   */
+  _meta?: Record<string, unknown>; /** The tool handler. Receives merged call args + `buildContext` output. */
   method: (args: Record<string, unknown>) => Promise<unknown>;
 };
 /** Options for {@link createGatedToolRegistrar}. */
@@ -893,10 +1102,13 @@ interface McpAuthOptions {
   /**
    * JSON-RPC methods (read from `body.method`) that bypass verification.
    *
-   * `initialize` is public because the MCP authorization spec sanctions it: a
-   * client completes the lifecycle handshake before it can discover the
-   * authorization server. Nothing else is, so a server with `auth` configured
-   * serves no tool metadata to an unauthenticated caller.
+   * The lifecycle handshake is public because the MCP authorization spec
+   * sanctions it: a client completes it before it can discover the
+   * authorization server. That means one entry per protocol era —
+   * `initialize` on 2025, `server/discover` on `2026-07-28`, which removed
+   * `initialize` — so neither era is left unable to negotiate. Nothing else
+   * is public, so a server with `auth` configured serves no tool metadata to
+   * an unauthenticated caller.
    *
    * Opening `tools/list` is a deliberate choice, not a default. It serves the
    * full tool catalogue — every name, description, and input schema — to
@@ -907,7 +1119,7 @@ interface McpAuthOptions {
    * cannot call one. Set it only to serve callers that will never
    * authenticate.
    *
-   * @default ['initialize']
+   * @default ['initialize', 'server/discover']
    *
    * @example
    * ```typescript
@@ -1135,9 +1347,10 @@ interface McpRouterOptions {
    * OAuth / JWT authentication configuration for the MCP endpoint.
    *
    * When set, incoming MCP requests must include a valid Bearer token in the
-   * `Authorization` header — except for `publicMethods` (by default just
-   * `initialize`), which bypasses verification so a client can complete the
-   * lifecycle handshake before authenticating. Invalid or missing tokens
+   * `Authorization` header — except for `publicMethods` (by default the
+   * lifecycle handshake of each protocol era: `initialize` and
+   * `server/discover`), which bypass verification so a client can complete
+   * the handshake before authenticating. Invalid or missing tokens
    * receive a `401` response with `WWW-Authenticate: Bearer` (or
    * `Bearer resource_metadata="..."` when `resourceMetadataUrl` is set, per
    * RFC 9728). Tokens that fail a `requiredScopes` check receive `403`.
@@ -1206,4 +1419,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => Router<Application.DefaultState, Application.DefaultContext>;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterToolFromSchemaParams, type ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -2,7 +2,7 @@
 /// <reference types="node" />
 import { Router } from "@ttoss/http-server";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { CallToolResult, McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/server";
+import { CallToolResult, McpServer, McpServer as McpServer$1, RegisteredResource } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import accepts from "accepts";
 import { AsyncLocalStorage as AsyncLocalStorage$1 } from "async_hooks";
@@ -676,6 +676,197 @@ declare namespace Application {
  */
 declare const getIdentity: <T = unknown>() => T | undefined;
 //#endregion
+//#region src/registerAppResource.d.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] },
+ *       },
+ *     },
+ *   }
+ * );
+ * ```
+ */
+declare const UI_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** MIME type every MCP Apps HTML resource is served as. */
+declare const UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+ * Origins an app's view is allowed to reach, mapped by the host onto the
+ * iframe's Content Security Policy. Anything not declared is blocked: an
+ * omitted list is the restrictive default, not "no restriction".
+ */
+interface UiResourceCsp {
+  /** Origins for network requests (`connect-src`). */
+  connectDomains?: string[];
+  /**
+   * Origins for scripts, styles, images, fonts and media (`script-src`,
+   * `style-src`, `img-src`, `font-src`, `media-src`).
+   */
+  resourceDomains?: string[];
+  /** Origins for nested iframes (`frame-src`). */
+  frameDomains?: string[];
+  /** Allowed document base URIs (`base-uri`). */
+  baseUriDomains?: string[];
+}
+/**
+ * Browser capabilities the view asks for. A host *may* grant them, so a view
+ * should feature-detect rather than assume: each key is a request, not a
+ * guarantee.
+ */
+interface UiResourcePermissions {
+  camera?: Record<string, never>;
+  microphone?: Record<string, never>;
+  geolocation?: Record<string, never>;
+  clipboardWrite?: Record<string, never>;
+}
+/** Rendering and security configuration for an app's view (`_meta.ui`). */
+interface UiResourceMeta {
+  /** Origins the view may reach; omitted means none. */
+  csp?: UiResourceCsp;
+  /** Browser capabilities requested for the view. */
+  permissions?: UiResourcePermissions;
+  /**
+   * Dedicated sandbox origin for the view, for cases needing a stable origin
+   * (OAuth callbacks, CORS, API key allowlists). The accepted format is
+   * host-specific; consult the host's documentation rather than deriving one.
+   */
+  domain?: string;
+  /** Whether the host should draw a border and background around the view. */
+  prefersBorder?: boolean;
+}
+/** Who may reach a tool. Defaults to both when left unset. */
+type UiToolVisibility = 'model' | 'app';
+/** Parameters for {@link registerAppResource}. */
+interface RegisterAppResourceParams {
+  /** The `McpServer` instance to register the app resource on. */
+  server: McpServer$1;
+  /** Resource name, as listed by `resources/list`. */
+  name: string;
+  /** Resource URI. Must use the `ui://` scheme. */
+  uri: string;
+  /** What the view does and when a host should render it. */
+  description?: string;
+  /**
+   * The view's HTML5 document, or a builder invoked per `resources/read`.
+   * A builder receives the requested URI so one registration can serve
+   * variants of a document.
+   */
+  html: string | ((args: {
+    uri: URL;
+  }) => string | Promise<string>);
+  /** Rendering and security configuration relayed to the host as `_meta.ui`. */
+  ui?: UiResourceMeta;
+}
+/** Parameters for {@link RegisteredAppResource.toolMeta}. */
+interface ToolMetaParams {
+  /**
+   * Who may reach the tool. Left unset, the spec's default applies — visible
+   * to the model *and* callable by the app.
+   */
+  visibility?: UiToolVisibility[];
+  /** Further `_meta` entries to merge in, e.g. vendor-namespaced keys. */
+  _meta?: Record<string, unknown>;
+}
+/** An app resource registered by {@link registerAppResource}. */
+interface RegisteredAppResource {
+  /** The URI tools link to. */
+  uri: string;
+  /** The SDK's registration handle, for `update`/`disable`/`remove`. */
+  resource: RegisteredResource;
+  /**
+   * Builds the `_meta` bag that links a tool to this view. Pass it to
+   * `registerTool`, {@link registerToolFromSchema}, or a `GatedToolDef` —
+   * whichever registration path the tool uses.
+   */
+  toolMeta: (params?: ToolMetaParams) => Record<string, unknown>;
+}
+/**
+ * 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,
+ *     };
+ *   }
+ * );
+ * ```
+ */
+declare const registerAppResource: ({
+  server,
+  name,
+  uri,
+  description,
+  html,
+  ui
+}: RegisterAppResourceParams) => RegisteredAppResource;
+//#endregion
 //#region src/registerToolFromSchema.d.ts
 /**
  * A plain JSON Schema object (draft-07 compatible) describing the shape of a
@@ -722,6 +913,19 @@ interface RegisterToolFromSchemaParams {
    * @default false
    */
   validateArguments?: boolean;
+  /**
+   * Tool metadata forwarded verbatim on `tools/list`.
+   *
+   * The MCP Apps extension links a tool to the view its result is rendered
+   * with through this field; build the bag with `toolMeta()` from
+   * `registerAppResource` rather than writing the keys by hand.
+   *
+   * @example
+   * ```typescript
+   * _meta: dashboard.toolMeta({ visibility: ['app'] }),
+   * ```
+   */
+  _meta?: Record<string, unknown>;
   /**
    * Tool handler invoked when the AI client calls the tool.
    * Receives the request arguments, validated against `inputSchema` only when
@@ -745,7 +949,7 @@ interface RegisterToolFromSchemaParams {
  *
  * @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
@@ -802,7 +1006,12 @@ type GatedToolDef = {
    * Each gate receives the full {@link ToolCallContext} (identity + args).
    * Throw to reject the call; return (or resolve) to continue.
    */
-  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>; /** The tool handler. Receives merged call args + `buildContext` output. */
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>;
+  /**
+   * Tool metadata forwarded verbatim on `tools/list` — how a gated tool links
+   * to an MCP Apps view (`registerAppResource(...).toolMeta()`).
+   */
+  _meta?: Record<string, unknown>; /** The tool handler. Receives merged call args + `buildContext` output. */
   method: (args: Record<string, unknown>) => Promise<unknown>;
 };
 /** Options for {@link createGatedToolRegistrar}. */
@@ -894,10 +1103,13 @@ interface McpAuthOptions {
   /**
    * JSON-RPC methods (read from `body.method`) that bypass verification.
    *
-   * `initialize` is public because the MCP authorization spec sanctions it: a
-   * client completes the lifecycle handshake before it can discover the
-   * authorization server. Nothing else is, so a server with `auth` configured
-   * serves no tool metadata to an unauthenticated caller.
+   * The lifecycle handshake is public because the MCP authorization spec
+   * sanctions it: a client completes it before it can discover the
+   * authorization server. That means one entry per protocol era —
+   * `initialize` on 2025, `server/discover` on `2026-07-28`, which removed
+   * `initialize` — so neither era is left unable to negotiate. Nothing else
+   * is public, so a server with `auth` configured serves no tool metadata to
+   * an unauthenticated caller.
    *
    * Opening `tools/list` is a deliberate choice, not a default. It serves the
    * full tool catalogue — every name, description, and input schema — to
@@ -908,7 +1120,7 @@ interface McpAuthOptions {
    * cannot call one. Set it only to serve callers that will never
    * authenticate.
    *
-   * @default ['initialize']
+   * @default ['initialize', 'server/discover']
    *
    * @example
    * ```typescript
@@ -1136,9 +1348,10 @@ interface McpRouterOptions {
    * OAuth / JWT authentication configuration for the MCP endpoint.
    *
    * When set, incoming MCP requests must include a valid Bearer token in the
-   * `Authorization` header — except for `publicMethods` (by default just
-   * `initialize`), which bypasses verification so a client can complete the
-   * lifecycle handshake before authenticating. Invalid or missing tokens
+   * `Authorization` header — except for `publicMethods` (by default the
+   * lifecycle handshake of each protocol era: `initialize` and
+   * `server/discover`), which bypass verification so a client can complete
+   * the handshake before authenticating. Invalid or missing tokens
    * receive a `401` response with `WWW-Authenticate: Bearer` (or
    * `Bearer resource_metadata="..."` when `resourceMetadataUrl` is set, per
    * RFC 9728). Tokens that fail a `requiredScopes` check receive `403`.
@@ -1207,4 +1420,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => Router<Application.DefaultState, Application.DefaultContext>;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterToolFromSchemaParams, type ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };

package/dist/index.mjs

@@ -117,6 +117,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 +314,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 +345,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 +469,8 @@ var createGatedToolRegistrar = ({
     };
     server.registerTool(def.name, {
       description: def.description,
-      inputSchema: def.inputSchema
+      inputSchema: def.inputSchema,
+      _meta: def._meta
     }, handler);
   };
   return {
@@ -324,13 +481,23 @@ var createGatedToolRegistrar = ({
 //#endregion
 //#region src/index.ts
 /**
-* MCP lifecycle methods reachable before a client authenticates.
+* MCP lifecycle handshakes reachable before a client authenticates.
+*
+* One entry per protocol era, because the exemption the MCP authorization spec
+* sanctions is about *the handshake* — a client has to complete it before it
+* can discover the authorization server — not about a method name:
+*
+* - `initialize` is the 2025-era handshake.
+* - `server/discover` is its `2026-07-28` replacement. That revision removed
+*   `initialize` entirely, so naming only `initialize` left the modern era
+*   with no public method at all — the asymmetry ttoss/ttoss#1222 fixed.
+*
+* A future revision that renames the handshake again needs a matching entry
+* here; nothing detects that automatically.
 *
-* Only `initialize`, which the MCP authorization spec sanctions: a client has
-* to complete the handshake before it can discover the authorization server.
-* `tools/list` is not here — see {@link McpAuthOptions.publicMethods}.
+* `tools/list` is deliberately absent — see {@link McpAuthOptions.publicMethods}.
 */
-var DEFAULT_PUBLIC_METHODS = ["initialize"];
+var DEFAULT_PUBLIC_METHODS = ["initialize", "server/discover"];
 /**
 * Asserts that a verified token's `aud` claim includes at least one of the
 * expected resource indicator values. `aud` may be a single string or an
@@ -623,4 +790,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.0",
+  "version": "0.28.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",