ruby-mcp-client 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7e861ecba26ec407886fbb6d169b85c78ecba0768552b512cbe6c9c1f6216ad
-  data.tar.gz: d71bab971376849e2bf72e2598116087cdb4f072c556368471d1d9adfe1bd7b5
+  metadata.gz: e99574cdccfbab39918f6576fc7c896b5208599313bd69e2f39df5b529c82c22
+  data.tar.gz: 823177bc1a531d773514b9d9da8d3d6f0f2aa15f6e8562e8c0123adcdb38911c
 SHA512:
-  metadata.gz: 20d61bad3b57193dbc1a8019b87ec85758c55f61edc7c37808e7f1bc3a4fb60f35532f694aa68334273da31245ef6541cddbf2c4d0dc720d122bfae09488b415
-  data.tar.gz: e3e3ec6840cf41e0b18d6112a7ff602a798cdcb6108b1c75afd5ecaf68724adee2109dca6782e884e7b2db51d8dd8ef09fd414e20d3d7ec0c1bc072225e33427
+  metadata.gz: bc352d545dbabb90322ab473eaff7c6d52111ccd6e4812baa8b6507dc720024e23752b4a68481dc5b83722d2c9c4b6b3a36a17821998fc745cd8164e57ac8380
+  data.tar.gz: 72b2cdc279b54f2b10cbac22755086edee67792bd18e035d167f2855ad1d5dc5999c87d98e17bef83a70632459003bbd4af516414fe0e7b78b918fc2b2c5a8ce

data/README.md

@@ -38,7 +38,7 @@ 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
 
@@ -107,6 +107,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 +129,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
@@ -200,6 +208,39 @@ 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.
+
+```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 +284,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
@@ -303,14 +356,96 @@ client = Anthropic::Client.new(access_token: ENV['ANTHROPIC_API_KEY'])
 # Use tools with Claude API
 ```
 
+### RubyLLM
+
+```ruby
+require 'mcp_client'
+require 'ruby_llm'
+
+RubyLLM.configure { |c| c.openai_api_key = ENV['OPENAI_API_KEY'] }
+mcp = MCPClient.connect('http://localhost:8931/mcp')  # Playwright MCP
+
+# Wrap each MCP tool as a RubyLLM tool
+tools = mcp.list_tools.map do |t|
+  tool_name = t.name
+  Class.new(RubyLLM::Tool) do
+    description t.description
+    params t.schema
+    define_method(:name) { tool_name }
+    define_method(:execute) { |**args| mcp.call_tool(tool_name, args) }
+  end.new
+end
+
+chat = RubyLLM.chat(model: 'gpt-4o-mini')
+tools.each { |tool| chat.with_tool(tool) }
+response = chat.ask('Navigate to google.com and tell me the page title')
+```
+
 See `examples/` for complete implementations:
 - `ruby_openai_mcp.rb`, `openai_ruby_mcp.rb` - OpenAI integration
 - `ruby_anthropic_mcp.rb` - Anthropic integration
 - `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(