RubyGems - mcp - Versions diffs - 0.23.0 → 0.25.0 - Mend

mcp 0.23.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

checksums.yaml +4 -4
data/README.md +329 -6
data/lib/json_rpc_handler.rb +18 -1
data/lib/mcp/apps.rb +109 -0
data/lib/mcp/client/elicitation.rb +51 -0
data/lib/mcp/client/http.rb +383 -32
data/lib/mcp/client/oauth/client_credentials_provider.rb +72 -14
data/lib/mcp/client/oauth/cross_app_access_provider.rb +80 -0
data/lib/mcp/client/oauth/discovery.rb +1 -1
data/lib/mcp/client/oauth/flow.rb +182 -6
data/lib/mcp/client/oauth/id_jag_token_exchange.rb +101 -0
data/lib/mcp/client/oauth/in_memory_storage.rb +3 -1
data/lib/mcp/client/oauth/jwt_client_assertion.rb +128 -0
data/lib/mcp/client/oauth/provider.rb +11 -3
data/lib/mcp/client/oauth.rb +5 -1
data/lib/mcp/client/paginated_result.rb +7 -5
data/lib/mcp/client/stdio.rb +3 -1
data/lib/mcp/client.rb +127 -1
data/lib/mcp/configuration.rb +1 -1
data/lib/mcp/error_codes.rb +21 -0
data/lib/mcp/icon.rb +1 -1
data/lib/mcp/instrumentation.rb +0 -2
data/lib/mcp/methods.rb +3 -1
data/lib/mcp/resource.rb +135 -0
data/lib/mcp/resource_template.rb +149 -0
data/lib/mcp/result_type.rb +18 -0
data/lib/mcp/server/transports/streamable_http_transport.rb +138 -87
data/lib/mcp/server.rb +192 -23
data/lib/mcp/server_context.rb +12 -0
data/lib/mcp/server_session.rb +40 -0
data/lib/mcp/version.rb +1 -1
data/lib/mcp.rb +3 -0
metadata +10 -3

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3d294b5e8b52b58ba3d2a2752db94f3a0d836ed6003d10ba0220d9d31b2d267
-  data.tar.gz: 1f0e92d3a77fc36166a1f68c3443aa9d5174ee139491b784dfa3cdcb92caa8e1
+  metadata.gz: 829c2bc3c3644f2a7edcf5fd44b96d87887c37da3a4cf4766eed79a2676425ee
+  data.tar.gz: 1a168f15a16ad704db47e8c8c2aa7be3f4f869af2a5199fa54d44b4a05990aa0
 SHA512:
-  metadata.gz: 975ebdaeab3e8dd8219c81c812fcbde232047a9baabf6924bea6fba7f4eae05b6eab96aa02efd601e83e443fc0ad62107f9379a1ab07924d1fcccedae48c6232
-  data.tar.gz: 624de6afb8859bce866dabef20c6357913ff8adf2e479f84d2472049f7f7f2853dc65f27ed1925f1c3f76eae880a3886806136dea6d94459988d24e6f973d304
+  metadata.gz: e6ca51112faf60a4a2b9f5be2db20f9fe25b6581ca327708f483c03f021b9a68ce8df8c3342e5430132ac670103a26d4ac2f9617e3e0358e074745d6fa4c7743
+  data.tar.gz: a57eea28ea7e173422e855702789780381032e888bed42eb42900251e05f8a2806df4220c50c0727423d6c5a8e9124127cdc53e9e9bf34170e6a7c2afa058e7a

data/README.md CHANGED Viewed

