Move the Documentation From README.md to the Documentation Site

Move the documentation that had grown to 3,000+ lines in README.md onto https://ruby.sdk.modelcontextprotocol.io/
and slim the README down to a quick start and feature overview, following the Python SDK layout:

- Add 20 server pages as the docs/_server/ collection (overview plus transports, discovery, tools, prompts, resources,
  roots, sampling, elicitation, multi round-trip results, notifications, notification subscriptions, cancellation,
  progress, ping, completions, logging, pagination, server context, and configuration), 8 client pages as
  the docs/_client/ collection (overview, transports, lifecycle, multi round-trip results, cancellation, ping, pagination,
  and authorization), and 3 advanced pages as the docs/_advanced/ collection (capability extensions, MCP Apps,
  and custom methods) - one page per topic, ordered to match the sidebar of the 2026-07-28 specification,
  with the client-side APIs (pinging, cancelling, and paginating from MCP::Client) documented under Building Clients
- Add top-level Examples and Protocol Versions pages after Installation, linking the runnable examples in examples/
  and summarizing the supported protocol versions, the era model, and client negotiation
- Render the three sections as just-the-docs collections, which list every page beneath a plain category heading in
  the sidebar with no folding, and serve every page at an extensionless URL under /server/, /client/, and /advanced/,
  matching the sibling SDK documentation sites
- Replace docs/building-servers.md and docs/building-clients.md with redirects to the new section overview pages via
  jekyll-redirect-from, redirect the previously published /installation.html to its extensionless URL,
  fold their content that was missing from README.md into the new pages, and update the Tool argument keys reference comment
  in lib/mcp/server.rb to the relocated Tools page
- Reduce README.md to the badges, installation instructions, a stdio server and client quick start,
  a link-free feature overview in the Python SDK style, the conformance testing section, and a License section,
  using absolute URLs for the remaining repository links so they resolve on rubygems.org
- Adapt formatting where GitHub rendering habits break on the site: convert the numbered "three ways to define" lists into headings,
  since kramdown restarts numbering at 1 when code blocks split list items, convert GitHub-style alerts into just-the-docs callouts
  with the SEP-2260 server-to-client association note raised to a red warning, merge the duplicated Exception Reporting
  and Configuration Block Data sections into the Configuration page, and relocate the Streamable HTTP settings that were nested under
  the Logging section into the Transports page
- Refresh the migrated content against the current implementation: correct stale claims and broken examples the README carried,
  note on each session-era feature how it relates to the modern lifecycle of MCP 2026-07-28, and point spec links at the latest revision,
  keeping deliberate 2025-11-25 pins for pages the modern revision removed
- Style the site after the Rails API documentation palette (red links and accents on neutral surfaces) with matching light
  and dark color schemes, center the sidebar and content as one block, add a Previous/Next footer pager following the sidebar order,
  open external links in a new tab, and serve the MCP logo as the favicon

Every code block and heading from the previous README was verified to have a home in the new docs pages or the slimmed README
before the reduction; a few examples were corrected rather than copied, as noted above.

Author: koic

README.md

@@ -0,0 +1,35 @@
+---
+layout: default
+title: Capability Extensions
+nav_order: 1
+---
+
+# Capability Extensions
+
+Per SEP-2133, both clients and servers can declare protocol extensions under the `extensions` member of their capabilities.
+Keys are extension identifiers using the reverse-DNS prefix convention (e.g. `"io.modelcontextprotocol/tasks"`, `"com.example/feature"`);
+values are extension-defined configuration objects, with `{}` meaning "supported with no settings".
+
+On the server, declare extensions through the `capabilities` keyword, either as a plain hash or via the `MCP::Server::Capabilities` builder:
+
+```ruby
+capabilities = MCP::Server::Capabilities.new
+capabilities.support_tools
+capabilities.support_extensions("com.example/feature" => { enabled: true })
+
+server = MCP::Server.new(name: "my_server", capabilities: capabilities)
+```
+
+The declared extensions appear in the `initialize` result's `capabilities.extensions`. Extensions the client declared during `initialize` are
+readable via `server.client_capabilities[:extensions]` (or `session.client_capabilities[:extensions]` for per-session transports).
+
+On the [modern lifecycle](/server/discovery/), the same declarations appear in the `server/discover` result,
+and the client's extensions ride each request's `_meta` envelope instead of an `initialize` handshake.
+Inside a handler, `server_context.client_capabilities[:extensions]` reads the current request's declarations
+with envelope-first resolution, on either lifecycle.
+
+On the client, pass extensions through `connect`:
+
+```ruby
+client.connect(capabilities: { extensions: { "com.example/feature" => {} } })
+```

