ruby-mcp-client 0.6.2 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15f194d4e1504310a998aeeb819e5851dea4f1f8049bf494368ad5494e611d3c
-  data.tar.gz: 93d8d00a95ab2436241b09253d7bb56d130122303c1e78c429cecc343d09fa82
+  metadata.gz: 94f8597a5cddfa1f86b6e09401b652d2c7aa3bd4eefc8771712b7c03d99772a8
+  data.tar.gz: b303e3056719fea1a62cf4eeff76156e6e3ed68d134d48aa3ce969e8095d85be
 SHA512:
-  metadata.gz: f7edb3c0ae40b647c03d3a70af06e08b7d1290de0326fcf34b668b08f1fb156692799e1280f4a3a17c44b9afdb18b456d949a1cc39edec396877a25a00290c8f
-  data.tar.gz: a169f6e4f24c9f1f4ed52e7853f00285565cfcd2aa2d8fe6049c10191dd2fcbf571c8468dea65bf6504175f1ca1ce402ad9d7353660888db2f96e57831056598
+  metadata.gz: da1d04e7aee8207ff32a2db24df14c2b832b8f5fd6acf36c6b8f22b86cf802d99de5514a608a6336f1973949a34a8829c8f71a5b2dadc68ebff50ed7d4d23bc7
+  data.tar.gz: e75630074326e81fddbc006f3bcd8b848c474792ac73c2e9f883722b49b0aeb2da31bb824263234599b279974c7c2445ce6d4d06766a0e447753e8060b248d8f

data/README.md

@@ -30,6 +30,8 @@ via different transport mechanisms:
 
 - **Standard I/O**: Local processes implementing the MCP protocol
 - **Server-Sent Events (SSE)**: Remote MCP servers over HTTP with streaming support
+- **HTTP**: Remote MCP servers over HTTP request/response (non-streaming Streamable HTTP)
+- **Streamable HTTP**: Remote MCP servers that use HTTP POST with Server-Sent Event formatted responses
 
 The core client resides in `MCPClient::Client` and provides helper methods for integrating
 with popular AI services with built-in conversions:
@@ -38,6 +40,14 @@ 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
+
+This Ruby MCP Client implements key features from the latest MCP specification (Protocol Revision: 2025-03-26):
+
+### Implemented Features
+- **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
+
 ## Usage
 
 ### Basic Client Usage
@@ -56,7 +66,7 @@ client = MCPClient.create_client(
     MCPClient.sse_config(
       base_url: 'https://api.example.com/sse',
       headers: { 'Authorization' => 'Bearer YOUR_TOKEN' },
-      name: 'api',      # Optional name for this server
+      name: 'sse_api',  # Optional name for this server
       read_timeout: 30, # Optional timeout in seconds (default: 30)
       ping: 10,         # Optional ping interval in seconds of inactivity (default: 10)
                         # Connection closes automatically after inactivity (2.5x ping interval)
@@ -64,7 +74,19 @@ client = MCPClient.create_client(
       retry_backoff: 1, # Optional backoff delay in seconds (default: 1)
       # Native support for tool streaming via call_tool_streaming method
       logger: Logger.new($stdout, level: Logger::INFO) # Optional logger for this server
-)  ],
+    ),
+    # Remote HTTP server (request/response without streaming)
+    MCPClient.http_config(
+      base_url: 'https://api.example.com',
+      endpoint: '/rpc', # Optional JSON-RPC endpoint path (default: '/rpc')
+      headers: { 'Authorization' => 'Bearer YOUR_TOKEN' },
+      name: 'http_api', # Optional name for this server
+      read_timeout: 30, # Optional timeout in seconds (default: 30)
+      retries: 3,       # Optional number of retry attempts (default: 3)
+      retry_backoff: 1, # Optional backoff delay in seconds (default: 1)
+      logger: Logger.new($stdout, level: Logger::INFO) # Optional logger for this server
+    )
+  ],
   # Optional logger for the client and all servers without explicit loggers
   logger: Logger.new($stdout, level: Logger::WARN)
 )