@@ -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
@@ -178,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.
@@ -279,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`
@@ -972,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(
@@ -989,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|
@@ -1001,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`)
@@ -1018,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(
@@ -1046,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.
@@ -1919,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
@@ -2112,6 +2318,72 @@ response = client.call_tool(
 The server will send `notifications/progress` back to the client during execution.
+`MCP::Client::HTTP.new` accepts an optional `max_message_bytes:` keyword that caps the bytes buffered in memory for a single message from the server -
+an SSE event or a JSON response body. A message that reaches this limit before completing is rejected as a transport error, preventing unbounded memory growth from
+a server that never terminates an SSE event. It defaults to `4 * 1024 * 1024` (4 MiB); raise it if your server returns larger responses.
+#### 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| ... }`.
+#### Server-to-Client Requests (Sampling)
+Servers can also request an LLM completion from the client with [`sampling/createMessage`](https://modelcontextprotocol.io/specification/2025-11-25/client/sampling),
+letting a server leverage the client's model access without its own API keys.
+> MCP Sampling is deprecated as of protocol version `2026-07-28` (SEP-2577), while remaining fully supported under `2025-11-25`.
+> Register this handler to interoperate with servers that still send sampling requests during the deprecation window;
+> new servers should call LLM provider APIs directly.
+Register a handler and advertise the capability on `connect`:
+```ruby
+client.connect(capabilities: { sampling: {} })
+client.on_sampling do |params|
+  completion = my_llm.complete(params["messages"], max_tokens: params["maxTokens"])
+  {
+    role: "assistant",
+    content: { type: "text", text: completion.text },
+    model: completion.model,
+    stopReason: "endTurn",
+  }
+end
+```
+For trust and safety, the spec recommends a human in the loop able to review, edit, or reject the request and the generated response.
+To reject a request, raise `MCP::Client::ServerRequestError` with the spec's user-rejection code `-1`:
+```ruby
+client.on_sampling do |params|
+  raise MCP::Client::ServerRequestError.new("User rejected sampling request", code: -1) unless approved?(params)
+  generate_completion(params)
+end
+```
+Use `capabilities: { sampling: { tools: {} } }` to receive tool-enabled sampling requests. Like elicitation, this uses the same standalone GET SSE listening stream.
 #### 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:
@@ -2188,13 +2460,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`,
@@ -2271,6 +2547,43 @@ Keyword arguments:
 - `token_endpoint_auth_method`: `"client_secret_basic"` (default) or `"client_secret_post"`. `"none"` is rejected with `ClientCredentialsProvider::InvalidCredentialsError`.
 - `scope`, `storage`: Optional, same meaning as on `Provider`.
+##### Cross-App Access (JWT Bearer) Grant
+For enterprise MCP deployments where an identity provider (IdP) governs authorization (SEP-990), use `MCP::Client::OAuth::CrossAppAccessProvider` instead of `Provider`.
+The client exchanges an IdP-issued ID token for an Identity Assertion Authorization Grant (ID-JAG) at the IdP via RFC 8693 token exchange, then presents the ID-JAG
+to the MCP authorization server with the RFC 7523 `jwt-bearer` grant, authenticating with `client_secret_basic`. There is no authorization request, PKCE, DCR, or `offline_access`.
+Mirrors `CrossAppAccessProvider` and `requestJwtAuthorizationGrant` in the TypeScript SDK.
+`MCP::Client::OAuth::IDJAGTokenExchange.request` performs the RFC 8693 exchange at the IdP token endpoint. Wrap it in a callable so the same provider can plug into
+an enterprise secret store or a test double without changing the transport wiring.
+```ruby
+provider = MCP::Client::OAuth::CrossAppAccessProvider.new(
+  client_id: "my-mcp-client",
+  client_secret: ENV.fetch("MCP_CLIENT_SECRET"),
+  assertion_provider: ->(audience:, resource:) {
+    MCP::Client::OAuth::IDJAGTokenExchange.request(
+      token_endpoint: "https://idp.example.com/token",
+      id_token: ENV.fetch("IDP_ID_TOKEN"),
+      client_id: "my-idp-client",
+      audience: audience,
+      resource: resource,
+    )
+  },
+  # scope: "mcp:read mcp:write" (optional; used when neither WWW-Authenticate nor PRM specify one)
+)
+transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp", oauth: provider)
+```
+Keyword arguments:
+- `client_id`, `client_secret`: Required. The `jwt-bearer` grant authenticates with `client_secret_basic` at the MCP authorization server.
+- `assertion_provider`: Required. Callable invoked as `call(audience:, resource:)` and returning the ID-JAG assertion.
+  `audience` is the MCP authorization server's validated issuer identifier; `resource` is the canonical MCP server URL (RFC 8707).
+  Passing both through to `IDJAGTokenExchange.request` covers the common case.
+- `scope`, `storage`: Optional, same meaning as on `Provider`.
 ##### Communication Security
 When `oauth:` is set, the MCP transport URL and every OAuth-facing URL (PRM, Authorization Server metadata, `authorization_endpoint`, `token_endpoint`, `registration_endpoint`,
@@ -2302,6 +2615,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 CHANGED Viewed

@@ -16,7 +16,7 @@ module JsonRpcHandler
     PARSE_ERROR = -32700
   end
-  DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+  DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/.freeze
   # Sentinel return value from a handler. When a handler returns this,
   # `process_request` emits no JSON-RPC response for the request,
@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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