ruby-mcp-client 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa54ff918901d9386e2d395408c4ae23707cdc7b0f7162f348e31d24c163bc39
-  data.tar.gz: 77b384d45849e900e11b49647602cbd681511c39ae4a03cabdbfc3571f4cf38d
+  metadata.gz: 0f797750d8f5a6f1b742411418f77c8352cc89e8879e77ba51bcb7257f9de6db
+  data.tar.gz: 104e26ec1506bebae21b5b4e70508db0159d3ef8b9b69148720fed202633d7e8
 SHA512:
-  metadata.gz: 8702eef3f53b5a77f5323d215d8be67678cb5148163443b94f986c03933366b23b1eeac5428e0ccbe4448aa9bf3a322f6556a29383c9c22c697685bcd483143e
-  data.tar.gz: 108332fb14663b1c65363b4b78766fee383a0b48ee8ff5f621dabf0b340accaf435e790246713f23e1cb0653b3852b2d3bbe9725e321202933b2d8ecf6fa1d3b
+  metadata.gz: 20aa894d62ed87e70d50f92b7ce4b60839855f7ce9697f476c7822dcf99167f62030bfbd90f1d5c50d535cc78a075e35f25086e0b3f09d57c3d0bd9f4c8ff35e
+  data.tar.gz: dd252c97f599834a3f1e4f9a3acf0c7e98489c247c4601a3d038f8af646c431ef0245ed00b33cb61ea387c296ee5c63c99a8487bf8b9b3ed68be5bfd4e5a5f55

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:
@@ -56,7 +58,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 +66,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 +92,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 +158,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 +436,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 +478,82 @@ 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.
+
 ## 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 +598,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 +648,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

data/lib/mcp_client/client.rb

@@ -70,7 +70,7 @@ module MCPClient
       if tools.empty? && !servers.empty?
         raise connection_errors.first if connection_errors.any?
 
-        raise MCPClient::Errors::ToolCallError, 'Failed to retrieve tools from any server'
+        @logger.warn('No tools found from any server.')
       end
 
       tools

data/lib/mcp_client/config_parser.rb

@@ -87,6 +87,10 @@ module MCPClient
         parse_stdio_config(clean, config, server_name)
       when 'sse'
         return nil unless parse_sse_config(clean, config, server_name)
+      when 'streamable_http'
+        return nil unless parse_streamable_http_config(clean, config, server_name)
+      when 'http'
+        return nil unless parse_http_config(clean, config, server_name)
       else
         @logger.warn("Unrecognized type '#{type}' for server '#{server_name}'; skipping.")
         return nil
@@ -106,7 +110,9 @@ module MCPClient
       inferred_type = if config.key?('command') || config.key?('args') || config.key?('env')
                         'stdio'
                       elsif config.key?('url')
-                        'sse'
+                        # Default to streamable_http unless URL contains "sse"
+                        url = config['url'].to_s.downcase
+                        url.include?('sse') ? 'sse' : 'streamable_http'
                       end
 
       if inferred_type
@@ -181,6 +187,72 @@ module MCPClient
       true
     end
 
+    # Parse Streamable HTTP-specific configuration
+    # @param clean [Hash] clean configuration hash to update
+    # @param config [Hash] raw configuration from JSON
+    # @param server_name [String] name of the server for error reporting
+    # @return [Boolean] true if parsing succeeded, false if required elements are missing
+    def parse_streamable_http_config(clean, config, server_name)
+      # URL is required
+      source = config['url']
+      unless source
+        @logger.warn("Streamable HTTP server '#{server_name}' is missing required 'url' property; skipping.")
+        return false
+      end
+
+      unless source.is_a?(String)
+        @logger.warn("'url' for server '#{server_name}' is not a string; converting to string.")
+        source = source.to_s
+      end
+
+      # Headers are optional
+      headers = config['headers']
+      headers = headers.is_a?(Hash) ? headers.transform_keys(&:to_s) : {}
+
+      # Endpoint is optional (defaults to '/rpc' in the transport)
+      endpoint = config['endpoint']
+      endpoint = endpoint.to_s if endpoint && !endpoint.is_a?(String)
+
+      # Update clean config
+      clean[:url] = source
+      clean[:headers] = headers
+      clean[:endpoint] = endpoint if endpoint
+      true
+    end
+
+    # Parse HTTP-specific configuration
+    # @param clean [Hash] clean configuration hash to update
+    # @param config [Hash] raw configuration from JSON
+    # @param server_name [String] name of the server for error reporting
+    # @return [Boolean] true if parsing succeeded, false if required elements are missing
+    def parse_http_config(clean, config, server_name)
+      # URL is required
+      source = config['url']
+      unless source
+        @logger.warn("HTTP server '#{server_name}' is missing required 'url' property; skipping.")
+        return false
+      end
+
+      unless source.is_a?(String)
+        @logger.warn("'url' for server '#{server_name}' is not a string; converting to string.")
+        source = source.to_s
+      end
+
+      # Headers are optional
+      headers = config['headers']
+      headers = headers.is_a?(Hash) ? headers.transform_keys(&:to_s) : {}
+
+      # Endpoint is optional (defaults to '/rpc' in the transport)
+      endpoint = config['endpoint']
+      endpoint = endpoint.to_s if endpoint && !endpoint.is_a?(String)
+
+      # Update clean config
+      clean[:url] = source
+      clean[:headers] = headers
+      clean[:endpoint] = endpoint if endpoint
+      true
+    end
+
     # Filter out reserved keys from configuration objects
     # @param data [Hash] configuration data
     # @return [Hash] filtered configuration data