docs/_advanced/capability-extensions.md

@@ -0,0 +1,62 @@
+---
+layout: default
+title: Custom Methods
+nav_order: 3
+---
+
+# Custom Methods
+
+The server allows you to define custom JSON-RPC methods beyond the standard MCP protocol methods using the `define_custom_method` method:
+
+```ruby
+server = MCP::Server.new(name: "my_server")
+
+# Define a custom method that returns a result
+server.define_custom_method(method_name: "add") do |params|
+  params[:a] + params[:b]
+end
+
+# Define a custom notification method (returns nil)
+server.define_custom_method(method_name: "notify") do |params|
+  # Process notification
+  nil
+end
+```
+
+**Key Features:**
+
+- Accepts any method name as a string
+- Block receives the request parameters as a hash
+- Can handle both regular methods (with responses) and notifications
+- Prevents overriding existing MCP protocol methods
+- Supports instrumentation callbacks for monitoring
+- Blocks may opt in to a `server_context:` keyword like the built-in handlers
+  (see [Cancellation](/server/cancellation/) for an example)
+
+**Usage Example:**
+
+The wire exchange for the custom `add` method defined above. The client sends:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "add",
+  "params": { "a": 5, "b": 3 }
+}
+```
+
+The server responds:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": 8
+}
+```
+
+**Error Handling:**
+
+- Raises `MCP::Server::MethodAlreadyDefinedError` if trying to override an existing method
+- Supports the same exception reporting and instrumentation as standard methods

docs/_advanced/custom-methods.md

@@ -0,0 +1,48 @@
+---
+layout: default
+title: MCP Apps
+nav_order: 2
+---
+
+# MCP Apps
+
+MCP Apps (SEP-1865) is a Final extension (negotiated via [Capability Extensions](/advanced/capability-extensions/)) that lets a server ship interactive
+HTML user interfaces which the host renders for tool results. On the server side the extension is a thin convention,
+and `MCP::Apps` provides the vocabulary and helpers:
+
+```ruby
+capabilities = MCP::Server::Capabilities.new
+capabilities.support_tools
+capabilities.support_resources
+capabilities.support_extensions(MCP::Apps.capability) # { "io.modelcontextprotocol/ui" => { mimeTypes: [...] } }
+
+server = MCP::Server.new(
+  name: "weather_server",
+  capabilities: capabilities,
+  # UI templates are ordinary resources with a `ui://` URI and the `text/html;profile=mcp-app` MIME type.
+  resources: [MCP::Apps.ui_resource(uri: "ui://weather-server/dashboard", name: "weather_dashboard")],
+)
+
+server.resources_read_handler do |params|
+  [{ uri: params[:uri], mimeType: MCP::Apps::RESOURCE_MIME_TYPE, text: "<html>...</html>" }]
+end
+
+# Link the tool to its template via `_meta.ui.resourceUri` (pass `legacy: true` to also
+# emit the older flat `"ui/resourceUri"` alias for hosts that predate the Final spec).
+server.define_tool(
+  name: "get_weather",
+  meta: MCP::Apps.tool_meta(resource_uri: "ui://weather-server/dashboard"),
+) do |server_context:|
+  # The extension is optional: always return a meaningful text result, and use
+  # `MCP::Apps.client_supports?` when UI-capable clients should get richer structured content.
+  MCP::Apps.client_supports?(server_context.client_capabilities) # => true when the host declared the extension
+  MCP::Tool::Response.new([{ type: "text", text: "Sunny, 22 degrees Celsius" }])
+end
+```
+
+`MCP::Apps.tool_meta` also accepts `visibility:` (an array of `"model"` / `"app"`) to restrict who sees the tool,
+and merges non-destructively into caller-supplied `meta:`.
+
+Everything else the extension defines (the sandboxed iframe, the `ui/*` postMessage bridge, consent for UI-initiated actions)
+is the HOST's responsibility; a server only ever receives ordinary `resources/read` and `tools/call` requests.
+See the [MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx).