|
| 1 | +# frozen_string_literal: true |
| 2 | + |
| 3 | +module MCP |
| 4 | + # Server-side helpers for the MCP Apps extension (SEP-1865, Extensions Track, Final): |
| 5 | + # interactive user interfaces delivered as `ui://` HTML template resources that hosts |
| 6 | + # render for tool results. The extension is negotiated per SEP-2133 through |
| 7 | + # `capabilities.extensions` on both sides; a server declares {EXTENSION_ID}, registers |
| 8 | + # UI templates as ordinary resources, and links tools to templates via `_meta`. |
| 9 | + # |
| 10 | + # Everything else defined by the extension (the sandboxed iframe, the `ui/*` |
| 11 | + # postMessage bridge methods, consent for UI-initiated calls) is HOST responsibility: |
| 12 | + # a server only ever receives ordinary `resources/read` and `tools/call` requests. |
| 13 | + # |
| 14 | + # Because the extension is optional, a UI-enabled tool MUST still return a meaningful |
| 15 | + # text-only result for clients that did not declare the capability; |
| 16 | + # use {Apps.client_supports?} to branch. |
| 17 | + # |
| 18 | + # @example Declaring an Apps-enabled server |
| 19 | + # capabilities = MCP::Server::Capabilities.new |
| 20 | + # capabilities.support_tools |
| 21 | + # capabilities.support_resources |
| 22 | + # capabilities.support_extensions(MCP::Apps.capability) |
| 23 | + # server = MCP::Server.new( |
| 24 | + # name: "weather_server", |
| 25 | + # capabilities: capabilities, |
| 26 | + # resources: [MCP::Apps.ui_resource(uri: "ui://weather-server/dashboard", name: "weather_dashboard")], |
| 27 | + # ) |
| 28 | + # server.define_tool( |
| 29 | + # name: "get_weather", |
| 30 | + # meta: MCP::Apps.tool_meta(resource_uri: "ui://weather-server/dashboard"), |
| 31 | + # ) { |server_context:| ... } |
| 32 | + # |
| 33 | + # https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx |
| 34 | + module Apps |
| 35 | + # Reverse-DNS extension identifier (note: `/ui`, not `/apps`), shared wire vocabulary with |
| 36 | + # the reference `@modelcontextprotocol/ext-apps` package and the Python SDK's `Apps` extension. |
| 37 | + EXTENSION_ID = "io.modelcontextprotocol/ui" |
| 38 | + # UI template resources MUST use this parameterized MIME type. |
| 39 | + RESOURCE_MIME_TYPE = "text/html;profile=mcp-app" |
| 40 | + # UI template resource URIs MUST use this scheme. |
| 41 | + URI_SCHEME = "ui://" |
| 42 | + # Legacy flat `_meta` key linking a tool to its template; the canonical shape is |
| 43 | + # the nested `_meta.ui.resourceUri`. {Apps.tool_meta} can emit both. |
| 44 | + RESOURCE_URI_META_KEY = "ui/resourceUri" |
| 45 | + |
| 46 | + extend self |
| 47 | + |
| 48 | + # The `capabilities.extensions` fragment advertising Apps support. Pass to |
| 49 | + # `MCP::Server::Capabilities.new(extensions: ...)` or `support_extensions(...)`, |
| 50 | + # or merge into a client's `connect(capabilities: { extensions: ... })`. |
| 51 | + def capability(mime_types: [RESOURCE_MIME_TYPE]) |
| 52 | + { EXTENSION_ID => { mimeTypes: mime_types } } |
| 53 | + end |
| 54 | + |
| 55 | + # Builds an `MCP::Resource` for a UI template, enforcing the spec's MUSTs: |
| 56 | + # a `ui://` URI and the `text/html;profile=mcp-app` MIME type by default. |
| 57 | + def ui_resource(uri:, name:, mime_type: RESOURCE_MIME_TYPE, **rest) |
| 58 | + unless uri.is_a?(String) && uri.start_with?(URI_SCHEME) |
| 59 | + raise ArgumentError, "MCP Apps template URIs must start with #{URI_SCHEME.inspect} (got #{uri.inspect})" |
| 60 | + end |
| 61 | + |
| 62 | + Resource.new(uri: uri, name: name, mime_type: mime_type, **rest) |
| 63 | + end |
| 64 | + |
| 65 | + # Builds the tool `_meta` linking a tool to its UI template, merged non-destructively into |
| 66 | + # caller-supplied `meta`. `visibility` restricts who sees the tool (an array of `"model"` / `"app"`). |
| 67 | + # `legacy: true` also writes the flat `"ui/resourceUri"` alias, matching the reference server helper |
| 68 | + # that keeps both key shapes in sync for older hosts. |
| 69 | + def tool_meta(resource_uri:, visibility: nil, meta: nil, legacy: false) |
| 70 | + unless resource_uri.is_a?(String) && resource_uri.start_with?(URI_SCHEME) |
| 71 | + raise ArgumentError, "resource_uri must start with #{URI_SCHEME.inspect} (got #{resource_uri.inspect})" |
| 72 | + end |
| 73 | + |
| 74 | + ui_entry = { resourceUri: resource_uri } |
| 75 | + ui_entry[:visibility] = visibility if visibility |
| 76 | + |
| 77 | + merged = (meta || {}).merge(ui: ui_entry) |
| 78 | + merged[RESOURCE_URI_META_KEY.to_sym] = resource_uri if legacy |
| 79 | + merged |
| 80 | + end |
| 81 | + |
| 82 | + # Whether the client declared Apps support for `mime_type` in its `capabilities.extensions` |
| 83 | + # (symbol or string keys). UI-enabled tools use this to fall back to a text-only result for |
| 84 | + # clients without the extension. |
| 85 | + def client_supports?(client_capabilities, mime_type: RESOURCE_MIME_TYPE) |
| 86 | + extensions = read_key(client_capabilities, :extensions) |
| 87 | + declaration = read_key(extensions, EXTENSION_ID) |
| 88 | + return false unless declaration.is_a?(Hash) |
| 89 | + |
| 90 | + mime_types = read_key(declaration, :mimeTypes) |
| 91 | + |
| 92 | + # A declaration without mimeTypes advertises the extension without narrowing. |
| 93 | + return true if mime_types.nil? |
| 94 | + |
| 95 | + mime_types.is_a?(Array) && mime_types.include?(mime_type) |
| 96 | + end |
| 97 | + |
| 98 | + private |
| 99 | + |
| 100 | + def read_key(hash, key) |
| 101 | + return unless hash.is_a?(Hash) |
| 102 | + |
| 103 | + value = hash[key.to_sym] |
| 104 | + value.nil? ? hash[key.to_s] : value |
| 105 | + end |
| 106 | + end |
| 107 | +end |
0 commit comments