@@ -78,11 +100,12 @@ client = MCPClient.create_client(
 # MCP server configuration JSON format can be:
 # 1. A single server object: 
 #    { "type": "sse", "url": "http://example.com/sse" }
+#    { "type": "http", "url": "http://example.com", "endpoint": "/rpc" }
 # 2. An array of server objects: 
-#    [{ "type": "stdio", "command": "npx server" }, { "type": "sse", "url": "http://..." }]
+#    [{ "type": "stdio", "command": "npx server" }, { "type": "sse", "url": "http://..." }, { "type": "http", "url": "http://..." }]
 # 3. An object with "mcpServers" key containing named servers:
-#    { "mcpServers": { "server1": { "type": "sse", "url": "http://..." } } }
-#    Note: When using this format, server1 will be accessible by name
+#    { "mcpServers": { "server1": { "type": "sse", "url": "http://..." }, "server2": { "type": "http", "url": "http://..." } } }
+#    Note: When using this format, server1/server2 will be accessible by name
 
 # List available tools
 tools = client.list_tools
@@ -143,6 +166,114 @@ client.clear_cache
 client.cleanup
 ```
 
+### HTTP Transport Example
+
+The HTTP transport provides simple request/response communication with MCP servers:
+
+```ruby
+require 'mcp_client'
+require 'logger'
+
+# Optional logger for debugging
+logger = Logger.new($stdout)
+logger.level = Logger::INFO
+
+# Create an MCP client that connects to an HTTP MCP server
+http_client = MCPClient.create_client(
+  mcp_server_configs: [
+    MCPClient.http_config(
+      base_url: 'https://api.example.com',
+      endpoint: '/mcp',     # JSON-RPC endpoint path
+      headers: {
+        'Authorization' => 'Bearer YOUR_API_TOKEN',
+        'X-Custom-Header' => 'custom-value'
+      },
+      read_timeout: 30,     # Timeout in seconds for HTTP requests
+      retries: 3,           # Number of retry attempts on transient errors
+      retry_backoff: 1,     # Base delay in seconds for exponential backoff
+      logger: logger        # Optional logger for debugging HTTP requests
+    )
+  ]
+)
+
+# List available tools
+tools = http_client.list_tools
+
+# Call a tool
+result = http_client.call_tool('analyze_data', { 
+  dataset: 'sales_2024',
+  metrics: ['revenue', 'conversion_rate']
+})
+
+# HTTP transport also supports streaming (though implemented as single response)
+# This provides API compatibility with SSE transport
+http_client.call_tool_streaming('process_batch', { batch_id: 123 }).each do |result|
+  puts "Processing result: #{result}"
+end
+
+# Send custom JSON-RPC requests
+custom_result = http_client.send_rpc('custom_method', params: { key: 'value' })
+
+# Send notifications (fire-and-forget)
+http_client.send_notification('status_update', params: { status: 'processing' })
+
+# Test connectivity
+ping_result = http_client.ping
+puts "Server is responsive: #{ping_result.inspect}"
+
+# Clean up
+http_client.cleanup
+```
+
+### Streamable HTTP Transport Example
+
+The Streamable HTTP transport is designed for servers that use HTTP POST requests but return Server-Sent Event formatted responses. This is commonly used by services like Zapier's MCP implementation:
+
+```ruby
+require 'mcp_client'
+require 'logger'
+
+# Optional logger for debugging
+logger = Logger.new($stdout)
+logger.level = Logger::INFO
+
+# Create an MCP client that connects to a Streamable HTTP MCP server
+streamable_client = MCPClient.create_client(
+  mcp_server_configs: [
+    MCPClient.streamable_http_config(
+      base_url: 'https://mcp.zapier.com/api/mcp/s/YOUR_SESSION_ID/mcp',
+      headers: {
+        'Authorization' => 'Bearer YOUR_ZAPIER_TOKEN'
+      },
+      read_timeout: 60,     # Timeout in seconds for HTTP requests
+      retries: 3,           # Number of retry attempts on transient errors
+      retry_backoff: 2,     # Base delay in seconds for exponential backoff
+      logger: logger        # Optional logger for debugging requests
+    )
+  ]
+)
+
+# List available tools (server responds with SSE-formatted JSON)
+tools = streamable_client.list_tools
+puts "Found #{tools.size} tools:"
+tools.each { |tool| puts "- #{tool.name}: #{tool.description}" }
+
+# Call a tool (response will be in SSE format)
+result = streamable_client.call_tool('google_calendar_find_event', {
+  instructions: 'Find today\'s meetings',
+  calendarid: 'primary'
+})
+
+# The client automatically parses SSE responses like:
+# event: message
+# data: {"jsonrpc":"2.0","id":1,"result":{"content":[...]}}
+
+puts "Tool result: #{result.inspect}"
+
+# Clean up
+streamable_client.cleanup
+```
+
 ### Server-Sent Events (SSE) Example
 
 The SSE transport provides robust connection handling for remote MCP servers:
@@ -313,6 +444,15 @@ You can define MCP server configurations in JSON files for easier management:
         "Authorization": "Bearer TOKEN"
       }
     },
+    "api_server": {
+      "type": "http",
+      "url": "https://api.example.com",
+      "endpoint": "/mcp",
+      "headers": {
+        "Authorization": "Bearer API_TOKEN",
+        "X-Custom-Header": "value"
+      }
+    },
     "filesystem": {
       "type": "stdio",
       "command": "npx",
@@ -346,20 +486,145 @@ client = MCPClient.create_client(server_definition_file: 'path/to/definition.jso
 ```
 
 The JSON format supports:
-1. A single server object: `{ "type": "sse", "url": "..." }`
-2. An array of server objects: `[{ "type": "stdio", ... }, { "type": "sse", ... }]`
+1. A single server object: `{ "type": "sse", "url": "..." }` or `{ "type": "http", "url": "..." }`
+2. An array of server objects: `[{ "type": "stdio", ... }, { "type": "sse", ... }, { "type": "http", ... }]`
 3. An object with named servers under `mcpServers` key (as shown above)
 
 Special configuration options:
 - `comment` and `description` are reserved keys that are ignored during parsing and can be used for documentation
-- Server type can be inferred from the presence of either `command` (for stdio) or `url` (for SSE)
+- Server type can be inferred from the presence of either `command` (for stdio) or `url` (for SSE/HTTP)
+- For HTTP servers, `endpoint` specifies the JSON-RPC endpoint path (defaults to '/rpc' if not specified)
 - All string values in arrays (like `args`) are automatically converted to strings
 
+## Session-Based MCP Protocol Support
+
+Both HTTP and Streamable HTTP transports now support session-based MCP servers that require session continuity:
+
+### Session Management Features
+
+- **Automatic Session Management**: Captures session IDs from `initialize` response headers
+- **Session Header Injection**: Automatically includes `Mcp-Session-Id` header in subsequent requests
+- **Session Termination**: Sends HTTP DELETE requests to properly terminate sessions during cleanup
+- **Session Validation**: Validates session ID format for security (8-128 alphanumeric characters with hyphens/underscores)
+- **Backward Compatibility**: Works with both session-based and stateless MCP servers
+- **Session Cleanup**: Properly cleans up session state during connection teardown
+
+### Resumability and Redelivery (Streamable HTTP)
+
+The Streamable HTTP transport provides additional resumability features for reliable message delivery:
+
+- **Event ID Tracking**: Automatically tracks event IDs from SSE responses
+- **Last-Event-ID Header**: Includes `Last-Event-ID` header in requests for resuming from disconnection points
+- **Message Replay**: Enables servers to replay missed messages from the last received event
+- **Connection Recovery**: Maintains message continuity even with unstable network connections
+
+### Security Features
+
+Both transports implement security best practices:
+
+- **URL Validation**: Validates server URLs to ensure only HTTP/HTTPS protocols are used
+- **Session ID Validation**: Enforces secure session ID formats to prevent malicious injection
+- **Security Warnings**: Logs warnings for potentially insecure configurations (e.g., 0.0.0.0 binding)
+- **Header Sanitization**: Properly handles and validates all session-related headers
+
+### Usage
+
+The session support is transparent to the user - no additional configuration is required. The client will automatically detect and handle session-based servers by:
+
+1. **Session Initialization**: Capturing the `Mcp-Session-Id` header from the `initialize` response
+2. **Session Persistence**: Including this header in all subsequent requests (except `initialize`)
+3. **Session Termination**: Sending HTTP DELETE request with session ID during cleanup
+4. **Resumability** (Streamable HTTP): Tracking event IDs and including `Last-Event-ID` for message replay
+5. **Security Validation**: Validating session IDs and server URLs for security
+6. **Logging**: Comprehensive logging of session activity for debugging purposes
+
+Example of automatic session termination:
+
+```ruby
+# Session is automatically terminated when client is cleaned up
+client = MCPClient.create_client(
+  mcp_server_configs: [
+    MCPClient.http_config(base_url: 'https://api.example.com/mcp')
+  ]
+)
+
+# Use the client...
+tools = client.list_tools
+
+# Session automatically terminated with HTTP DELETE request
+client.cleanup
+```
+
+This enables compatibility with MCP servers that maintain state between requests and require session identification.
+
+## OAuth 2.1 Authentication
+
+The Ruby MCP Client includes comprehensive OAuth 2.1 support for secure authentication with MCP servers:
+
+```ruby
+require 'mcp_client'
+
+# Create an OAuth-enabled HTTP server
+server = MCPClient::OAuthClient.create_http_server(
+  server_url: 'https://api.example.com/mcp',
+  redirect_uri: 'http://localhost:8080/callback',
+  scope: 'mcp:read mcp:write'
+)
+
+# Check if authorization is needed
+unless MCPClient::OAuthClient.valid_token?(server)
+  # Start OAuth flow
+  auth_url = MCPClient::OAuthClient.start_oauth_flow(server)
+  puts "Please visit: #{auth_url}"
+
+  # After user authorization, complete the flow
+  # token = MCPClient::OAuthClient.complete_oauth_flow(server, code, state)
+end
+
+# Use the server normally
+server.connect
+tools = server.list_tools
+```
+
+### Manual OAuth Provider
+
+For more control over the OAuth flow:
+
+```ruby
+# Create OAuth provider directly
+oauth_provider = MCPClient::Auth::OAuthProvider.new(
+  server_url: 'https://api.example.com/mcp',
+  redirect_uri: 'http://localhost:8080/callback',
+  scope: 'mcp:read mcp:write'
+)
+
+# Update configuration at runtime
+oauth_provider.scope = 'mcp:read mcp:write admin'
+oauth_provider.redirect_uri = 'http://localhost:9000/callback'
+
+# Start authorization flow
+auth_url = oauth_provider.start_authorization_flow
+
+# Complete flow after user authorization
+token = oauth_provider.complete_authorization_flow(code, state)
+```
+
+### OAuth Features
+
+- **OAuth 2.1 compliance** with PKCE for security
+- **Automatic server discovery** via `.well-known` endpoints
+- **Dynamic client registration** when supported by servers
+- **Token refresh** and automatic token management
+- **Pluggable storage** for tokens and client credentials
+- **Runtime configuration** via getter/setter methods
+
+For complete OAuth documentation, see [OAUTH.md](OAUTH.md).
+
 ## Key Features
 
 ### Client Features
 
-- **Multiple transports** - Support for both stdio and SSE transports
+- **Multiple transports** - Support for stdio, SSE, HTTP, and Streamable HTTP transports
 - **Multiple servers** - Connect to multiple MCP servers simultaneously
 - **Named servers** - Associate names with servers and find/reference them by name
 - **Server lookup** - Find servers by name using `find_server`
@@ -404,6 +669,47 @@ The SSE client implementation provides these key features:
 - **URL normalization**: Consistent URL handling that respects user-provided formats
 - **Server connectivity check**: Built-in `ping` method to test server connectivity and health
 
+### HTTP Transport Implementation
+
+The HTTP transport provides a simpler, stateless communication mechanism for MCP servers:
+
+- **Request/Response Model**: Standard HTTP request/response cycle for each JSON-RPC call
+- **JSON-Only Responses**: Accepts only `application/json` responses (no SSE support)
+- **Session Support**: Automatic session header (`Mcp-Session-Id`) capture and injection for session-based MCP servers
+- **Session Termination**: Proper session cleanup with HTTP DELETE requests during connection teardown
+- **Session Validation**: Security validation of session IDs to prevent malicious injection
+- **Stateless & Stateful**: Supports both stateless servers and session-based servers that require state continuity
+- **HTTP Headers Support**: Full support for custom headers including authorization, API keys, and other metadata
+- **Reliable Error Handling**: Comprehensive HTTP status code handling with appropriate error mapping
+- **Configurable Retries**: Exponential backoff retry logic for transient network failures
+- **Connection Pooling**: Uses Faraday's connection pooling for efficient HTTP connections
+- **Timeout Management**: Configurable timeouts for both connection establishment and request completion
+- **JSON-RPC over HTTP**: Full JSON-RPC 2.0 implementation over HTTP POST requests
+- **MCP Protocol Compliance**: Supports all standard MCP methods (initialize, tools/list, tools/call)
+- **Custom RPC Methods**: Send any custom JSON-RPC method or notification
+- **Thread Safety**: All operations are thread-safe for concurrent usage
+- **Streaming API Compatibility**: Provides `call_tool_streaming` method for API compatibility (returns single response)
+- **Graceful Degradation**: Simple fallback behavior when complex features aren't needed
+
+### Streamable HTTP Transport Implementation
+
+The Streamable HTTP transport bridges HTTP and Server-Sent Events, designed for servers that use HTTP POST but return SSE-formatted responses:
+
+- **Hybrid Communication**: HTTP POST requests with Server-Sent Event formatted responses
+- **SSE Response Parsing**: Automatically parses `event:` and `data:` lines from SSE responses
+- **Session Support**: Automatic session header (`Mcp-Session-Id`) capture and injection for session-based MCP servers
+- **Session Termination**: Proper session cleanup with HTTP DELETE requests during connection teardown
+- **Resumability**: Event ID tracking and `Last-Event-ID` header support for message replay after disconnections
+- **Session Validation**: Security validation of session IDs to prevent malicious injection
+- **HTTP Semantics**: Maintains standard HTTP request/response model for client compatibility
+- **Streaming Format Support**: Handles complex SSE responses with multiple fields (event, id, retry, etc.)
+- **Error Handling**: Comprehensive error handling for both HTTP and SSE parsing failures
+- **Headers Optimization**: Includes SSE-compatible headers (`Accept: text/event-stream, application/json`, `Cache-Control: no-cache`)
+- **JSON-RPC Compliance**: Full JSON-RPC 2.0 support over the hybrid HTTP/SSE transport
+- **Retry Logic**: Exponential backoff for both connection and parsing failures
+- **Thread Safety**: All operations are thread-safe for concurrent usage
+- **Malformed Response Handling**: Graceful handling of invalid SSE format or missing data lines
+
 ## Requirements
 
 - Ruby >= 3.2.0
@@ -413,7 +719,7 @@ The SSE client implementation provides these key features:
 
 To implement a compatible MCP server you must:
 
-- Listen on your chosen transport (JSON-RPC stdio, or HTTP SSE)
+- Listen on your chosen transport (JSON-RPC stdio, HTTP SSE, HTTP, or Streamable HTTP)
 - Respond to `list_tools` requests with a JSON list of tools
 - Respond to `call_tool` requests by executing the specified tool
 - Return results (or errors) in JSON format