ruby-mcp-client 1.1.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e99574cdccfbab39918f6576fc7c896b5208599313bd69e2f39df5b529c82c22
-  data.tar.gz: 823177bc1a531d773514b9d9da8d3d6f0f2aa15f6e8562e8c0123adcdb38911c
+  metadata.gz: 0705c6df1b589bdf048b8922a92c957125f75afd0ce3ba832ef71b99a9cbe87a
+  data.tar.gz: 486d2c9891e107acaf545a62d1845e0f3d843c634d526d80ee8d12c8f9e3bde7
 SHA512:
-  metadata.gz: bc352d545dbabb90322ab473eaff7c6d52111ccd6e4812baa8b6507dc720024e23752b4a68481dc5b83722d2c9c4b6b3a36a17821998fc745cd8164e57ac8380
-  data.tar.gz: 72b2cdc279b54f2b10cbac22755086edee67792bd18e035d167f2855ad1d5dc5999c87d98e17bef83a70632459003bbd4af516414fe0e7b78b918fc2b2c5a8ce
+  metadata.gz: f766e8b97d5d6ec634fb2e95b000b154e0ce00a0f25011de9a33bd40531d2151ce727e5c3958894f1f79cab8294242441020b6f9184dd8ddf4df828430d4ad2d
+  data.tar.gz: 4a9bf198454ce1d8a9cb4b8940551faf7ddaac5962248b10b20e5b095bb46d32c1a1a642042da70b98d47a5832c3eb22aa09f9df05d54c40cf3ca1003e92824d

data/README.md

@@ -28,7 +28,10 @@ Built-in API conversions: `to_openai_tools()`, `to_anthropic_tools()`, `to_googl
 
 ## MCP Protocol Support
 
-Implements **MCP 2025-11-25** specification:
+Implements the **MCP 2025-11-25** specification. The client negotiates the
+protocol version during `initialize` and disconnects if the server answers
+with a revision it cannot speak (supported: `2025-11-25`, `2025-06-18`,
+`2025-03-26`, `2024-11-05`):
 
 - **Tools**: list, call, streaming, annotations (hint-style), structured outputs, title
 - **Prompts**: list, get with parameters
@@ -40,7 +43,13 @@ Implements **MCP 2025-11-25** specification:
 - **Logging**: Server log messages with level filtering
 - **Tasks**: Task-augmented `tools/call` — create with a `ttl`, poll `tasks/get`, retrieve via `tasks/result`, plus `tasks/list` and `tasks/cancel`
 - **Audio**: Audio content type support
-- **OAuth 2.1**: PKCE, server discovery, dynamic registration
+- **Progress & Cancellation**: `progressToken` plumbing with per-call callbacks; automatic `notifications/cancelled` for abandoned requests
+- **Metadata**: `icons`, `title` and `_meta` parsed on tools, prompts and resources
+- **OAuth 2.1**: PKCE (S256 required), RFC 8414/9728 discovery, dynamic registration, Client ID Metadata Documents, scope step-up challenges
+
+Transports treat the server as untrusted input — see
+[Treating the Server as Untrusted](#treating-the-server-as-untrusted) for the
+limits applied to peer-controlled data.
 
 ## Quick Connect API (Recommended)
 
@@ -152,6 +161,25 @@ tool.output_schema       # JSON Schema for output
 
 result = client.call_tool('get_weather', { location: 'SF' })
 data = result['structuredContent']  # Type-safe structured data
+
+# Per MCP 2025-11-25, clients SHOULD validate structured results against the
+# tool's output schema, and a tool that declares an outputSchema must return
+# structuredContent in successful results. call_tool checks both automatically
+# for the common JSON Schema keywords (type, properties, required, items, enum,
+# numeric/string bounds). The full 2020-12 vocabulary ($ref/$dynamicRef/$defs,
+# allOf/anyOf/oneOf/not, if/then/else, additionalProperties, patternProperties,
+# propertyNames, prefixItems, contains/minContains/maxContains, uniqueItems,
+# multipleOf, format, dependentRequired/dependentSchemas, minProperties/
+# maxProperties, unevaluated*) is NOT evaluated: when a schema uses any of
+# those keywords, call_tool logs a "validation is partial" warning naming them
+# (in both modes), since data may pass this check that a full validator would
+# reject. By default a violation (mismatch, or missing structuredContent on a
+# successful result) logs a warning; opt in to strict mode to raise instead:
+client = MCPClient::Client.new(
+  mcp_server_configs: [...],
+  validate_structured_content: :strict # raises MCPClient::Errors::ValidationError on violation
+)
+# Task-delivered results (get_task_result) are not validated yet.
 ```
 
 ### Roots
