ruby-mcp-client 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e0949102c5c22625bef68e2f5b4a0e2aecdfc636495ecba52d16f663c35f2fc
-  data.tar.gz: fbeb7484c1458775b88aa074422913e9d09d8a37b23aac38c7edf82e2111b9cb
+  metadata.gz: a5e35c00292938e3c6cd17885d6578e465d12853ed1844f67dc4633096bb2fa3
+  data.tar.gz: e9419a3969689a0768ea8290f2a45f5214fcc4b74521ac38aac3bfd842b7ec49
 SHA512:
-  metadata.gz: b2e75071c0fceb5061037b1537d9e71fd8f03dc5c94aa6c2bbc2a63ce6f24ae16c1c2c2cdb560f48e12ca4115224561f89043dde2145116d1e4e397c9cb7e409
-  data.tar.gz: d3900ae79aba5d896a1496bc28af3e9ec8f0b7066f30eb0723cd1664845769dd09afd130faa2db0b4b1b67d948f15e3532cfb5abcd3b076d0e7547e7e89671fb
+  metadata.gz: 063bc6c91cf5d6e82a05b17dd90519e07d3168baf5efb36969e98d0893d40f4d630db3181dfd28929fc255f579780c041b407dfd8bfec17f3461022f2cb84471
+  data.tar.gz: e92a6c8d29474c08966008f9e2e5f530520258f546b40694fc0245eaf3da2ad6064ce7bb312596a07d5e4a94f4516603256c2bd7375cfc67065180f636f64eb1

data/README.md

@@ -40,11 +40,16 @@ with popular AI services with built-in conversions:
 - `to_anthropic_tools()` - Formats tools for Anthropic Claude API
 - `to_google_tools()` - Formats tools for Google Vertex AI API (automatically removes "$schema" keys not accepted by Vertex AI)
 
-## MCP 2025-03-26 Protocol Features
+## MCP Protocol Support
 
-This Ruby MCP Client implements key features from the latest MCP specification (Protocol Revision: 2025-03-26):
+This Ruby MCP Client implements the **MCP 2025-06-18** specification with full backward compatibility.
 
-### Implemented Features
+### Key Features
+
+**MCP 2025-06-18 (Latest):**
+- **Structured Tool Outputs** - Tools can declare output schemas and return type-safe, validated structured data
+- **Elicitation (Server-initiated User Interactions)** - Servers can request user input during tool execution via bidirectional JSON-RPC (stdio, SSE, and Streamable HTTP transports)
+- **Tool Annotations** - Support for tool behavior annotations (readOnly, destructive, requiresConfirmation) for safer tool execution
 - **OAuth 2.1 Authorization Framework** - Complete authentication with PKCE, dynamic client registration, server discovery, and runtime configuration
 - **Streamable HTTP Transport** - Enhanced transport with Server-Sent Event formatted responses and session management
 - **HTTP Redirect Support** - Automatic redirect handling for both SSE and HTTP transports with configurable limits
@@ -581,14 +586,22 @@ client = Anthropic::Client.new(access_token: ENV['ANTHROPIC_API_KEY'])
 ```
 
 Complete examples can be found in the `examples/` directory:
+
+**AI Integration Examples:**
 - `ruby_openai_mcp.rb` - Integration with alexrudall/ruby-openai gem
 - `openai_ruby_mcp.rb` - Integration with official openai/openai-ruby gem
 - `ruby_anthropic_mcp.rb` - Integration with alexrudall/ruby-anthropic gem
 - `gemini_ai_mcp.rb` - Integration with Google Vertex AI and Gemini models
+
+**Transport Examples:**
 - `streamable_http_example.rb` - Streamable HTTP transport with Playwright MCP
 - `echo_server.py` & `echo_server_client.rb` - FastMCP server example with full setup
 - `echo_server_streamable.py` & `echo_server_streamable_client.rb` - Enhanced streamable HTTP server example
 
+**MCP 2025 Protocol Features:**
+- `structured_output_server.py` & `test_structured_outputs.rb` - Structured tool outputs (MCP 2025-06-18)
+- `echo_server_with_annotations.py` & `test_tool_annotations.rb` - Tool annotations (MCP 2025-03-26)
+
 ## MCP Server Compatibility
 
 This client works with any MCP-compatible server, including:
@@ -777,6 +790,83 @@ auth_url = oauth_provider.start_authorization_flow
 token = oauth_provider.complete_authorization_flow(code, state)
 ```
 
