feat: add MCP Apps support (renders_ui DSL, weather dashboard demo)

crisnahine · crisnahine · commit 4113d325d822 · 2026-04-15T18:34:23.000+08:00
per ext-apps draft spec (2026-01-26). closes #202. - ActionMCP::MIME_TYPE_APP_HTML constant for text/html;profile=mcp-app. - renders_ui "ui://..." class macro on Tool with optional visibility kwarg. validates URI scheme and visibility values at class-load time. emits nested _meta.ui.resourceUri only. no legacy flat _meta["ui/resourceUri"] key anywhere, pinned by a negative test. - Capability#client_supports_ui? instance helper for tools that want to degrade for hosts not advertising the extension. key-presence check, not value truthiness. the spec requires mimeTypes inside the value but validating that payload is not this helper's job. - weather dashboard resource template at ui://weather/dashboard with self-contained HTML, csp connectDomains, and prefersBorder. the demo intentionally emits _meta.ui on both the listing entry and the content item so both wire placements stay covered by tests. per spec, content-level takes precedence. - existing weather tool gets renders_ui. text and structured output are preserved. per apps.mdx, tools/list filtering by visibility is host-side; no server-side filter is added. ToolsRegistry.items is snapshotted and restored in setup/teardown for the new test file. Class.new(ActionMCP::Tool) fires the inherited hook before abstract! can run, which briefly leaks the unnamed class under the "" key; the snapshot/restore pattern neutralizes it and matches the existing approach in resource_template_test.rb.
diff --git a/lib/action_mcp.rb b/lib/action_mcp.rb
@@ -41,6 +41,11 @@ class StructuredContentValidationError < StandardError; end
 
   LATEST_VERSION = SUPPORTED_VERSIONS.first.freeze
   DEFAULT_PROTOCOL_VERSION = "2025-06-18" # Default to previous stable version for backwards compatibility
+
+  # MCP Apps extension (ext-apps, draft 2026-01-26).
+  # Canonical MIME type for UI resources rendered by host-side sandboxes.
+  # See ext-apps apps.mdx, Resource Content Types section.
+  MIME_TYPE_APP_HTML = "text/html;profile=mcp-app"
   class << self
     # Returns a Rack-compatible application for serving MCP requests
     # @return [#call] A Rack application that can be used with `run ActionMCP.server`
diff --git a/lib/action_mcp/capability.rb b/lib/action_mcp/capability.rb
@@ -32,6 +32,21 @@ def session
 
     delegate :session_data, to: :session, allow_nil: true
 
+    # Returns true when the current client advertises the MCP Apps UI extension
+    # (`capabilities.extensions["io.modelcontextprotocol/ui"]` in the initialize
+    # request). Returns false when there is no session, no stored capabilities,
+    # or the extension key is absent. Never raises.
+    #
+    # We check key presence rather than value truthiness. An empty hash under
+    # the extension key still counts as "supported". The spec requires
+    # `mimeTypes` inside the value (ext-apps apps.mdx, Client<>Server Capability
+    # Negotiation section), but validating that payload is not this helper's
+    # responsibility.
+    def client_supports_ui?
+      extensions = session&.client_capabilities&.dig("extensions")
+      extensions.is_a?(Hash) && extensions.key?("io.modelcontextprotocol/ui")
+    end
+
     # use _capability_name or default_capability_name
     def self.capability_name
       _capability_name || default_capability_name
diff --git a/lib/action_mcp/tool.rb b/lib/action_mcp/tool.rb
@@ -187,6 +187,45 @@ def meta(data = nil)
         end
       end
 
