ruby-mcp-client 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27b97462ec0c99d98299df120726f90944f495aaddf198272d72725544240ec0
-  data.tar.gz: b58b8a6ba53f698abe1cb3576fba8030d66cb0bd7eafa2e39e28943e7ef1337f
+  metadata.gz: a5e35c00292938e3c6cd17885d6578e465d12853ed1844f67dc4633096bb2fa3
+  data.tar.gz: e9419a3969689a0768ea8290f2a45f5214fcc4b74521ac38aac3bfd842b7ec49
 SHA512:
-  metadata.gz: 50d5791642a74f521133a057d924d3daf14e657ec617e73ad8f95510b4d97f3d52742c5a467c54d75dc02030a087f29e63ee346429271e8c80eb71cb96e38f94
-  data.tar.gz: 5f92d87a5d176e3271a11e9bbea7eafc6720107c6ae795601250e088cde69e6d6340911eecd6ea8ab32776d97d9bfb0b4d3740087509eb704cb400bf4e23e5aa
+  metadata.gz: 063bc6c91cf5d6e82a05b17dd90519e07d3168baf5efb36969e98d0893d40f4d630db3181dfd28929fc255f579780c041b407dfd8bfec17f3461022f2cb84471
+  data.tar.gz: e92a6c8d29474c08966008f9e2e5f530520258f546b40694fc0245eaf3da2ad6064ce7bb312596a07d5e4a94f4516603256c2bd7375cfc67065180f636f64eb1

data/README.md

@@ -40,17 +40,22 @@ 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
 - **FastMCP Compatibility** - Full compatibility with FastMCP servers including proper line ending handling
 - **Prompts Support** - Full implementation of MCP prompts for dynamic content generation
-- **Resources Support** - Complete resources implementation for accessing files and data with URI-based identification
+- **Resources Support** - Full MCP resources specification compliance including templates, subscriptions, pagination, and annotations
 
 ## Usage
 
@@ -165,11 +170,30 @@ result = client.get_prompt('greeting', { name: 'Ruby Developer' })
 result = client.get_prompt('greeting', { name: 'Ruby Developer' }, server: 'filesystem')
 
 # === Working with Resources ===
-# List available resources from all servers
-resources = client.list_resources
+# List available resources from all servers (returns hash with 'resources' array and optional 'nextCursor')
+result = client.list_resources
+resources = result['resources']  # Array of Resource objects from all servers
+next_cursor = result['nextCursor']  # nil when aggregating multiple servers
+
+# Get resources from a specific server with pagination support
+result = client.servers.first.list_resources
+resources = result['resources']  # Array of Resource objects
+next_cursor = result['nextCursor']  # For pagination
 
-# Read a specific resource by URI
+# List resources with pagination (only works with single server or client.list_resources with cursor)
+result = client.list_resources(cursor: next_cursor)  # Uses first server when cursor provided
+
+# Read a specific resource by URI (returns array of ResourceContent objects)
 contents = client.read_resource('file:///example.txt')
+contents.each do |content|
+  if content.text?
+    puts content.text  # Text content
+  elsif content.binary?
+    data = Base64.decode64(content.blob)  # Binary content
+  end
+  puts content.mime_type if content.mime_type
+  puts content.annotations if content.annotations  # Optional metadata
+end
 
 # Read a resource from a specific server
 contents = client.read_resource('file:///example.txt', server: 'filesystem')
@@ -413,11 +437,16 @@ prompts.each { |prompt| puts "- #{prompt.name}: #{prompt.description}" }
 greeting = client.get_prompt('greeting', { name: 'Ruby Developer' })
 
 # List and read resources
-resources = client.list_resources
+result = client.list_resources
+resources = result['resources']
 puts "Found #{resources.length} resources:"
 resources.each { |resource| puts "- #{resource.name} (#{resource.uri})" }
 