@@ -184,6 +212,81 @@ client = MCPClient.connect('http://server/mcp',
 )
 ```
 
+Sampling tool calling (SEP-1577) is opt-in: pass `sampling_supports_tools: true`
+to declare the `sampling.tools` capability. The handler then receives the full
+request params (including `tools`/`toolChoice`) as an optional fifth argument;
+without the opt-in, tool-enabled sampling requests are rejected with `-32602`
+as the spec requires:
+
+```ruby
+client = MCPClient::Client.new(
+  mcp_server_configs: [...],
+  sampling_supports_tools: true,
+  sampling_handler: ->(messages, prefs, system_prompt, max_tokens, params = nil) {
+    tools = params && params['tools'] # ToolUseContent may be returned in content
+    # ...
+  }
+)
+```
+
+### Progress Tracking
+
+Attach a per-call progress callback — the client generates a unique
+`progressToken`, places it in the request `_meta`, and routes matching
+`notifications/progress` to your block while the request is active (stale
+tokens after completion are dropped):
+
+```ruby
+client.call_tool('long_running', args, progress: ->(progress, total, message) {
+  puts "#{message}: #{progress}/#{total}"
+})
+```
+
+A request-level `_meta` (e.g. a hand-picked `progressToken`) can also be passed
+inside the arguments under the `'_meta'` key on every transport — it is hoisted
+to the JSON-RPC params level on the wire, never sent as a tool argument.
+
+### Timeouts and Cancellation
+
+Timeouts are configurable per request in addition to the per-server
+`read_timeout`. A timed-out request raises
+`MCPClient::Errors::RequestTimeoutError` (a `TransportError` subclass), is
+**never** silently re-sent by the retry layer, and a best-effort
+`notifications/cancelled` is sent for the abandoned request (never for
+`initialize`, and task-augmented calls use `tasks/cancel` instead):
+
+```ruby
+client.send_rpc('tools/call', params: { name: 'slow', arguments: {} }, timeout: 300)
+server.rpc_request('tools/list', {}, timeout: 5)
+```
+
+### Client Identity and Server Instructions
+
+Hosts can present their own `Implementation` info (sent as `clientInfo` during
+initialize; `name` and `version` required — `title`, `description`,
+`websiteUrl`, `icons` optional), and read the server's `instructions` hint
+after connecting:
+
+```ruby
+client = MCPClient::Client.new(
+  mcp_server_configs: [...],
+  client_info: { 'name' => 'my-ide', 'version' => '2.0.0', 'description' => 'An MCP-powered IDE' }
+)
+client.servers.first.connect
+puts client.servers.first.instructions # e.g. "Use the search tool before answering."
+```
+
+### Capability Gating
+
+Optional server features (`logging/setLevel`, `resources/subscribe`,
+`completion/complete`, `tasks/list`, `tasks/cancel`) are only sent to servers
+that negotiated the corresponding capability; otherwise
+`MCPClient::Errors::CapabilityError` is raised (the lifecycle forbids using
+capabilities that were not negotiated). `Client#log_level=` skips
+non-logging servers instead of failing. Declared *client* capabilities are
+derived from what the host actually registered (handlers, roots), never
+hardcoded.
+
 ### Completion (Autocomplete)
 
 ```ruby
@@ -213,6 +316,9 @@ end
 A task-capable server (one advertising `tasks.requests.tools.call`) can run a tool
 whose `execution.taskSupport` is `optional` or `required` as a background task:
 the call returns immediately with a task handle, and the result is fetched later.
+Try it locally: `python3 examples/echo_server_streamable.py &` then
+`./examples/tasks_example.rb` runs the full lifecycle against a task-capable
+demo server.
 
 ```ruby
 tool = client.find_tool('long_job')