+      # Declares that this tool renders an MCP Apps UI resource. Host reads
+      # `_meta.ui.resourceUri` from the tool listing and renders the referenced
+      # `ui://` resource in a sandboxed iframe. See ext-apps apps.mdx.
+      #
+      # @param resource_uri [String] URI starting with `ui://`
+      # @param visibility [Array<Symbol, String>, nil] subset of [:model, :app].
+      #   When omitted, no visibility key is emitted and the host applies the
+      #   spec default.
+      def renders_ui(resource_uri, visibility: nil)
+        unless resource_uri.is_a?(String) && resource_uri.match?(%r{\Aui://\S+\z})
+          raise ArgumentError,
+                "renders_ui requires a String URI starting with ui://, got: #{resource_uri.inspect}"
+        end
+
+        ui_meta = { resourceUri: resource_uri }
+
+        if visibility
+          unless visibility.is_a?(Array) && !visibility.empty?
+            raise ArgumentError,
+                  "renders_ui visibility must be a non-empty Array, got: #{visibility.inspect}"
+          end
+
+          normalized = visibility.map(&:to_s)
+          invalid = normalized - %w[model app]
+          unless invalid.empty?
+            raise ArgumentError,
+                  "renders_ui visibility values must be one of model, app - got: #{invalid.inspect}"
+          end
+          if normalized.uniq != normalized
+            raise ArgumentError,
+                  "renders_ui visibility contains duplicates: #{visibility.inspect}"
+          end
+
+          ui_meta[:visibility] = normalized
+        end
+
+        self._meta = _meta.merge(ui: ui_meta)
+      end
+
       # Marks this tool as requiring consent before execution
       def requires_consent!
         self._requires_consent = true
diff --git a/test/action_mcp/mcp_apps_test.rb b/test/action_mcp/mcp_apps_test.rb
@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module ActionMCP
+  class McpAppsTest < ActiveSupport::TestCase
+    def setup
+      @original_tool_items = ActionMCP::ToolsRegistry.items.dup
+    end
+
+    def teardown
+      ActionMCP::ToolsRegistry.instance_variable_set(:@items, @original_tool_items)
+    end
+
+    def build_tool(&block)
+      klass = Class.new(ActionMCP::Tool)
+      klass.define_singleton_method(:name) { "RendersUiTempTool#{SecureRandom.hex(4)}" }
+      klass.abstract!
+      klass.tool_name "renders_ui_temp_#{SecureRandom.hex(4)}"
+      klass.description "temp"
+      klass.class_eval(&block) if block
+      klass
+    end
+
+    test "renders_ui serializes resourceUri under _meta.ui" do
+      klass = build_tool { renders_ui "ui://widgets/panel", visibility: %i[model app] }
+
+      assert_equal(
+        { ui: { resourceUri: "ui://widgets/panel", visibility: [ "model", "app" ] } },
+        klass.to_h[:_meta]
+      )
+    end
+
+    test "renders_ui rejects non-ui:// URI" do
+      assert_raises(ArgumentError) { build_tool { renders_ui "http://widgets/panel" } }
+      assert_raises(ArgumentError) { build_tool { renders_ui "" } }
+    end
+
+    class StubSession
+      attr_reader :client_capabilities
+
+      def initialize(capabilities)
+        @client_capabilities = capabilities
+      end
+    end
+
+    class CapabilityProbe < ActionMCP::Capability
+    end
+
+    test "client_supports_ui? is true when the extension key is present" do
+      caps = { "extensions" => { "io.modelcontextprotocol/ui" => {} } }
+      instance = CapabilityProbe.new.with_context(session: StubSession.new(caps))
+
+      assert instance.client_supports_ui?
+    end
+
+    test "client_supports_ui? is false when the extension key is absent" do
+      instance = CapabilityProbe.new.with_context(session: StubSession.new("tools" => {}))
+
+      refute instance.client_supports_ui?
+    end
+
+    test "weather tool declares renders_ui pointing at the dashboard" do
+      assert_equal "ui://weather/dashboard", WeatherTool.to_h.dig(:_meta, :ui, :resourceUri)
+    end
+
+    test "weather dashboard resolve returns HTML content with _meta" do
+      instance = WeatherDashboardTemplate.new({})
+      response = instance.call
+
+      refute response.error?
+      content = response.contents.first
+      assert_equal ActionMCP::MIME_TYPE_APP_HTML, content.mime_type
+      refute_empty content.text
+      assert content._meta[:ui][:prefersBorder]
+    end
+  end
+end
diff --git a/test/dummy/app/mcp/resource_templates/weather_dashboard_template.rb b/test/dummy/app/mcp/resource_templates/weather_dashboard_template.rb
@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+class WeatherDashboardTemplate < ApplicationMCPResTemplate
+  description "Interactive weather dashboard UI for the weather tool"
+  uri_template "ui://weather/dashboard"
+  mime_type ActionMCP::MIME_TYPE_APP_HTML
+
+  # The spec (ext-apps apps.mdx, Metadata Location section) allows _meta.ui on
+  # both the listing entry and the content item, with content-level taking
+  # precedence. We intentionally emit both so the demo exercises each placement
+  # and the wire shape stays visible to the tests.
+  meta ui: {
+    csp: { connectDomains: %w[api.openweathermap.org] },
+    prefersBorder: true
+  }
+
+  HTML = <<~HTML
+    <!doctype html>
+    <html lang="en">
+    <head>
+      <meta charset="utf-8">
+      <title>Weather</title>
+      <style>
+        :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+        body { margin: 0; padding: 1.25rem; }
+        .card { max-width: 28rem; padding: 1rem 1.25rem; border-radius: 0.75rem;
+                background: color-mix(in srgb, currentColor 6%, transparent); }
+        h1 { margin: 0 0 0.5rem; font-size: 1.25rem; }
+        .temp { font-size: 3rem; font-weight: 600; line-height: 1; }
+        .row { display: flex; gap: 1rem; margin-top: 0.75rem; font-size: 0.9rem;
+               opacity: 0.8; }
+        .icon { font-size: 2.5rem; }
+      </style>
+    </head>
+    <body>
+      <div class="card" role="region" aria-label="Weather summary">
+        <h1 id="loc">Weather</h1>
+        <div class="icon" aria-hidden="true">\u2600\ufe0f</div>
+        <div class="temp"><span id="temp">--</span>&deg;</div>
+        <div class="row">
+          <div>Humidity <span id="hum">--</span>%</div>
+          <div>Wind <span id="wind">--</span> km/h</div>
+        </div>
+      </div>
+      <script>
+        (function () {
+          function set(id, v) { var el = document.getElementById(id); if (el) el.textContent = v; }
+          window.addEventListener("message", function (event) {
+            var data = event.data && event.data.result;
+            if (!data || !data.current) return;
+            if (data.metadata && data.metadata.location_found) set("loc", data.metadata.location_found);
+            set("temp", Math.round(data.current.temperature));
+            set("hum", data.current.humidity);
+            set("wind", data.current.wind_speed);
+          });
+        }());
+      </script>
+    </body>
+    </html>
+  HTML
+
+  def resolve
+    ActionMCP::Content::Resource.new(
+      self.class.uri_template,
+      ActionMCP::MIME_TYPE_APP_HTML,
+      text: HTML,
+      _meta: {
+        ui: {
+          csp: { connectDomains: %w[api.openweathermap.org] },
+          prefersBorder: true
+        }
+      }
+    )
+  end
+end
diff --git a/test/dummy/app/mcp/tools/weather_tool.rb b/test/dummy/app/mcp/tools/weather_tool.rb
@@ -4,6 +4,8 @@ class WeatherTool < ApplicationMCPTool
   tool_name "weather"
   description "Get weather information for a location with structured output"
 
+  renders_ui "ui://weather/dashboard"
+
   # Input properties (existing pattern)
   property :location, type: "string", required: true, description: "City name or coordinates"
   property :units, type: "string", default: "celsius", enum: [ "celsius", "fahrenheit" ], description: "Temperature units"