+### Browser-Based OAuth Authentication
+
+For the easiest authentication experience, use the browser-based OAuth flow that automatically handles the entire process:
+
+```ruby
+require 'mcp_client/auth/browser_oauth'
+
+# Create OAuth provider
+oauth_provider = MCPClient::Auth::OAuthProvider.new(
+  server_url: 'https://api.example.com/mcp',
+  redirect_uri: 'http://localhost:8080/callback',
+  scope: 'read:tools write:tools'  # Optional
+)
+
+# Create browser OAuth helper
+browser_oauth = MCPClient::Auth::BrowserOAuth.new(
+  oauth_provider,
+  callback_port: 8080,        # Optional: Port for local server (default: 8080)
+  callback_path: '/callback'  # Optional: Callback path (default: '/callback')
+)
+
+# Authenticate (opens browser automatically and handles callback)
+token = browser_oauth.authenticate(
+  timeout: 300,              # Optional: 5 minutes (default: 300)
+  auto_open_browser: true    # Optional: Auto-open browser (default: true)
+)
+
+# Create authenticated client (use streamable_http for modern MCP servers)
+server_config = {
+  type: 'streamable_http',  # or 'http' for simple HTTP-only servers
+  base_url: 'https://api.example.com/mcp',
+  oauth_provider: oauth_provider
+}
+
+client = MCPClient::Client.new(mcp_server_configs: [server_config])
+```
+
+**How it works:**
+1. **Automatically starts a local HTTP server** (using pure Ruby `TCPServer`) to handle the OAuth callback
+2. **Opens your default browser** to the authorization page (macOS: `open`, Linux: `xdg-open`, Windows: `start`)
+3. **Captures the authorization code** automatically from the callback
+4. **Completes the OAuth flow** and stores the access token
+5. **Handles token refresh** automatically when tokens expire
+
+**Features:**
+- **Zero external dependencies** - Uses pure Ruby stdlib (`TCPServer`)
+- **User-friendly HTML pages** - Shows success/error pages in the browser
+- **Automatic token management** - Handles token refresh transparently
+- **Configurable timeout** - Raises `Timeout::Error` if user doesn't authorize in time
+- **Token storage** - Supports custom storage backends for persistent tokens
+- **Port conflict detection** - Clear error messages if port is already in use
+- **Security hardened** - PKCE, CSRF protection, request validation, header limits
+
+**Error Handling:**
+```ruby
+begin
+  token = browser_oauth.authenticate
+rescue Timeout::Error
+  puts "User took too long to authorize"
+rescue MCPClient::Errors::ConnectionError => e
+  puts "OAuth flow failed: #{e.message}"
+  # Port already in use, server doesn't support OAuth, etc.
+rescue ArgumentError => e
+  puts "Invalid state parameter (CSRF protection)"
+end
+```
+
+**Server Requirements:**
+- OAuth 2.1 Protocol with PKCE
+- Authorization Server Discovery via:
+  - `/.well-known/oauth-authorization-server` (primary, for self-contained servers)
+  - `/.well-known/oauth-protected-resource` (fallback, for delegated auth)
+- Dynamic Client Registration (recommended)
+- Authorization Code Grant Flow
+
+For a complete working example, see [`examples/oauth_browser_auth.rb`](examples/oauth_browser_auth.rb).
+
 ### OAuth Features
 
 - **OAuth 2.1 compliance** with PKCE for security
@@ -785,6 +875,7 @@ token = oauth_provider.complete_authorization_flow(code, state)
 - **Token refresh** and automatic token management
 - **Pluggable storage** for tokens and client credentials
 - **Runtime configuration** via getter/setter methods
+- **Browser-based authentication** with automatic callback handling
 
 For complete OAuth documentation, see [OAUTH.md](OAUTH.md).
 
