ruby-mcp-client 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e56ef84106ab19bf3028b31dd7ce362cfb58f244743057271f14a83409153f0
-  data.tar.gz: 96f0e42875d80032c24056c1dbd9c6417b3db994538838736fa52f303e0d4f85
+  metadata.gz: 5687a9c54b7e5c4814e80bd2e5e97d2072dd0f994e3bebe680259a1a9db64c25
+  data.tar.gz: 05b3bce582f21e57ae07ac862daf6a74812f3ba79f6e4b806868850686c33467
 SHA512:
-  metadata.gz: 48b7cd77ab406967bc4cd5fe79c5c1511a8eb2c9e4c9ebc27b31b8386e175a435d1a620ffcfa7871044188061b3f0718875d009f2a4ef7d030786ad11bcbde35
-  data.tar.gz: 11f845c21895b67d0a308267972936fcf07df042e33de6417b69ee486f1739a8768f25b698bbbad92fdbef3acf0e6ec42eaffa525896b9e77e50e86960c7daf8
+  metadata.gz: 3aef7d0842eab30de7e84a5507298efd30ae78de3ea3223cc8f00bd31892e7665f55f533952df771a2d3ab38f874d3905e029b0d19b8147d07ffd030772106fe
+  data.tar.gz: 324f5121352512f827f05fa55f78917b3218b7d031c418cfa884a8718b2b06fda027b8b811df2083361200ff17682dbfea8998505db0e2932db3a545f605c35a

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
@@ -38,9 +41,11 @@ Implements **MCP 2025-11-25** specification:
 - **Sampling**: Server-requested LLM completions with modelPreferences
 - **Completion**: Autocomplete for prompts/resources with context
 - **Logging**: Server log messages with level filtering
-- **Tasks**: Structured task management with progress tracking
+- **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
 
 ## Quick Connect API (Recommended)
 
@@ -107,6 +112,11 @@ end
 prompts = client.list_prompts
 result = client.get_prompt('greeting', { name: 'Alice' })
 
+# Pagination: list_tools and list_prompts automatically follow the server's
+# nextCursor and return the COMPLETE set across all pages (with a per-call
+# safety bound and an identical-cursor loop guard). No manual cursor handling
+# is required.
+
 # Resources
 result = client.list_resources
 contents = client.read_resource('file:///example.txt')
@@ -124,9 +134,12 @@ end
 tool = client.find_tool('delete_user')
 
 # Hint-style annotations (MCP 2025-11-25)
-tool.read_only_hint?      # Defaults to true; tool does not modify environment
-tool.destructive_hint?    # Defaults to false; tool may perform destructive updates
-tool.idempotent_hint?     # Defaults to false; repeated calls have no additional effect
+# Defaults follow the MCP ToolAnnotations schema: when a hint is absent the
+# client assumes the less-safe value, so an un-annotated tool is treated as
+# writable, potentially destructive, and open-world.
+tool.read_only_hint?      # Defaults to false; tool may modify its environment
+tool.destructive_hint?    # Defaults to true; tool may perform destructive updates
+tool.idempotent_hint?     # Defaults to false; repeated calls may have additional effects
 tool.open_world_hint?     # Defaults to true; tool may interact with external entities
 
 # Legacy annotations
@@ -144,6 +157,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
@@ -176,6 +208,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
@@ -200,6 +307,42 @@ client.on_notification do |server, method, params|
 end
 ```
 
+### Tasks (Long-running, task-augmented tools)
+
+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')
+tool.supports_task?   # execution.taskSupport is optional/required?
+
+# Create the task (returns immediately); ttl is the requested lifetime in ms
+task = client.call_tool_as_task('long_job', { input: 'data' }, ttl: 60_000)
+
+# Poll until the task reaches a terminal (or input-required) status,
+# 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
+end
+
+# Retrieve the underlying result (e.g. a CallToolResult) via tasks/result
+result = client.get_task_result(task.task_id)
+
+# List and cancel tasks
+page = client.list_tasks               # { tasks: [...], next_cursor: ... }
+client.cancel_task(task.task_id)       # tasks/cancel
+
+# React to server-pushed status updates
+client.on_notification do |server, method, params|
+  puts "Task #{params['taskId']} -> #{params['status']}" if method == 'notifications/tasks/status'
+end
+```
+
 ### Elicitation (Server-initiated user interactions)
 
 ```ruby
@@ -243,6 +386,18 @@ client = MCPClient.create_client(
 client = MCPClient.create_client(server_definition_file: 'servers.json')
 ```
 