@@ -225,15 +331,24 @@ task = client.call_tool_as_task('long_job', { input: 'data' }, ttl: 60_000)
 # honoring the server's suggested poll interval
 until task.terminal? || task.input_required?
   sleep((task.poll_interval || 1000) / 1000.0)
-  task = client.get_task(task.task_id)   # tasks/get
+  task = client.get_task(task)          # tasks/get, routed to the task's own server
 end
 
 # Retrieve the underlying result (e.g. a CallToolResult) via tasks/result
-result = client.get_task_result(task.task_id)
+result = client.get_task_result(task)
 
 # List and cancel tasks
 page = client.list_tasks               # { tasks: [...], next_cursor: ... }
-client.cancel_task(task.task_id)       # tasks/cancel
+client.cancel_task(task)               # tasks/cancel
+```
+
+Task IDs are only unique within the server that issued them, so pass the `Task`
+returned by `call_tool_as_task` — it carries its own server. A bare task ID also
+works when the client has a single server; with several servers configured it
+raises `ArgumentError` rather than guessing, so name the server explicitly:
+
+```ruby
+client.get_task('task-123', server: 'my-server')
 
 # React to server-pushed status updates
 client.on_notification do |server, method, params|
@@ -290,12 +405,49 @@ The `retries:` option controls automatic retry with exponential backoff. Only
 failures where the request most likely did **not** complete at the server are
 retried: transport/network errors and HTTP **5xx** responses. Application-level
 failures — a JSON-RPC error response or an HTTP **4xx** — are **never** retried,
-because the server already processed or rejected the request and re-sending
-would risk re-executing a non-idempotent `tools/call`. Retryable server failures
-raise `MCPClient::Errors::TransientServerError`, a subclass of
+because the server already processed or rejected the request. Retryable server
+failures raise `MCPClient::Errors::TransientServerError`, a subclass of
 `MCPClient::Errors::ServerError`, so existing `rescue ServerError` handlers are
 unaffected.
 
+**`tools/call` is never retried automatically.** Even a "transient" failure can
+arrive *after* the server executed the request, and JSON-RPC has no idempotency
+key that would make a replay safe — so a retry could run a side effect twice.
+Retry a tool call explicitly if your application knows it is safe to repeat, and
+treat the raised error as *outcome unknown* rather than *not executed*:
+
+```ruby
+begin
+  client.call_tool('send_invoice', { customer: 'acme' })
+rescue MCPClient::Errors::TransportError => e
+  # The server may or may not have sent the invoice. Check before retrying.
+end
+```
+
+The same reasoning excludes `RequestTimeoutError` and `ResponseTooLargeError`
+from retries, and applies to session recovery: if a `tools/call` comes back with
+an expired-session 404, the client starts a fresh session but does **not** re-send
+the call — it raises so you can decide. Idempotent requests are re-sent against
+the new session as before.
+
+### Response Size Limits (Streamable HTTP)
+
+A gzip-encoded response is decompressed incrementally and abandoned once it
+expands past `max_decompressed_body_bytes` (default **64 MiB**), so a small
+highly-compressed body cannot exhaust memory. Exceeding it raises
+`MCPClient::Errors::ResponseTooLargeError`.
+
+Raise the limit if you legitimately exchange very large payloads — base64
+resource blobs or audio — so that whether a response is accepted does not depend
+on the server's choice to compress it:
+
+```ruby
+MCPClient.streamable_http_config(
+  base_url: 'https://api.example.com/mcp',
+  max_decompressed_body_bytes: 256 * 1024 * 1024
+)
+```
+
 ### Faraday Customization
 
 ```ruby
@@ -470,6 +622,20 @@ Features: PKCE, server discovery (`.well-known`), dynamic registration, token re
 
 See [OAUTH.md](OAUTH.md) for full documentation.
 
+### OAuth Extras (2025-11-25)
+
+- **Client ID Metadata Documents (SEP-991)** — pass
+  `client_id_metadata_url: 'https://myapp.example/oauth-client.json'` (an HTTPS
+  URL with a path, which doubles as the `client_id`); when the authorization
+  server advertises `client_id_metadata_document_supported`, dynamic client
+  registration is skipped entirely.
+- **Scope challenges (SEP-835)** — an HTTP 403 `insufficient_scope` challenge
+  raises `MCPClient::Errors::InsufficientScopeError` (a `ConnectionError`
+  subclass) exposing `#scope` and `#error_description`; the challenged scopes
+  are treated as authoritative for the next authorization flow.
+- **PKCE** — authorization refuses to proceed when the authorization server
+  does not advertise `code_challenge_methods_supported` including `S256`.
+
 ## Server Notifications
 
 ```ruby
@@ -492,7 +658,9 @@ Both HTTP and Streamable HTTP transports automatically handle session-based serv
 - **Session capture**: Extracts `Mcp-Session-Id` from initialize response
 - **Session persistence**: Includes session header in subsequent requests
 - **Session termination**: Sends DELETE request during cleanup
-- **Resumability** (Streamable HTTP): Tracks event IDs for message replay
+- **Resumability** (Streamable HTTP, SEP-1699): tracks SSE event IDs and, when a
+  response stream is interrupted, resumes via GET with `Last-Event-ID` so the
+  server can replay missed messages — honoring the server's `retry:` directive
 
 No configuration required - works automatically.
 
@@ -519,10 +687,48 @@ tools = client.list_tools
 result = client.call_tool('echo', { message: 'Hello!' })
 ```
 
