mcp-sdk.rb 0.1.1 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 144a7bc5d730857d1ea77754f36046acf3e12fcd043f3f84b709e19f8d2c6f99
-  data.tar.gz: 492711d7e4b5796548f669d593eff579dc906ea3eeabdf29839c25187e2d0b32
+  metadata.gz: 4a9f49fa38172f0c33f2294a0854871f9dbd0ba3e8a7ee2b68d168fff64f2bbf
+  data.tar.gz: 25a48fe35af5cbdf85e36cddde8ece4d1628e1a72a728d4c78eb66eefb4a9284
 SHA512:
-  metadata.gz: 60f59abaa36e97a5cae62385e4a9034885d29dd8d6447311f7b87e4805bd87fd198308a3d3d3da8c81487b6a1a8f254bf8f3e28bd5c11476712d52dea85be491
-  data.tar.gz: cd9a155aa772476ffaa2c7cf3aa8ae509dd824292483e5133168df86bbdf5ef7522e88c8bd38e7df9b711d71c48e881d0cb031a1db55cd0eab10e7fa651d44d1
+  metadata.gz: 35a216611ff9232bac3b3791f45e36317c02067e3cdcf273fe40861a4faa0946f85c861631d29d08b4987724fd9a18ff229e5385b7c2a8501bf529ba3cc3880d
+  data.tar.gz: c0fda6f709b4ac25aefd98a45b17c7991b53a97f48790eeef1ce09f8c7efb2489e433deba8048862aa6c8176a88435aada59f56fed39b2a5d63653d9b21df656

data/README.md