+### Retries
+
+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
+`MCPClient::Errors::ServerError`, so existing `rescue ServerError` handlers are
+unaffected.
+
 ### Faraday Customization
 
 ```ruby
@@ -334,9 +489,65 @@ See `examples/` for complete implementations:
 - `gemini_ai_mcp.rb` - Google Vertex AI integration
 - `ruby_llm_mcp.rb` - RubyLLM integration (OpenAI provider)
 
+## Running the Examples
+
+The `examples/run_all_examples.sh` harness runs every example that can run on the current machine — self-contained stdio servers, the Python/Flask/FastMCP echo and elicitation servers, `npx`-based MCP servers, and (optionally) the paid LLM integrations. It starts and tears down each server automatically and prints a `PASS`/`FAIL`/`SKIP` summary. `tasks_example.rb` is always skipped (it needs a task-capable remote server); `oauth_browser_auth.rb` is interactive and only runs when you opt in with `RUN_OAUTH=1`.
+
+### Prerequisites
+
+Run `bundle install` first. The script preflight-checks the following and prints a warning (it does **not** abort) for anything missing; affected examples are then skipped or fail:
+
+- `ruby`, `bundle`, `curl`, `lsof` - on `PATH`
+- `python3` (or `$PYTHON`) plus a separate `python` binary - on `PATH`
+- Python packages `flask`, `fastmcp`, `mcp` - importable by `$PYTHON`
+- `npx` (Node) - needed by the `npx`-based example (`json_input`) and by every LLM example, which spawn `npx` filesystem/Playwright servers
+
+### Usage
+
+```bash
+examples/run_all_examples.sh                       # run everything runnable on this machine
+RUN_AI=0 examples/run_all_examples.sh              # skip the paid-LLM examples
+RUN_NPX=0 examples/run_all_examples.sh             # skip the npx-based example (json_input)
+LOG_DIR=/path examples/run_all_examples.sh         # write logs to a chosen dir
+PYTHON=python3.12 TIMEOUT=180 examples/run_all_examples.sh  # override interpreter and per-example timeout
+```
+
+### Environment Knobs
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `RUN_AI` | `1` | Set to `0` to skip the LLM integrations, which make **real, paid** API calls. |
+| `RUN_NPX` | `1` | Set to `0` (or leave `npx` off `PATH`) to skip the `npx`-based example (`json_input`). The LLM examples spawn `npx` servers too, but are gated by `RUN_AI` and their API keys instead. |
+| `PYTHON` | `python3` | Interpreter used to launch the Python/Flask/FastMCP servers and run the import preflight checks. |
+| `TIMEOUT` | `120` | Per-example wall-clock timeout in seconds; a timeout is reported as a `FAIL`. |
+| `LOG_DIR` | fresh `mktemp` dir | Directory for per-example and per-server logs; the path is printed after preflight and in the summary. |
+
+### Secrets and API Keys
+
+Real secrets live in `examples/secrets.env`, which is **gitignored** and sourced automatically (every `KEY=value` line is exported) when present. Copy the tracked template to get started:
+
+```bash
+cp examples/secrets.env.example examples/secrets.env
+# then set ZAPIER_MCP_TOKEN=... to enable the Zapier streamable-HTTP example
+```
+
+Set `ZAPIER_MCP_TOKEN` (from the Zapier MCP setup page, "Option 1: Authorization header") to run `streamable_http_example.rb` and `oauth_example.rb` against Zapier; override `ZAPIER_MCP_URL` if your connect URL differs. To run the interactive `oauth_browser_auth.rb`, set `MCP_SERVER_URL` (e.g. an ngrok tunnel to your OAuth-protected MCP server) in `secrets.env` and pass `RUN_OAUTH=1`. The LLM examples each need their own credentials in the environment and are skipped without them:
+
+- `ruby_anthropic_mcp.rb` - `ANTHROPIC_API_KEY` (+ `npx`)
+- `openai_ruby_mcp.rb` - `OPENAI_API_KEY` (+ `npx`)
+- `ruby_openai_mcp.rb`, `ruby_llm_mcp.rb` - `OPENAI_API_KEY` (+ `npx`, plus a Playwright MCP server on `:8931`)
+- `gemini_ai_mcp.rb` - a Vertex service-account JSON at `VERTEX_CREDENTIALS_FILE` (default `examples/google-credentials.json`, + `npx`)
+
+### How Pass/Fail Is Judged
+
+Most examples print their own success/failure marks but exit `0` regardless, so the harness combines the exit code with a scan of the output rather than trusting the exit status alone. An example `FAIL`s when it exits nonzero, times out (exit `124`), prints a hard-error signature (a Ruby/Python traceback, `Connection refused`, `uninitialized constant`, and similar), prints a `❌` mark, or is missing its expected success marker; otherwise it `PASS`es. (The `❌` check is suppressed with `IGNORE_XMARK=1` for the interactive elicitation demos, where `❌` can be legitimate "declined" output.) The script exits `0` only if zero examples failed — `SKIP`s do not affect the exit status.
+
+For deeper, per-topic walkthroughs see [`examples/README.md`](examples/README.md), [`examples/README_ECHO_SERVER.md`](examples/README_ECHO_SERVER.md), [`examples/STREAMABLE_HTTP_TESTING.md`](examples/STREAMABLE_HTTP_TESTING.md), and [`examples/elicitation/README.md`](examples/elicitation/README.md).
+
 ## OAuth 2.1 Authentication
 
 ```ruby
+require 'mcp_client'
 require 'mcp_client/auth/browser_oauth'
 
 oauth = MCPClient::Auth::OAuthProvider.new(
@@ -361,6 +572,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
@@ -383,7 +608,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.