7d9fda4360
## Motivation and Context SEP-1865 "MCP Apps - Interactive User Interfaces for MCP" is Final on the Extensions Track: (https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865) an optional extension, negotiated through the SEP-2133 `capabilities.extensions` mechanism, that lets a server ship HTML user interfaces which the host renders for tool results. The normative spec lives in the ext-apps repository (`specification/2026-01-26/apps.mdx`). The Python SDK implements it in-SDK (python-sdk#3003, the `Apps` extension); the TypeScript ecosystem ships it as the separate `@modelcontextprotocol/ext-apps` package on top of the core SDK's SEP-2133 support. Server-side support is a thin convention layer over primitives this SDK already has (SEP-2133 extension capabilities, `_meta` on tools and resources, free-form resource URIs and MIME types). New `MCP::Apps` module: - Wire vocabulary constants shared with the reference implementations: `EXTENSION_ID` (`"io.modelcontextprotocol/ui"` - note `/ui`, not `/apps`), `RESOURCE_MIME_TYPE` (`"text/html;profile=mcp-app"`), `URI_SCHEME` (`"ui://"`), and the legacy flat meta key `RESOURCE_URI_META_KEY` (`"ui/resourceUri"`). - `Apps.capability(mime_types:)` builds the `capabilities.extensions` fragment for `support_extensions` on the server or `connect` on the client. - `Apps.ui_resource(uri:, name:, ...)` builds an `MCP::Resource` for a UI template, enforcing the spec's MUSTs (a `ui://` URI; the parameterized HTML MIME type by default). - `Apps.tool_meta(resource_uri:, visibility:, meta:, legacy:)` builds the `_meta.ui.resourceUri` linkage (optionally also emitting the legacy flat alias, matching the reference server helper that keeps both shapes in sync), merged non-destructively into caller-supplied meta. - `Apps.client_supports?(client_capabilities, mime_type:)` gates the text-only fallback the extension requires for clients that did not declare the capability (symbol/string tolerant). Everything else the extension defines (the sandboxed iframe, the `ui/*` postMessage bridge methods, consent for UI-initiated calls) is HOST responsibility and out of scope for a server SDK; a server only ever receives ordinary `resources/read` and `tools/call` requests. The README section states this boundary. Resolves #376. ## How Has This Been Tested? New `test/mcp/apps_test.rb` pins the wire vocabulary and covers the capability fragment, `ui_resource` scheme validation and MIME default, `tool_meta` non-destructive merging, visibility, the legacy alias, and `client_supports?` across symbol/string keys, mimeTypes narrowing, and missing declarations. New integration tests in `test/mcp/server_test.rb` drive a full server: the `initialize` result advertises the extension, tools/list serializes `_meta.ui.resourceUri`, `resources/read` serves the HTML template, and `client_supports?` distinguishes hosts with and without the declared extension. `bundle exec rake` (tests, RuboCop, and conformance baseline) passes. Also verified end-to-end over stdio: a client connecting with the extension declared negotiates the capability, discovers the tool linkage via `_meta.ui.resourceUri`, and reads the `ui://` template as `text/html;profile=mcp-app` content. ## Breaking Changes None. Purely additive helper module; no existing code paths change.
69 lines
3 KiB
Ruby
69 lines
3 KiB
Ruby
# frozen_string_literal: true
|
|
|
|
require "test_helper"
|
|
|
|
module MCP
|
|
class AppsTest < ActiveSupport::TestCase
|
|
test "exposes the SEP-1865 wire vocabulary" do
|
|
# The exact strings are shared with the reference ext-apps package and the Python SDK.
|
|
assert_equal "io.modelcontextprotocol/ui", Apps::EXTENSION_ID
|
|
assert_equal "text/html;profile=mcp-app", Apps::RESOURCE_MIME_TYPE
|
|
assert_equal "ui://", Apps::URI_SCHEME
|
|
assert_equal "ui/resourceUri", Apps::RESOURCE_URI_META_KEY
|
|
end
|
|
|
|
test ".capability builds the extensions fragment" do
|
|
assert_equal({ "io.modelcontextprotocol/ui" => { mimeTypes: ["text/html;profile=mcp-app"] } }, Apps.capability)
|
|
assert_equal({ "io.modelcontextprotocol/ui" => { mimeTypes: ["text/html"] } }, Apps.capability(mime_types: ["text/html"]))
|
|
end
|
|
|
|
test ".ui_resource builds a Resource with the spec defaults and validates the scheme" do
|
|
resource = Apps.ui_resource(uri: "ui://weather/dashboard", name: "dashboard", description: "Weather UI")
|
|
|
|
assert_instance_of Resource, resource
|
|
assert_equal "ui://weather/dashboard", resource.uri
|
|
assert_equal "text/html;profile=mcp-app", resource.mime_type
|
|
assert_equal "Weather UI", resource.description
|
|
assert_raises(ArgumentError) do
|
|
Apps.ui_resource(uri: "file:///dashboard.html", name: "dashboard")
|
|
end
|
|
end
|
|
|
|
test ".tool_meta links a tool to its template without clobbering caller meta" do
|
|
meta = Apps.tool_meta(
|
|
resource_uri: "ui://weather/dashboard",
|
|
visibility: ["model", "app"],
|
|
meta: { custom: "value" },
|
|
)
|
|
|
|
assert_equal({ custom: "value", ui: { resourceUri: "ui://weather/dashboard", visibility: ["model", "app"] } }, meta)
|
|
assert_raises(ArgumentError) do
|
|
Apps.tool_meta(resource_uri: "https://example.com")
|
|
end
|
|
end
|
|
|
|
test ".tool_meta emits the legacy flat key when requested" do
|
|
meta = Apps.tool_meta(resource_uri: "ui://weather/dashboard", legacy: true)
|
|
|
|
assert_equal "ui://weather/dashboard", meta.dig(:ui, :resourceUri)
|
|
assert_equal "ui://weather/dashboard", meta[:"ui/resourceUri"]
|
|
end
|
|
|
|
test ".client_supports? checks the declared extension and mime types" do
|
|
declared = { extensions: { "io.modelcontextprotocol/ui" => { mimeTypes: ["text/html;profile=mcp-app"] } } }
|
|
string_keys = {
|
|
"extensions" => { "io.modelcontextprotocol/ui" => { "mimeTypes" => ["text/html;profile=mcp-app"] } },
|
|
}
|
|
without_mime_types = { extensions: { "io.modelcontextprotocol/ui" => {} } }
|
|
other_mime_type = { extensions: { "io.modelcontextprotocol/ui" => { mimeTypes: ["text/html"] } } }
|
|
|
|
assert Apps.client_supports?(declared)
|
|
assert Apps.client_supports?(string_keys)
|
|
assert Apps.client_supports?(without_mime_types)
|
|
refute Apps.client_supports?(other_mime_type)
|
|
refute Apps.client_supports?({})
|
|
refute Apps.client_supports?(nil)
|
|
refute Apps.client_supports?({ extensions: {} })
|
|
end
|
|
end
|
|
end
|