mcp 0.22.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0e0cdbc945ee9ec5d178aeaedb1c8af84eca0bae8db8e264f523b47b8d67c52
-  data.tar.gz: 6acb2d299d9ae215c26db733091ebbcbb3f6b1477c94d9b4047f9ab37c3a8f0c
+  metadata.gz: 4773bb2a9b8bce187692737d82d8ba204da880a68255258bc1bc697ee994d356
+  data.tar.gz: e27c758cacba095342a7b8a7b1feb7299298773d0399676f5ee3827322765fd5
 SHA512:
-  metadata.gz: 8299a6cf0101d4b8b980a69ed3128636aae6f0497fb431d14fdc0f6b8b659fb18ab5d886cf1cb567c53f385a4f8c0cdaf5e91aff6d1a4fe4daefca25d17a7dc2
-  data.tar.gz: dff4075f2a0fdf27329af3455b1db6960e38f557ea2436388f1a271d6915172e318b9630ccc8312fab16e3e8ac42e0dc84ef20e974b313056d377f3798d4a83c
+  metadata.gz: 83c6b8ab2f63916f03f6d79a5e0f8e572f828d5153f0ee3dcb43e002c97b46a9e686959dd0e8e46a620b5155b456739a4ffd78dc51093898c56ddf2c6a21f99c
+  data.tar.gz: 46687cedce187961437298f5d9d4a807e058099a8c8e4f7793473999eb79a4dc70cf3a9cceaad8a3c8df4c20e4bebc85e7995844f413e64c6d4109918ffa856f

data/README.md

@@ -46,6 +46,8 @@ It implements the Model Context Protocol specification, handling model context r
 ### Supported Methods
 
 - `initialize` - Initializes the protocol and returns server capabilities
+- `server/discover` - Sessionless capability discovery (MCP 2026-07-28 draft, SEP-2575): returns `supportedVersions`, `capabilities`, `serverInfo`,
+  and `instructions`, and responds before `initialize` and without an `Mcp-Session-Id`
 - `ping` - Simple health check
 - `logging/setLevel` - Configures the minimum log level for the server
 - `tools/list` - Lists all registered tools and their schemas
@@ -102,6 +104,8 @@ transport = MCP::Server::Transports::StdioTransport.new(server)
 transport.open
 ```
 
+`StdioTransport.new` accepts an optional `max_line_bytes:` keyword that caps the byte length of a single newline-delimited request frame. A frame that reaches this limit without a newline is rejected and the connection is closed, preventing unbounded memory growth from a peer that never emits a newline. It defaults to `4 * 1024 * 1024` (4 MiB).
+
 You can run this script and then type in requests to the server at the command line.
 
 ```console
@@ -128,6 +132,27 @@ The following examples show two common integration styles in Rails.
 >
 > Stateless mode (`stateless: true`) does not use sessions and works with any server configuration.
 
+> [!IMPORTANT]
+> Per MCP 2025-11-25, `StreamableHTTPTransport` validates the `Host` and `Origin` headers by default to
+> prevent DNS rebinding attacks against locally bound servers, rejecting unauthorized values with HTTP 403.
+> `Host` is allowed for the loopback defaults (`127.0.0.1`, `::1`, `localhost`), and an `Origin` header,
+> when present, must be same-origin or explicitly allow-listed. Non-browser clients that send no `Origin`
+> header are unaffected.
+>
+> Deployments behind a reverse proxy or bound to a non-loopback interface must widen the allow lists:
+>
+> ```ruby
+> transport = MCP::Server::Transports::StreamableHTTPTransport.new(
+>   server,
+>   allowed_hosts: ["mcp.example.com"],
+>   allowed_origins: ["https://app.example.com"],
+> )
+> ```
+>
+> An `allowed_hosts:` entry matches either the bare host name (any port) or the full `host:port` value,
+> so both `"mcp.example.com"` and `"mcp.example.com:8443"` work. Pass `dns_rebinding_protection: false`
+> to disable the check entirely (e.g., when an upstream proxy or middleware already validates `Host`/`Origin`).
+
 ##### Rails (mount)
 
 `StreamableHTTPTransport` is a Rack app that can be mounted directly in Rails routes:
@@ -155,6 +180,8 @@ end
 the [MCP Streamable HTTP transport spec](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http),
 so no additional route configuration is needed.
 