@@ -2,14 +2,16 @@
 
 [![Gem Version](https://badge.fury.io/rb/mcp-sdk.rb.svg)](https://badge.fury.io/rb/mcp-sdk.rb)
 
-A Ruby implementation of the Model Context Protocol (MCP) for connecting to MCP servers.
+A Ruby implementation of the Model Context Protocol (MCP) for both connecting to MCP servers and creating MCP servers.
 
 ## Features
 
-- Supports both SSE (Server-Sent Events) and Stdio-based MCP servers
-- Type-safe client interfaces
+- **Client Support**: Connect to SSE (Server-Sent Events) and Stdio-based MCP servers
+- **Server Support**: Create MCP servers with tool registration
+- Type-safe client interfaces  
 - Easy integration with Ruby applications
 - Comprehensive error handling
+- JSON-RPC 2.0 compliant
 
 ## Installation
 
@@ -33,7 +35,9 @@ $ gem install mcp-sdk.rb
 
 ## Usage
 
-### Connecting to an SSE-based MCP server
+### MCP Client
+
+#### Connecting to an SSE-based MCP server
 
 ```ruby
 require 'mcp-sdk.rb'
@@ -43,7 +47,7 @@ mcp_server_json = client.list_tools
 puts JSON.pretty_generate(convertFormat(mcp_server_json))
 ```
 
-### Connecting to a Stdio-based MCP server
+#### Connecting to a Stdio-based MCP server
 
 ```ruby
 require 'mcp-sdk.rb'
@@ -54,6 +58,285 @@ mcp_server_json = client.list_tools
 puts JSON.pretty_generate(convertFormat(mcp_server_json))
 ```
 
+### MCP Server
+
+#### Creating an MCP Server
+
+**Stdio Server (Default)**
+```ruby
+require 'mcp-sdk.rb'
+
+# Create stdio server (processes JSON-RPC over stdin/stdout)
+server = MCP::Server.new(
+  name: "Demo",
+  version: "1.0.0",
+  type: "stdio"  # optional, this is the default
+)
+
+# Add an addition tool
+server.add_tool("add") do |params|
+  result = params["a"] + params["b"]
+  {
+    content: [{ type: "text", text: result.to_s }]
+  }
+end
+
+# Start the server (listens on stdin, responds on stdout)
+server.start
+```
+
+**SSE Server (HTTP with Server-Sent Events)**
+```ruby
+require 'mcp-sdk.rb'
+
+# Create SSE server (HTTP server with SSE support)
+server = MCP::Server.new(
+  name: "Demo",
+  version: "1.0.0",
+  type: "sse",
+  port: 8080
+)
+
+# Add tools as needed
+server.add_tool("add") do |params|
+  result = params["a"] + params["b"]
+  {
+    content: [{ type: "text", text: result.to_s }]
+  }
+end
+
+server.add_tool("multiply") do |params|
+  result = params["x"] * params["y"]
+  {
+    content: [{ type: "text", text: result.to_s }]
+  }
+end
+
+server.add_tool("greet") do |params|
+  name = params["name"] || "World"
+  {
+    content: [{ type: "text", text: "Hello, #{name}!" }]
+  }
+end
+
+# Start the HTTP server
+server.start
+```
+
+**Enhanced SSE Server (Advanced Features)**
+```ruby
+require 'mcp-sdk.rb'
+
+# Create Enhanced SSE server with advanced features
+server = MCP::Server.new(
+  name: "Enhanced Demo",
+  version: "1.0.0",
+  type: "enhanced_sse",
+  port: 8080
+)
+
+# Add tools as needed
+server.add_tool("calculate") do |params|
+  operation = params["operation"] || "add"
+  a = params["a"] || 0
+  b = params["b"] || 0
+  
+  result = case operation
+  when "add" then a + b
+  when "multiply" then a * b
+  when "subtract" then a - b
+  when "divide" then b != 0 ? a / b : "Error: Division by zero"
+  else "Unknown operation"
+  end
+  
+  {
+    content: [{ type: "text", text: "#{a} #{operation} #{b} = #{result}" }]
+  }
+end
+
+# Start the Enhanced SSE server
+server.start
+```
+
+#### Server Types
+
+**Stdio Server (`type: "stdio"`)**
+- Default server type
+- Communicates via stdin/stdout using JSON-RPC 2.0
+- Perfect for command-line tools and process-based communication
+- No additional configuration required
+
+**SSE Server (`type: "sse"`)**
+- HTTP server with Server-Sent Events support
+- Requires `port` parameter
+- Provides REST endpoints and real-time SSE communication
+- Includes CORS support for web applications
+
+**Enhanced SSE Server (`type: "enhanced_sse"`)**
+- Advanced HTTP server with enhanced SSE capabilities
+- Requires `port` parameter
+- Provides all standard SSE features plus:
+  - Connection management and tracking
+  - Broadcasting to multiple clients
+  - WebSocket-like bidirectional communication simulation
+  - Enhanced health monitoring
+  - Connection status endpoints
+- Includes CORS support for web applications
+- Built with Sinatra for better performance and extensibility
+
+#### SSE Server Protocol
+
+The MCP SSE server follows a specific two-step protocol flow:
+
+**Step 1: Get Message Endpoint**
+```bash
+curl http://localhost:8080/sse
+```
+This returns the endpoint information in SSE format:
+```
+event: endpoint
+data: /mcp/message
+```
+
+**Step 2: Send JSON-RPC to Message Endpoint**
+```bash
+curl -X POST http://localhost:8080/mcp/message \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+This returns the JSON-RPC response in SSE format:
+```
+data: {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}
+```
+
+**Additional Endpoints:**
+- `GET /health` - Server health check (convenience)
+
+#### Enhanced SSE Server Protocol
+
+The Enhanced SSE server provides all standard SSE endpoints plus advanced features:
+
+**Standard Endpoints:**
+- `GET /sse` - Get message endpoint (MCP protocol compliance)
+- `POST /mcp/message` - Send JSON-RPC requests and receive SSE responses
+- `GET /health` - Enhanced health check with detailed server information
+
+**Advanced Endpoints:**
+- `GET /sse/events` - Advanced SSE endpoint with connection management
+- `POST /mcp/broadcast` - Broadcast messages to all connected SSE clients
+- `GET /ws/connect` - WebSocket-like connection simulation (long polling)
+- `POST /ws/send/:connection_id` - Send messages to specific connections
+- `GET /connections` - View active connection status
+
+**Enhanced SSE Events Example:**
+```bash
+# Connect to advanced SSE endpoint
+curl -N http://localhost:8080/sse/events
+# Returns connection ID and keeps connection alive with heartbeats
+
+# Broadcast to all connected clients
+curl -X POST http://localhost:8080/mcp/broadcast \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+
+# Check connection status
+curl http://localhost:8080/connections
+```
+
+#### Server API
+
+- `MCP::Server.new(name:, version:, type:, port:)` - Create a new server instance
+  - `name`: Server name (required)
+  - `version`: Server version (required)  
+  - `type`: Server type - `"stdio"` (default), `"sse"`, or `"enhanced_sse"` (optional)
+  - `port`: Port number (required for SSE servers, ignored for stdio)
+- `server.add_tool(name, &block)` - Register a tool with a block that receives parameters
+- `server.start` - Start the server and listen for requests
+- `server.stop` - Stop the server
+- `server.list_tools` - Get list of registered tools
+- `server.call_tool(name, arguments)` - Call a tool directly
+
+The server implements the MCP protocol over JSON-RPC 2.0, supporting:
+- `tools/list` - List available tools
+- `tools/call` - Execute a specific tool
+
+#### Examples
+
+**Test MCP SSE Protocol with curl:**
+```bash
+# Step 1: Get the message endpoint
+curl http://localhost:8080/sse
+# Returns: event: endpoint\ndata: /mcp/message
+
+# Step 2: Send JSON-RPC requests to the message endpoint
+curl -X POST http://localhost:8080/mcp/message \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+
+curl -X POST http://localhost:8080/mcp/message \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add","arguments":{"a":5,"b":3}}}'
+
+# Health check (convenience)
+curl http://localhost:8080/health
+```
+
+**Test Stdio Server:**
+```bash
+# Send JSON-RPC to stdin
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ruby your_server.rb
+```
+
+#### Tool Response Format
+
+Tools should return responses in MCP format:
+
+```ruby
+{
+  content: [
+    { type: "text", text: "your response text" }
+  ]
+}
+```
+
+For simple text responses, you can return any value and it will be automatically wrapped in the proper format.
+
+## Example Files
+
+This repository includes several example files to help you get started:
+
+- `example_enhanced_sse.rb` - Complete Enhanced SSE server example with multiple tools
+- `enhanced_sse_client.html` - HTML client demo for testing SSE connections
+- `test_enhanced_sse.rb` - Integration test suite for Enhanced SSE functionality
+- `demo_both_servers.rb` - Demonstration of both stdio and SSE servers
+- `example_usage.rb` - Basic usage examples
+
+### Running Examples
+
+**Start Enhanced SSE Server:**
+```bash
+ruby example_enhanced_sse.rb
+```
+Then open `enhanced_sse_client.html` in your browser to test the connection.
+
+**Run Integration Tests:**
+```bash
+ruby test_enhanced_sse.rb
+```
+
+**Test Basic SSE Protocol:**
+```bash
+# Terminal 1: Start server
+ruby example_enhanced_sse.rb
+
+# Terminal 2: Test endpoints
+curl http://localhost:8081/health
+curl http://localhost:8081/sse
+curl -X POST http://localhost:8081/mcp/message \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/zhuangbiaowei/mcp-sdk.rb.

data/lib/mcp/angelo_sse_server.rb

@@ -0,0 +1,200 @@
+require "json"
+require "angelo"
+
+module MCP
+  # Angelo-based SSE server implementation for MCP
+  class AngeloSSEServer < Angelo::Base
+    attr_reader :mcp_server_instance
+    
+    def initialize(mcp_server_instance)
+      @mcp_server_instance = mcp_server_instance
+      super()
+    end
+    
+    # Configure server settings
+    def self.configure_for_mcp(port)
+      port port
+      addr "0.0.0.0"
+    end
+    
+    # Enable CORS for all routes
+    before do
+      headers 'Access-Control-Allow-Origin' => '*',
+              'Access-Control-Allow-Methods' => 'GET, POST, OPTIONS',
+              'Access-Control-Allow-Headers' => 'Content-Type'
+    end
+    
+    # Handle OPTIONS requests for CORS
+    options '*' do
+      halt 200
+    end
+    
+    # SSE endpoint - returns the message endpoint for subsequent requests
+    # This follows the MCP SSE protocol specification
+    get '/sse' do
+      content_type 'text/event-stream'
+      headers 'Cache-Control' => 'no-cache',
+              'Connection' => 'keep-alive'
+      
+      # Send endpoint event as per MCP SSE protocol
+      response = "event: endpoint\n"
+      response += "data: /mcp/message\n\n"
+      response
+    end
+    
+    # MCP message endpoint - handles POST requests and returns SSE responses
+    post '/mcp/message' do
+      content_type 'text/event-stream'
+      headers 'Cache-Control' => 'no-cache',
+              'Connection' => 'keep-alive'
+      
+      begin
+        request_data = JSON.parse(request.body.read)
+        response = @mcp_server_instance.send(:handle_request, request_data)
+        
+        # Return JSON-RPC response in SSE format
+        sse_response = "data: #{response.to_json}\n\n"
+        sse_response
+      rescue JSON::ParserError => e
+        error_response = {
+          jsonrpc: "2.0",
+          id: nil,
+          error: {
+            code: -32700,
+            message: "Parse error: #{e.message}"
+          }
+        }
+        "data: #{error_response.to_json}\n\n"
+      rescue => e
+        error_response = {
+          jsonrpc: "2.0", 
+          id: nil,
+          error: {
+            code: -32603,
+            message: "Internal error: #{e.message}"
+          }
+        }
+        "data: #{error_response.to_json}\n\n"
+      end
+    end
+    
+    # Alternative SSE endpoint using Angelo's eventsource functionality
+    # This provides more advanced SSE features
+    eventsource '/sse/events' do |sse|
+      # Add the connection to the SSE stash for broadcasting
+      sses << sse
+      
+      # Send initial endpoint event
+      sse.event :endpoint, '/mcp/message'
+      
+      # Keep connection alive
+      sse.on_close do
+        puts "SSE client disconnected"
+      end
+    end
+    
+    # POST endpoint for broadcasting events to all SSE connections
+    post '/mcp/broadcast' do
+      content_type 'application/json'
+      
+      begin
+        request_data = JSON.parse(request.body.read)
+        response = @mcp_server_instance.send(:handle_request, request_data)
+        
+        # Broadcast to all connected SSE clients
+        sses.each do |sse|
+          sse.message response.to_json
+        end
+        
+        { status: 'broadcasted', clients: sses.count }.to_json
+      rescue JSON::ParserError => e
+        error_response = {
+          jsonrpc: "2.0",
+          id: nil,
+          error: {
+            code: -32700,
+            message: "Parse error: #{e.message}"
+          }
+        }
+        
+        sses.each do |sse|
+          sse.message error_response.to_json
+        end
+        
+        { status: 'error', message: e.message }.to_json
+      rescue => e
+        error_response = {
+          jsonrpc: "2.0", 
+          id: nil,
+          error: {
+            code: -32603,
+            message: "Internal error: #{e.message}"
+          }
+        }
+        
+        sses.each do |sse|
+          sse.message error_response.to_json
+        end
+        
+        { status: 'error', message: e.message }.to_json
+      end
+    end
+    
+    # Health check endpoint
+    get '/health' do
+      content_type 'application/json'
+      {
+        status: 'ok',
+        server: @mcp_server_instance.name,
+        version: @mcp_server_instance.version,
+        type: 'angelo_sse',
+        tools_count: @mcp_server_instance.tools.size,
+        protocol: 'MCP SSE (Angelo)',
+        endpoints: {
+          sse: '/sse',
+          sse_events: '/sse/events',
+          message: '/mcp/message',
+          broadcast: '/mcp/broadcast'
+        },
+        connected_clients: sses.count
+      }.to_json
+    end
+    
+    # WebSocket endpoint for real-time bidirectional communication
+    websocket '/ws' do |ws|
+      websockets << ws
+      
+      ws.on_message do |msg|
+        begin
+          request_data = JSON.parse(msg)
+          response = @mcp_server_instance.send(:handle_request, request_data)
+          ws.write response.to_json
+        rescue JSON::ParserError => e
+          error_response = {
+            jsonrpc: "2.0",
+            id: nil,
+            error: {
+              code: -32700,
+              message: "Parse error: #{e.message}"
+            }
+          }
+          ws.write error_response.to_json
+        rescue => e
+          error_response = {
+            jsonrpc: "2.0", 
+            id: nil,
+            error: {
+              code: -32603,
+              message: "Internal error: #{e.message}"
+            }
+          }
+          ws.write error_response.to_json
+        end
+      end
+      
+      ws.on_close do
+        puts "WebSocket client disconnected"
+      end
+    end
+  end
+end