-readme_content = client.read_resource('file:///sample/README.md')
+# Read resource (returns array of ResourceContent objects)
+contents = client.read_resource('file:///sample/README.md')
+contents.each do |content|
+  puts content.text if content.text?
+end
 ```
 
 #### Streamable HTTP Example
@@ -557,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:
@@ -753,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
@@ -761,9 +875,378 @@ 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).
 
+## Resources
+
+The Ruby MCP Client provides full support for the MCP resources specification, enabling access to files, data, and other content with URI-based identification.
+
+### Resource Features
+
+- **Resource listing** with cursor-based pagination
+- **Resource templates** with URI patterns (RFC 6570)
+- **Resource subscriptions** for real-time updates
+- **Binary content support** with base64 encoding
+- **Resource annotations** for metadata (audience, priority, lastModified)
+- **ResourceContent objects** for structured content access
+
+### Resource API
+
+```ruby
+# Get a server instance
+server = client.servers.first  # or client.find_server('name')
+
+# List resources with pagination
+result = server.list_resources
+resources = result['resources']  # Array of Resource objects
+next_cursor = result['nextCursor']  # String cursor for next page (if any)
+
+# Get next page of resources
+if next_cursor
+  next_result = server.list_resources(cursor: next_cursor)
+end
+
+# Access Resource properties
+resource = resources.first
+resource.uri         # "file:///example.txt"
+resource.name        # "example.txt"
+resource.title       # Optional human-readable title
+resource.description # Optional description
+resource.mime_type   # "text/plain"
+resource.size        # Optional file size in bytes
+resource.annotations # Optional metadata hash
+
+# Read resource contents (returns array of ResourceContent objects)
+contents = server.read_resource(resource.uri)
+
+contents.each do |content|
+  # Check content type
+  if content.text?
+    # Text content
+    text = content.text
+    mime = content.mime_type  # e.g., "text/plain"
+  elsif content.binary?
+    # Binary content (base64 encoded)
+    blob = content.blob  # Base64 string
+    data = Base64.decode64(blob)  # Decoded binary data
+  end
+
+  # Access optional annotations
+  if content.annotations
+    audience = content.annotations['audience']  # e.g., ["user", "assistant"]
+    priority = content.annotations['priority']  # e.g., 0.5
+    modified = content.annotations['lastModified']  # ISO 8601 timestamp
+  end
+end
+
+# List resource templates
+templates_result = server.list_resource_templates
+templates = templates_result['resourceTemplates']  # Array of ResourceTemplate objects
+
+template = templates.first
+template.uri_template  # "file:///{path}" (RFC 6570 URI template)
+template.name         # Template name
+template.title        # Optional title
+template.description  # Optional description
+template.mime_type    # Optional MIME type hint
+
+# Subscribe to resource updates
+server.subscribe_resource('file:///watched.txt')  # Returns true on success
+
+# Unsubscribe from resource updates
+server.unsubscribe_resource('file:///watched.txt')  # Returns true on success
+
+# Check server capabilities for resources
+capabilities = server.capabilities
+if capabilities['resources']
+  can_subscribe = capabilities['resources']['subscribe']  # true/false
+  list_changed = capabilities['resources']['listChanged']  # true/false
+end
+```
+
+### Working with ResourceContent
+
+The `ResourceContent` class provides a structured way to handle both text and binary content:
+
+```ruby
+# ResourceContent for text
+content = MCPClient::ResourceContent.new(
+  uri: 'file:///example.txt',
+  name: 'example.txt',
+  mime_type: 'text/plain',
+  text: 'File contents here',
+  annotations: {
+    'audience' => ['user'],
+    'priority' => 1.0
+  }
+)
+
+# ResourceContent for binary data
+binary_content = MCPClient::ResourceContent.new(
+  uri: 'file:///image.png',
+  name: 'image.png',
+  mime_type: 'image/png',
+  blob: Base64.strict_encode64(binary_data)
+)
+
+# Access content
+if content.text?
+  puts content.text
+elsif content.binary?
+  data = Base64.decode64(content.blob)
+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
@@ -774,6 +1257,9 @@ For complete OAuth documentation, see [OAUTH.md](OAUTH.md).
 - **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