+A complete runnable application using this approach is available in [`examples/rails`](examples/rails).
+
 ##### Rails (controller)
 
 While the mount approach creates a single server at boot time, the controller approach creates a new server per request.
@@ -256,6 +283,46 @@ On the client, pass extensions through `connect`:
 client.connect(capabilities: { extensions: { "com.example/feature" => {} } })
 ```
 
+### MCP Apps (SEP-1865)
+
+MCP Apps is a Final extension (negotiated via the Capability Extensions mechanism above) 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.client_capabilities) # => true when the host declared the extension
+  MCP::Tool::Response.new([{ type: "text", text: "Sunny, 22 degrees Celsius" }])
+end
+```
+
+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).
+
 ### Server Context and Configuration Block Data
 
 #### `server_context`
@@ -949,7 +1016,71 @@ MCP spec includes [Resources](https://modelcontextprotocol.io/specification/late
 
 ### Reading Resources
 
-The `MCP::Resource` class provides a way to register resources with the server.
+Like tools and prompts, resources can be defined in three ways.
+
+1. As a class that inherits from `MCP::Resource`, implementing `contents` to serve the resource body:
+
+```ruby
+class MyResource < MCP::Resource
+  uri "https://example.com/my_resource"
+  resource_name "my-resource"
+  title "My Resource"
+  description "Lorem ipsum dolor sit amet"
+  mime_type "text/html"
+
+  class << self
+    def contents
+      [MCP::Resource::TextContents.new(
+        uri: uri,
+        mime_type: mime_type,
+        text: "Hello from example resource!"
+      )]
+    end
+  end
+end
+
+server = MCP::Server.new(
+  name: "my_server",
+  resources: [MyResource],
+)
+```
+
+`resources/read` requests are routed automatically: when the requested URI matches a registered
+class-based resource, its `contents` method is called. `contents` may return an array of
+`MCP::Resource::TextContents` / `MCP::Resource::BlobContents` objects (or plain hashes), or a single one.
+Like tools, `contents` can opt in to a `server_context:` keyword argument to receive per-request context.
+
+When class-based resources or resource templates are registered and a `resources/read` request
+does not match any of them, the server responds with the standard JSON-RPC Invalid Params error
+(`-32602`) carrying the requested URI in the error `data` member, per SEP-2164.
+
+2. With the `MCP::Resource.define` method, whose block implements `contents`:
+
+```ruby
+resource = MCP::Resource.define(
+  uri: "https://example.com/my_resource",
+  name: "my-resource",
+  mime_type: "text/html",
+) do
+  [MCP::Resource::TextContents.new(uri: uri, mime_type: mime_type, text: "Hello!")]
+end
+```
+
+3. Using the `MCP::Server#define_resource` method:
+
+```ruby
+server = MCP::Server.new(name: "my_server")
+server.define_resource(
+  uri: "https://example.com/my_resource",
+  name: "my-resource",
+  mime_type: "text/html",
+) do
+  [MCP::Resource::TextContents.new(uri: "https://example.com/my_resource", mime_type: "text/html", text: "Hello!")]
+end
+```
+
+Alternatively, resources can be registered as plain data objects with `MCP::Resource.new`,
+in which case the server only lists them:
 
 ```ruby
 resource = MCP::Resource.new(
@@ -966,7 +1097,8 @@ server = MCP::Server.new(
 )
 ```
 
-The server must register a handler for the `resources/read` method to retrieve a resource dynamically.
+With plain data resources, the server must register a handler for the `resources/read` method to
+retrieve a resource dynamically.
 
 ```ruby
 server.resources_read_handler do |params|
@@ -978,7 +1110,8 @@ server.resources_read_handler do |params|
 end
 ```
 
-otherwise `resources/read` requests will be a no-op.
+otherwise `resources/read` requests will be a no-op. Note that a `resources_read_handler` fully replaces
+the default `resources/read` handling, including the automatic routing to class-based resources described above.
 
 For unknown URIs, raise `MCP::Server::ResourceNotFoundError` from the handler.
 Per SEP-2164, the server then responds with the standard JSON-RPC Invalid Params error (`-32602`)
@@ -995,7 +1128,63 @@ end
 
 ### Resource Templates
 
-The `MCP::ResourceTemplate` class provides a way to register resource templates with the server.
+Resource templates follow the same pattern. Class-based templates declare a `uri_template` and
+receive the variables extracted from the requested URI as keyword arguments to `contents`:
+
+```ruby
+class UserProfileTemplate < MCP::ResourceTemplate
+  uri_template "users://{user_id}/profile"
+  resource_template_name "user-profile"
+  title "User Profile"
+  description "Profile data for a user"
+  mime_type "application/json"
+
+  class << self
+    def contents(user_id:)
+      [MCP::Resource::TextContents.new(
+        uri: "users://#{user_id}/profile",
+        mime_type: mime_type,
+        text: { id: user_id }.to_json
+      )]
+    end
+  end
+end
+
+server = MCP::Server.new(
+  name: "my_server",
+  resource_templates: [UserProfileTemplate],
+)
+```
+
+A `resources/read` request for `users://42/profile` calls `UserProfileTemplate.contents(user_id: "42")`.
+An exact match against a registered resource takes precedence over template matching.
+`contents` can also opt in to a `server_context:` keyword argument.
+
+URI template matching supports simple [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570) level 1 `{variable}` expressions only:
+
+- Operator expressions such as `{+path}`, `{#fragment}`, or `{?query}` are treated as literal text and never match an expanded URI.
+- A variable matches one or more characters excluding `/`.
+- Extracted values are not percent-decoded.
+
+The `MCP::ResourceTemplate.define` and `MCP::Server#define_resource_template` methods are also available,
+mirroring the resource variants:
+
+```ruby
+server.define_resource_template(
+  uri_template: "users://{user_id}/profile",
+  name: "user-profile",
+  mime_type: "application/json",
+) do |user_id:|
+  [MCP::Resource::TextContents.new(
+    uri: "users://#{user_id}/profile",
+    mime_type: "application/json",
+    text: { id: user_id }.to_json
+  )]
+end
+```
+
+Resource templates can also be registered as plain data objects with `MCP::ResourceTemplate.new`,
+in which case reads must be served by a `resources_read_handler`:
 
 ```ruby
 resource_template = MCP::ResourceTemplate.new(
@@ -1023,6 +1212,12 @@ Roots define the boundaries of where a server can operate, providing a list of d
 - **Client Capability**: Clients must declare `roots` capability during initialization
 - **Change Notifications**: Clients that support `roots.listChanged` send `notifications/roots/list_changed` when roots change
 
+> [!NOTE]
+> Per SEP-2260, server-to-client requests (`roots/list`, `sampling/createMessage`, `elicitation/create`) must be associated with
+> an originating client request (`ping` is exempt). Use the `server_context` passed to your handler, which stamps the association
+> automatically and routes the request onto the originating POST stream on the Streamable HTTP transport. Calling the corresponding
+> `ServerSession` methods without `related_request_id:` still works but emits a deprecation warning.
+
 **Using Roots in Tools:**
 
 Tools that accept a `server_context:` parameter can call `list_roots` on it.
@@ -1758,12 +1953,58 @@ Session-scoped standalone notifications (`resources/updated`, `elicitation/compl
 broadcast notifications (`tools/list_changed`, etc.) still flow to clients connected to the GET SSE stream.
 This mode is suitable for simple tool servers that do not need server-initiated requests.
 
-By default, sessions do not expire. To mitigate session hijacking risks, you can set a `session_idle_timeout` (in seconds).
-When configured, sessions that receive no HTTP requests for this duration are automatically expired and cleaned up:
+By default, stateful sessions are bounded so an `initialize` flood cannot retain sessions until memory is exhausted:
+they expire after `session_idle_timeout` seconds of inactivity (default 1800, i.e. 30 minutes) and the concurrent
+session count is capped at `max_sessions` (default 10000). A session's idle timer is reset by activity that touches it
+(a GET, or a regular-request POST), and expired sessions are collected by a background reaper roughly once a minute,
+so cleanup lags inactivity by up to that interval. At the cap, the transport first reclaims any already-expired slots
+and then, if still full, rejects a new `initialize` with HTTP 503 (it does not evict an existing session).
+
+```ruby
+# Tune the limits
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 900, max_sessions: 5000)
+
+# Opt out of expiry and/or the cap (not recommended on internet-facing deployments)
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: nil, max_sessions: nil)
+```
+
+Stateless mode (`stateless: true`) retains no sessions, so neither limit applies to it.
+
+#### Session Ownership
+
+`StreamableHTTPTransport` issues a random `SecureRandom.uuid` session ID and validates incoming requests by session
+existence and idle timeout only. It does not bind a session to a user, because the transport never receives
+an authenticated identity on its own. A caller that obtains a valid session ID could therefore act on that session,
+so binding a session to a user is the deploying application's responsibility (the MCP spec frames this as a SHOULD).
+
+The primary control is the `session_request_validator`. It is called as `->(request, session_id) { true | false }`
+on every non-`initialize` POST, GET, and DELETE against an existing session (including notification and response POSTs,
+so a stolen session ID cannot, for example, POST `notifications/cancelled` against a victim's request). A falsy return
+rejects the request with HTTP 403. Use it to compare the request's authenticated principal against the one recorded
+when the session was created:
+
+```ruby
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(
+  server,
+  session_request_validator: ->(request, session_id) { owns_session?(request, session_id) },
+)
+```
+
+Without a validator the transport does not enforce ownership. As a limited defense in depth (not authentication),
+it also records the `Origin` header at `initialize` and rejects a later request whose `Origin` differs, but only
+when both are present - a non-browser client that omits `Origin` (e.g. `curl` or a script) is not stopped by this check.
+Enforcing ownership against a determined attacker requires supplying the validator with an authenticated principal.
+
+#### Request Size Limits
+
+`StreamableHTTPTransport` bounds how many bytes a single POST body may allocate, so a peer cannot exhaust memory
+with one oversized message. A body larger than `max_request_bytes` (default 4 MiB) is rejected with HTTP 413,
+and JSON nesting depth is capped. The 4 MiB default comfortably fits a typical JSON-RPC message (a 4 MiB JSON
+string decodes to roughly 3 MiB of base64 payload) and matches the TypeScript SDK's 4 MB default; raise it only
+if you exchange unusually large payloads:
 
 ```ruby
-# Session timeout of 30 minutes
-transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 1800)
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, max_request_bytes: 8 * 1024 * 1024)
 ```
 
 ### Pagination
@@ -1850,6 +2091,40 @@ tools = client.tools # => Array<MCP::Client::Tool> of every tool on the server.
 Use these when you want the complete list; use `list_tools(cursor:)` etc. when you need
 fine-grained iteration (e.g. to stream-process pages without loading everything into memory).
 
+#### List Result Caching (`ttlMs` / `cacheScope`)
+
+Per SEP-2549, list and read results can carry cache hints telling clients how long a result stays fresh (`ttlMs`, max-age semantics in milliseconds;
+`0` means do not cache) and whether shared intermediaries may cache it (`cacheScope`: `"public"` or `"private"`).
+
+Emission is opt-in: pass `ttl_ms:` and/or `cache_scope:` to `MCP::Server.new` and both fields are added to `tools/list`, `prompts/list`, `resources/list`,
+`resources/templates/list`, and `resources/read` results (a missing field is filled with the defaults `ttlMs: 0` / `cacheScope: "public"`).
+When neither is set, responses are serialized exactly as before.
+
+```ruby
+server = MCP::Server.new(
+  name: "my_server",
+  tools: tools,
+  ttl_ms: 60_000,        # results stay fresh for one minute
+  cache_scope: "private", # only the requesting client may cache them
+)
+```
+
+A `resources_read_handler` can override the hints per result by returning a full result hash instead of bare contents:
+
+```ruby
+server.resources_read_handler do |params|
+  { contents: [{ uri: params[:uri], mimeType: "text/plain", text: "..." }], ttlMs: 5_000 }
+end
+```
+
+On the client, the values are surfaced on the paginated result structs as `ttl_ms` and `cache_scope`:
+
+```ruby
+page = client.list_tools
+page.ttl_ms      # => 60000 (nil when the server sent no hint)
+page.cache_scope # => "private"
+```
+
 ### Advanced
 
 #### Custom Methods
@@ -1958,6 +2233,7 @@ Use the `MCP::Client::Stdio` transport to interact with MCP servers running as s
 | `args:` | No | An array of arguments passed to the command. Defaults to `[]`. |
 | `env:` | No | A hash of environment variables to set for the server process. Defaults to `nil`. |
 | `read_timeout:` | No | Timeout in seconds for waiting for a server response. Defaults to `nil` (no timeout). |
+| `max_line_bytes:` | No | Maximum byte length of a single newline-delimited response frame. A frame that reaches this limit without a newline is rejected as a transport error, preventing unbounded memory growth from a server that never emits a newline. Defaults to `4 * 1024 * 1024` (4 MiB). |
 
 Example usage:
 
@@ -2042,6 +2318,30 @@ response = client.call_tool(
 
 The server will send `notifications/progress` back to the client during execution.
 
+#### Server-to-Client Requests (Elicitation)
+
+Servers can send requests back to the client while one of the client's own requests is in flight - for example,
+[`elicitation/create`](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation) to ask the user for additional input during a tool call.
+Register a handler and advertise the capability on `connect` to respond to them:
+
+```ruby
+client.connect(capabilities: { elicitation: {} })
+
+client.on_elicitation do |params|
+  {
+    action: "accept",
+    # Fill fields omitted by the user with the schema's `default` values (SEP-1034)
+    content: MCP::Client::Elicitation.apply_defaults(params["requestedSchema"]),
+  }
+end
+```
+
+Registering a handler opens a standalone HTTP GET SSE stream on a background thread
+([listening for messages from the server](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#listening-for-messages-from-the-server)),
+since servers deliver requests that are not tied to a client request on that stream. Server requests with no registered handler are answered with
+a JSON-RPC `-32601` (method not found) error. To handle methods other than `elicitation/create`, register directly on the transport with
+`http_transport.on_server_request("method/name") { |params| ... }`.
+
 #### HTTP Authorization
 
 By default, the HTTP transport layer provides no authentication to the server, but you can provide custom headers if you need authentication. For example, to use Bearer token authentication:
@@ -2118,13 +2418,17 @@ Required keyword arguments to `Provider.new`:
   an explicit value always wins.
 - `redirect_uri`: String. Must use HTTPS or be a loopback URL (`localhost`, `127.0.0.0/8`, `::1`); other values raise `Provider::InsecureRedirectURIError`.
 - `redirect_handler`: Callable invoked with the fully-built authorization `URI`. Typically opens the user's browser.
-- `callback_handler`: Callable that returns `[code, state]` after the user is redirected back to `redirect_uri`.
+- `callback_handler`: Callable that returns `[code, state]` or `[code, state, iss]` after the user is redirected back to `redirect_uri`. Returning the 3-element form
+  (with `iss` set to the RFC 9207 `iss` parameter from the redirect, or `nil` when absent) opts into SEP-2468 issuer validation: a present `iss` must match
+  the authorization server's issuer, and a missing one is rejected when the server advertises `authorization_response_iss_parameter_supported`.
 
 Optional keyword arguments:
 
 - `scope`: Space-separated scopes to request when the server's `WWW-Authenticate` does not specify one.
 - `storage`: Object responding to `tokens`, `save_tokens(t)`, `client_information`, `save_client_information(info)`. Defaults to `MCP::Client::OAuth::InMemoryStorage`,
-  which keeps credentials in process memory only.
+  which keeps credentials in process memory only. Persisted `client_information` is stamped with an `"issuer"` member binding it to the authorization server that
+  issued it (SEP-2352): when the server's authorization server changes, the SDK discards the stale registration and its tokens and re-registers automatically
+  (portable CIMD `client_id`s are kept). Treat the hash as opaque and persist it as-is.
 - `client_id_metadata_document_url`: URL where you publish a Client ID Metadata Document
   (`draft-ietf-oauth-client-id-metadata-document` and the MCP authorization specification).
   When the authorization server advertises `client_id_metadata_document_supported: true`,
@@ -2232,6 +2536,16 @@ The client provides a wrapper class for tools returned by the server:
 
 This class provides easy access to tool properties like name, description, input schema, and output schema.
 
+### Multi-Round-Trip Results (Experimental, SEP-2322)
+
+The MCP 2026-07-28 draft replaces in-flight server-to-client requests with Multi Round-Trip Requests: instead of issuing `sampling/createMessage`, `roots/list`,
+or `elicitation/create` while a request is being processed, a server may answer with a result whose `resultType` is `"input_required"`, carrying an `inputRequests` map
+and an opaque `requestState`; the client fulfills the requests and re-issues the original request with `inputResponses` and the echoed `requestState`.
+
+The Ruby client recognizes such results and raises `MCP::Client::InputRequiredError` instead of returning them as if they were final. The error exposes `input_requests`, `request_state`,
+and the raw `result`; automatic resumption is not implemented yet, so callers respond manually if they opt into the draft flow. `MCP::ResultType::COMPLETE` and `MCP::ResultType::INPUT_REQUIRED`
+are provided for forward compatibility. Servers on stable protocol versions never send `resultType`, so existing behavior is unchanged.
+
 ## Conformance Testing
 
 The `conformance/` directory contains a test server and runner that validate the SDK against the MCP specification using [`@modelcontextprotocol/conformance`](https://github.com/modelcontextprotocol/conformance).

data/lib/json_rpc_handler.rb

@@ -63,12 +63,29 @@ module JsonRpcHandler
         message: "Parse error",
         data: "Invalid JSON",
       })
+    rescue StandardError
+      # Last-resort guard so an unexpected handling error returns a JSON-RPC error
+      # instead of escaping to the transport loop.
+      response = error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::INTERNAL_ERROR,
+        message: "Internal error",
+      })
     end
 
     response&.to_json
   end
 
   def process_request(request, id_validation_pattern:, &method_finder)
+    # A batch element can be any JSON value; a non-object element cannot carry an id or a method,
+    # so reject it before the `request[:id]` access below.
+    unless request.is_a?(Hash)
+      return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::INVALID_REQUEST,
+        message: "Invalid Request",
+        data: "Request must be an object",
+      })
+    end
+
     id = request[:id]
 
     error = if !valid_version?(request[:jsonrpc])

