Extensions Support + MCP Apps

[patvice]

What this branch delivers

This branch adds support for MCP Extensions and MCP Apps (UI extension) in ruby_llm-mcp.

• Extension capability registration + negotiation support
• MCP Apps/UI extension support (io.modelcontextprotocol/ui, with apps alias handling)
• apps_metadata parsing/accessors for tools, resources, and templates
• End-to-end runnable MCP Apps example app in examples/mcp_app

How to use it

1) Enable MCP Apps extension globally

RubyLLM::MCP.configure do |config|
  config.extensions.enable_apps(
    "mimeTypes" => ["text/html;profile=mcp-app"]
  )
end

2) Connect a client (full extension advertisement)

client = RubyLLM::MCP.client(
  name: "mcp-app-server",
  adapter: :ruby_llm,
  transport_type: :stdio,
  config: {
    command: "npm",
    args: ["--prefix", "examples/mcp_app/test_server", "run", "start:stdio"]
  }
)

3) Read MCP Apps metadata from tools/resources

tool = client.tool("render_items_embed")
puts tool.apps_metadata.resource_uri
puts tool.apps_metadata.visibility.inspect

resource = client.resource("ui_shell")
puts resource.apps_metadata.domain
puts resource.apps_metadata.permissions.inspect

4) Optional per-client override (alias accepted)

client = RubyLLM::MCP.client(
  name: "special-app-server",
  adapter: :ruby_llm,
  transport_type: :streamable,
  config: {
    url: "https://example.com/mcp",
    extensions: {
      "io.modelcontextprotocol/apps" => {
        "mimeTypes" => ["text/html;profile=mcp-app", "text/html"]
      }
    }
  }
)

Docs changes (highlights)

• Added a new Extensions docs section: /docs/extensions/index.md
  • Covers extension registration, canonical IDs, merge/override behavior, and adapter negotiation rules.
• Added dedicated MCP Apps extension docs: /docs/extensions/mcp-apps.md
  • Covers config.extensions.enable_apps, capability-vs-metadata separation, and apps_metadata accessors.
• Added a practical guide: /docs/guides/mcp-apps.md
  • Step-by-step setup, metadata inspection, render/action loop pattern, and common pitfalls.
• Reshaped getting-started/navigation docs to surface extensions and MCP Apps earlier (/docs/getting-started/*, /docs/index.md, /docs/guides/index.md).
• Added MCP Apps example screenshot: /docs/assets/images/mcp-app-working-example.png.

Example app

Included a runnable end-to-end example at examples/mcp_app:

• Rails app consuming MCP tools
• Local TypeScript MCP server over stdio
• Demonstrates both tool actions and MCP Apps iframe UI flow

Spec references

• MCP Extensions Overview
• MCP Apps