@@ -908,6 +999,254 @@ elsif content.binary?
 end
 ```
 
+## Tool Annotations
+
+MCP 2025-06-18 supports tool annotations that describe tool behavior, enabling safer and more informed tool execution. The Ruby MCP Client provides full support for reading and interpreting these annotations.
+
+### Annotation Types
+
+Tools can include the following annotations:
+
+- **`readOnly`** - Indicates the tool only reads data and doesn't modify state
+- **`destructive`** - Indicates the tool performs potentially dangerous operations (e.g., deleting data)
+- **`requiresConfirmation`** - Indicates the tool should require explicit user confirmation before execution
+
+### Using Tool Annotations
+
+```ruby
+# List tools and check their annotations
+tools = client.list_tools
+
+tools.each do |tool|
+  puts "Tool: #{tool.name}"
+
+  # Check annotations using helper methods
+  if tool.read_only?
+    puts "  → Safe to execute (read-only)"
+  end
+
+  if tool.destructive?
+    puts "  ⚠️  Warning: This tool is destructive"
+  end
+
+  if tool.requires_confirmation?
+    puts "  🛡️  Requires user confirmation before execution"
+  end
+
+  # Access raw annotations hash
+  if tool.annotations
+    puts "  Annotations: #{tool.annotations.inspect}"
+  end
+end
+
+# Make informed decisions based on annotations
+tool = client.find_tool('delete_user')
+if tool.destructive? && tool.requires_confirmation?
+  # Prompt user for confirmation before executing
+  puts "This will delete user data. Are you sure? (y/n)"
+  response = gets.chomp
+  if response.downcase == 'y'
+    result = client.call_tool('delete_user', { user_id: 123 })
+  else
+    puts "Operation cancelled"
+  end
+else
+  # Safe to execute without confirmation
+  result = client.call_tool('get_user', { user_id: 123 })
+end
+```
+
+### Tool Annotation Helper Methods
+
+The `Tool` class provides convenient helper methods:
+
+- `tool.read_only?` - Returns true if the tool is marked as read-only
+- `tool.destructive?` - Returns true if the tool is marked as destructive
+- `tool.requires_confirmation?` - Returns true if the tool requires confirmation
+- `tool.annotations` - Returns the raw annotations hash
+
+### Example
+
+See `examples/test_tool_annotations.rb` for a complete working example demonstrating:
+- Listing tools with their annotations
+- Using annotation helper methods
+- Making annotation-aware decisions about tool execution
+- Handling destructive operations safely
+
+## Structured Tool Outputs
+
+MCP 2025-06-18 introduces structured tool outputs, allowing tools to declare output schemas and return type-safe, validated data structures instead of just text.
+
+### Overview
+
+Tools can now specify an `outputSchema` (JSON Schema) that defines the expected structure of their results. When called, they return data in a `structuredContent` field that validates against this schema, providing:
+
+- **Type safety** - Predictable, validated data structures
+- **Better IDE support** - Code completion and type checking
+- **Easier parsing** - No need to parse text or guess formats
+- **Backward compatibility** - Text content is still provided alongside structured data
+
+### Using Structured Outputs
+
+```ruby
+# List tools and check for structured output support
+tools = client.list_tools
+
+tools.each do |tool|
+  if tool.structured_output?
+    puts "#{tool.name} supports structured output"
+    puts "Output schema: #{tool.output_schema}"
+  end
+end
+
+# Call a tool that returns structured output
+result = client.call_tool('get_weather', { location: 'San Francisco' })
+
+# Access structured data (type-safe, validated)
+if result['structuredContent']
+  data = result['structuredContent']
+  puts "Temperature: #{data['temperature']}°C"
+  puts "Conditions: #{data['conditions']}"
+  puts "Humidity: #{data['humidity']}%"
+end
+
+# Backward compatibility: text content is still available
+text_content = result['content']&.first&.dig('text')
+parsed = JSON.parse(text_content) if text_content
+```
+
+### Helper Methods
+
+The `Tool` class provides a convenient helper method:
+
+- `tool.structured_output?` - Returns true if the tool has an output schema defined
+- `tool.output_schema` - Returns the JSON Schema for the tool's output
+
+### Example
+
+See `examples/test_structured_outputs.rb` for a complete working example demonstrating:
+- Detecting tools with structured output support
+- Accessing output schemas
+- Calling tools and receiving structured data
+- Backward compatibility with text content
+
+The example includes a Python MCP server (`examples/structured_output_server.py`) that provides three tools with structured outputs:
+- `get_weather` - Weather data with temperature, conditions, humidity
+- `analyze_text` - Text analysis with word count, character count, statistics
+- `calculate_stats` - Statistical calculations (mean, median, min, max, etc.)
+
+## Elicitation (Server-initiated User Interactions) - MCP 2025-06-18
+
+Elicitation enables MCP servers to request user input during tool execution via bidirectional JSON-RPC.
+This allows servers to gather additional information, confirm sensitive operations, or interact with users
+dynamically during the execution of tools.
+
+### Transport Support
+
+**Fully Supported:**
+- ✅ **stdio** - Full bidirectional JSON-RPC over stdin/stdout
+- ✅ **SSE** - Server sends requests via SSE stream, client responds via HTTP POST
+- ✅ **Streamable HTTP** - Server sends requests via SSE-formatted responses, client responds via HTTP POST
+
+**Not Supported:**
+- ❌ **HTTP** - Pure request-response architecture prevents server-initiated requests
+
+### Using Elicitation
+
+To use elicitation, register a handler when creating the client:
+
+```ruby
+# Define an elicitation handler
+elicitation_handler = lambda do |message, requested_schema|
+  puts "Server requests: #{message}"
+
+  # Show expected input format from schema
+  if requested_schema && requested_schema['properties']
+    requested_schema['properties'].each do |field, schema|
+      puts "  #{field}: #{schema['type']}"
+    end
+  end
+
+  # Prompt user and return one of three response types:
+
+  # 1. Accept and provide data to the server
+  {
+    'action' => 'accept',
+    'content' => {
+      'field_name' => 'user_input_value'
+    }
+  }
+
+  # 2. Decline to provide input
+  # { 'action' => 'decline' }
+
+  # 3. Cancel the operation
+  # { 'action' => 'cancel' }
+end
+
+# Create client with elicitation handler
+# Works with stdio, SSE, and Streamable HTTP transports
+client = MCPClient::Client.new(
+  mcp_server_configs: [
+    # Stdio transport
+    MCPClient.stdio_config(
+      command: 'python my_server.py',
+      name: 'my-server'
+    ),
+    # Or SSE transport
+    MCPClient.sse_config(
+      base_url: 'https://api.example.com/sse',
+      name: 'remote-server'
+    ),
+    # Or Streamable HTTP transport
+    MCPClient.streamable_http_config(
+      base_url: 'https://api.example.com',
+      endpoint: '/mcp',
+      name: 'streamable-server'
+    )
+  ],
+  elicitation_handler: elicitation_handler
+)
+
+# Call tools - connection happens automatically
+# Server may send elicitation requests during tool execution
+result = client.call_tool('create_document', { format: 'markdown' }, server: 'my-server')
+```
+
+### Response Actions
+
+The elicitation handler should return a hash with an `action` field:
+
+1. **Accept** - Provide the requested input:
+   ```ruby
+   {
+     'action' => 'accept',
+     'content' => { 'field' => 'value' }  # Must match requested schema
+   }
+   ```
+
+2. **Decline** - Refuse to provide input (server should handle gracefully):
+   ```ruby
+   { 'action' => 'decline' }
+   ```
+
+3. **Cancel** - Cancel the entire operation:
+   ```ruby
+   { 'action' => 'cancel' }
+   ```
+
+### Example
+
+See `examples/elicitation/test_elicitation.rb` for a complete working example demonstrating:
+- Registering an elicitation handler
+- Handling different message types and schemas
+- Responding with accept/decline/cancel actions
+- Interactive user prompts during tool execution
+
+The example includes a Python MCP server (`examples/elicitation/elicitation_server.py`) that provides tools using elicitation:
+- `create_document` - Requests title and content via elicitation
+- `send_notification` - Confirms before sending a notification
+
 ## Key Features
 
 ### Client Features
@@ -918,6 +1257,9 @@ end
 - **Server lookup** - Find servers by name using `find_server`
 - **Tool association** - Each tool knows which server it belongs to
 - **Tool discovery** - Find tools by name or pattern
+- **Structured outputs** - Support for MCP 2025-06-18 structured tool outputs with output schemas and type-safe responses
+- **Tool annotations** - Support for readOnly, destructive, and requiresConfirmation annotations with helper methods
+- **Elicitation support** - Server-initiated user interactions during tool execution (stdio, SSE, and Streamable HTTP transports)
 - **Server disambiguation** - Specify which server to use when tools with same name exist in multiple servers
 - **Atomic tool calls** - Simple API for invoking tools with parameters
 - **Batch support** - Call multiple tools in a single operation