data/lib/mcp/apps.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module MCP
+  # Server-side helpers for the MCP Apps extension (SEP-1865, Extensions Track, Final):
+  # interactive user interfaces delivered as `ui://` HTML template resources that hosts
+  # render for tool results. The extension is negotiated per SEP-2133 through
+  # `capabilities.extensions` on both sides; a server declares {EXTENSION_ID}, registers
+  # UI templates as ordinary resources, and links tools to templates via `_meta`.
+  #
+  # Everything else defined by the extension (the sandboxed iframe, the `ui/*`
+  # postMessage bridge methods, consent for UI-initiated calls) is HOST responsibility:
+  # a server only ever receives ordinary `resources/read` and `tools/call` requests.
+  #
+  # Because the extension is optional, a UI-enabled tool MUST still return a meaningful
+  # text-only result for clients that did not declare the capability;
+  # use {Apps.client_supports?} to branch.
+  #
+  # @example Declaring an Apps-enabled server
+  #   capabilities = MCP::Server::Capabilities.new
+  #   capabilities.support_tools
+  #   capabilities.support_resources
+  #   capabilities.support_extensions(MCP::Apps.capability)
+  #   server = MCP::Server.new(
+  #     name: "weather_server",
+  #     capabilities: capabilities,
+  #     resources: [MCP::Apps.ui_resource(uri: "ui://weather-server/dashboard", name: "weather_dashboard")],
+  #   )
+  #   server.define_tool(
+  #     name: "get_weather",
+  #     meta: MCP::Apps.tool_meta(resource_uri: "ui://weather-server/dashboard"),
+  #   ) { |server_context:|
+  #     ...
+  #   }
+  #
+  # https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
+  module Apps
+    # Reverse-DNS extension identifier (note: `/ui`, not `/apps`), shared wire vocabulary with
+    # the reference `@modelcontextprotocol/ext-apps` package and the Python SDK's `Apps` extension.
+    EXTENSION_ID = "io.modelcontextprotocol/ui"
+    # UI template resources MUST use this parameterized MIME type.
+    RESOURCE_MIME_TYPE = "text/html;profile=mcp-app"
+    # UI template resource URIs MUST use this scheme.
+    URI_SCHEME = "ui://"
+    # Legacy flat `_meta` key linking a tool to its template; the canonical shape is
+    # the nested `_meta.ui.resourceUri`. {Apps.tool_meta} can emit both.
+    RESOURCE_URI_META_KEY = "ui/resourceUri"
+
+    extend self
+
+    # The `capabilities.extensions` fragment advertising Apps support. Pass to
+    # `MCP::Server::Capabilities.new(extensions: ...)` or `support_extensions(...)`,
+    # or merge into a client's `connect(capabilities: { extensions: ... })`.
+    def capability(mime_types: [RESOURCE_MIME_TYPE])
+      { EXTENSION_ID => { mimeTypes: mime_types } }
+    end
+
+    # Builds an `MCP::Resource` for a UI template, enforcing the spec's MUSTs:
+    # a `ui://` URI and the `text/html;profile=mcp-app` MIME type by default.
+    def ui_resource(uri:, name:, mime_type: RESOURCE_MIME_TYPE, **rest)
+      unless uri.is_a?(String) && uri.start_with?(URI_SCHEME)
+        raise ArgumentError, "MCP Apps template URIs must start with #{URI_SCHEME.inspect} (got #{uri.inspect})"
+      end
+
+      Resource.new(uri: uri, name: name, mime_type: mime_type, **rest)
+    end
+
+    # Builds the tool `_meta` linking a tool to its UI template, merged non-destructively into
+    # caller-supplied `meta`. `visibility` restricts who sees the tool (an array of `"model"` / `"app"`).
+    # `legacy: true` also writes the flat `"ui/resourceUri"` alias, matching the reference server helper
+    # that keeps both key shapes in sync for older hosts.
+    def tool_meta(resource_uri:, visibility: nil, meta: nil, legacy: false)
+      unless resource_uri.is_a?(String) && resource_uri.start_with?(URI_SCHEME)
+        raise ArgumentError, "resource_uri must start with #{URI_SCHEME.inspect} (got #{resource_uri.inspect})"
+      end
+
+      ui_entry = { resourceUri: resource_uri }
+      ui_entry[:visibility] = visibility if visibility
+
+      merged = (meta || {}).merge(ui: ui_entry)
+      merged[RESOURCE_URI_META_KEY.to_sym] = resource_uri if legacy
+      merged
+    end
+
+    # Whether the client declared Apps support for `mime_type` in its `capabilities.extensions`
+    # (symbol or string keys). UI-enabled tools use this to fall back to a text-only result for
+    # clients without the extension.
+    def client_supports?(client_capabilities, mime_type: RESOURCE_MIME_TYPE)
+      extensions = read_key(client_capabilities, :extensions)
+      declaration = read_key(extensions, EXTENSION_ID)
+      return false unless declaration.is_a?(Hash)
+
+      mime_types = read_key(declaration, :mimeTypes)
+
+      # A declaration without mimeTypes advertises the extension without narrowing.
+      return true if mime_types.nil?
+
+      mime_types.is_a?(Array) && mime_types.include?(mime_type)
+    end
+
+    private
+
+    def read_key(hash, key)
+      return unless hash.is_a?(Hash)
+
+      value = hash[key.to_sym]
+      value.nil? ? hash[key.to_s] : value
+    end
+  end
+end