+## Treating the Server as Untrusted
+
+A connected MCP server controls everything it sends you, and the transports are
+written on that assumption. You do not need to configure any of this — it is the
+default behaviour — but it is worth knowing what the client will refuse:
+
+| Peer-controlled input | What the client does |
+|---|---|
+| Compressed response bodies (**Streamable HTTP only** — the only transport that requests gzip) | Decompressed incrementally, abandoned past `max_decompressed_body_bytes` (64 MiB default) |
+| SSE streams | Per-connection buffer cap; events scanned incrementally, so an unterminated event costs bounded memory *and* CPU |
+| `retry:` directives | Honored, but floored so `retry: 0` cannot drive a reconnect loop |
+| SSE event IDs | Bounded length, printable ASCII only (they are echoed in `Last-Event-ID`) |
+| Legacy SSE `endpoint` events | Must stay on the connection's origin; off-origin redirects are refused, so configured credential headers never reach another host |
+| OAuth discovery URLs from a peer | Must be HTTPS, and rejected when the host is a *literal* loopback/private/link-local address (unless the configured server is itself local); a refused challenge fails closed. Hostnames are not resolved, so a public name pointing at a private address is not caught — see the note below |
+| Unsolicited JSON-RPC responses | Discarded — only IDs with an outstanding request are accepted |
+| Server-initiated requests | Replies are bounded by a concurrency budget rather than spawning unbounded threads |
+| Schema `pattern` values | Matched under a whole-operation time budget; a timeout fails validation rather than silently passing |
+| Log messages (`notifications/message`) | Control characters escaped and length-capped, so a server cannot forge log lines |
+
+**Known limit:** the OAuth check is textual. A peer can still advertise a public
+hostname whose DNS record points inside your network; catching that needs
+resolution-time filtering in the HTTP layer, which this gem does not do. If you
+run in an environment where that matters, restrict egress at the network layer.
+
+Two related defaults worth calling out because they affect *your* data rather
+than the peer's:
+
+- **Payloads are never written to logs.** At DEBUG the client logs a method/id
+  summary and a byte count, not request params, response bodies or raw SSE
+  chunks. Server configurations are logged with credential-bearing keys redacted.
+- **Host exceptions are not reflected to the server.** A raising elicitation,
+  sampling or roots handler yields a constant JSON-RPC error message; the detail
+  stays in your local log.
+
 ## Requirements
 
 - Ruby >= 3.2.0
-- No runtime dependencies
+- Runtime dependencies: `faraday` (~> 2.0) with `faraday-follow_redirects` and
+  `faraday-retry`, plus `base64` — all pulled in automatically by the gem
+
+Development uses Ruby 4.0.6 (see `.ruby-version`). CI runs the suite on 4.0.6
+plus the supported floor, 3.2 and 3.3.
 
 ## License