data/lib/mcp/client/elicitation.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    # Client-side helpers for the `elicitation/create` server-to-client request.
+    # https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation
+    module Elicitation
+      # Fills fields omitted from `content` with the `default` values declared in
+      # the elicitation request's `requestedSchema` properties, per SEP-1034.
+      # Provided values are never overwritten, and properties without a `default`
+      # are left out so the server can apply its own handling.
+      # Mirrors the TypeScript SDK's `applyElicitationDefaults`; the Python SDK
+      # applies defaults in the elicitation callback the same way this helper
+      # is intended to be used.
+      #
+      # @param requested_schema [Hash] The `requestedSchema` from the `elicitation/create`
+      #   request params (string or symbol keys).
+      # @param content [Hash] Values already collected from the user.
+      # @return [Hash] `content` (string keys) with defaults filled in.
+      #
+      # @example Accept an elicitation request with all defaults
+      #   transport.on_server_request("elicitation/create") do |params|
+      #     {
+      #       action: "accept",
+      #       content: MCP::Client::Elicitation.apply_defaults(params["requestedSchema"]),
+      #     }
+      #   end
+      class << self
+        def apply_defaults(requested_schema, content = {})
+          filled = content.to_h.transform_keys(&:to_s)
+          properties = requested_schema["properties"] || requested_schema[:properties]
+          return filled unless properties.is_a?(Hash)
+
+          properties.each do |name, property_schema|
+            name = name.to_s
+            next if filled.key?(name)
+            next unless property_schema.is_a?(Hash)
+
+            if property_schema.key?("default")
+              filled[name] = property_schema["default"]
+            elsif property_schema.key?(:default)
+              filled[name] = property_schema[:default]
+            end
+          end
+
+          filled
+        end
+      end
+    end
+  end
+end