mcp 0.1.0 → 0.3.0

data/examples/README.md

@@ -0,0 +1,197 @@
+# MCP Ruby Examples
+
+This directory contains examples of how to use the Model Context Protocol (MCP) Ruby library.
+
+## Available Examples
+
+### 1. STDIO Server (`stdio_server.rb`)
+
+A simple server that communicates over standard input/output. This is useful for desktop applications and command-line tools.
+
+**Usage:**
+
+```console
+$ ruby examples/stdio_server.rb
+{"jsonrpc":"2.0","id":0,"method":"tools/list"}
+```
+
+### 2. HTTP Server (`http_server.rb`)
+
+A standalone HTTP server built with Rack that implements the MCP Streamable HTTP transport protocol. This demonstrates how to create a web-based MCP server with session management and Server-Sent Events (SSE) support.
+
+**Features:**
+
+- HTTP transport with Server-Sent Events (SSE) for streaming
+- Session management with unique session IDs
+- Example tools, prompts, and resources
+- JSON-RPC 2.0 protocol implementation
+- Full MCP protocol compliance
+
+**Usage:**
+
+```console
+$ ruby examples/http_server.rb
+```
+
+The server will start on `http://localhost:9292` and provide:
+
+- **Tools**:
+  - `ExampleTool` - adds two numbers
+  - `echo` - echoes back messages
+- **Prompts**: `ExamplePrompt` - echoes back arguments as a prompt
+- **Resources**: `test_resource` - returns example content
+
+### 3. HTTP Client Example (`http_client.rb`)
+
+A client that demonstrates how to interact with the HTTP server using all MCP protocol methods.
+
+**Usage:**
+
+1. Start the HTTP server in one terminal:
+
+   ```console
+   $ ruby examples/http_server.rb
+   ```
+
+2. Run the client example in another terminal:
+   ```console
+   $ ruby examples/http_client.rb
+   ```
+
+The client will demonstrate:
+
+- Session initialization
+- Ping requests
+- Listing and calling tools
+- Listing and getting prompts
+- Listing and reading resources
+- Session cleanup
+
+### 4. Streamable HTTP Server (`streamable_http_server.rb`)
+
+A specialized HTTP server designed to test and demonstrate Server-Sent Events (SSE) functionality in the MCP protocol.
+
+**Features:**
+
+- Tools specifically designed to trigger SSE notifications
+- Real-time progress updates and notifications
+- Detailed SSE-specific logging
+
+**Available Tools:**
+
+- `NotificationTool` - Send custom SSE notifications with optional delays
+- `echo` - Simple echo tool for basic testing
+
+**Usage:**
+
+```console
+$ ruby examples/streamable_http_server.rb
+```
+
+The server will start on `http://localhost:9393` and provide detailed instructions for testing SSE functionality.
+
+### 5. Streamable HTTP Client (`streamable_http_client.rb`)
+
+An interactive client that connects to the SSE stream and provides a menu-driven interface for testing SSE functionality.
+
+**Features:**
+
+- Automatic SSE stream connection
+- Interactive menu for triggering various SSE events
+- Real-time display of received SSE notifications
+- Session management
+
+**Usage:**
+
+1. Start the SSE test server in one terminal:
+
+   ```console
+   $ ruby examples/streamable_http_server.rb
+   ```
+
+2. Run the SSE test client in another terminal:
+   ```console
+   $ ruby examples/streamable_http_client.rb
+   ```
+
+The client will:
+
+- Initialize a session automatically
+- Connect to the SSE stream
+- Provide an interactive menu to trigger notifications
+- Display all received SSE events in real-time
+
+### Testing SSE with cURL
+
+You can also test SSE functionality manually using cURL:
+
+1. Initialize a session:
+
+```console
+SESSION_ID=$(curl -D - -s -o /dev/null http://localhost:9393 \
+  --json '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl-test","version":"1.0"}}}' | grep -i "Mcp-Session-Id:" | cut -d' ' -f2- | tr -d '\r')
+```
+
+2. Connect to SSE stream (in one terminal):
+
+```console
+curl -i -N -H "Mcp-Session-Id: $SESSION_ID" http://localhost:9393
+```
+
+3. Trigger notifications (in another terminal):
+
+```console
+# Send immediate notification
+curl -i http://localhost:9393 \
+  -H "Mcp-Session-Id: $SESSION_ID" \
+  --json '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"notification_tool","arguments":{"message":"Hello from cURL!"}}}'
+```
+
+## Streamable HTTP Transport Details
+
+### Protocol Flow
+
+The HTTP server implements the MCP Streamable HTTP transport protocol:
+
+1. **Initialize Session**:
+
+   - Client sends POST request with `initialize` method
+   - Server responds with session ID in `Mcp-Session-Id` header
+
+2. **Establish SSE Connection** (optional):
+
+   - Client sends GET request with `Mcp-Session-Id` header
+   - Server establishes Server-Sent Events stream for notifications
+
+3. **Send Requests**:
+
+   - Client sends POST requests with JSON-RPC 2.0 format
+   - Server processes and responds with results
+
+4. **Close Session**:
+   - Client sends DELETE request with `Mcp-Session-Id` header
+
+### Example cURL Commands
+
+Initialize a session:
+
+```console
+curl -i http://localhost:9292 \
+  --json '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
+```
+
+List tools (using the session ID from initialization):
+
+```console
+curl -i http://localhost:9292 \
+  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
+  --json '{"jsonrpc":"2.0","method":"tools/list","id":2}'
+```
+
+Call a tool:
+
+```console
+curl -i http://localhost:9292 \
+  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
+  --json '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"ExampleTool","arguments":{"a":5,"b":3}}}'
+```

data/examples/http_client.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+# Simple HTTP client example for interacting with the MCP HTTP server
+class MCPHTTPClient
+  def initialize(base_url = "http://localhost:9292")
+    @base_url = base_url
+    @session_id = nil
+  end
+
+  def send_request(method, params = nil, id = nil)
+    uri = URI(@base_url)
+    http = Net::HTTP.new(uri.host, uri.port)
+
+    request = Net::HTTP::Post.new(uri.path.empty? ? "/" : uri.path)
+    request["Content-Type"] = "application/json"
+    request["Mcp-Session-Id"] = @session_id if @session_id
+
+    body = {
+      jsonrpc: "2.0",
+      method: method,
+      params: params,
+      id: id || rand(10000),
+    }.compact
+
+    request.body = body.to_json
+
+    response = http.request(request)
+
+    # Store session ID if provided
+    if response["Mcp-Session-Id"]
+      @session_id = response["Mcp-Session-Id"]
+      puts "Session ID: #{@session_id}"
+    end
+
+    JSON.parse(response.body)
+  end
+
+  def initialize_session
+    puts "=== Initializing session ==="
+    result = send_request("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: {
+        name: "example_client",
+        version: "1.0",
+      },
+    })
+    puts "Response: #{JSON.pretty_generate(result)}"
+
+    result
+  end
+
+  def ping
+    puts "=== Sending ping ==="
+    result = send_request("ping")
+    puts "Response: #{JSON.pretty_generate(result)}"
+
+    result
+  end
+
+  def list_tools
+    puts "=== Listing tools ==="
+    result = send_request("tools/list")
+    puts "Response: #{JSON.pretty_generate(result)}"
+
+    result
+  end
+
+  def call_tool(name, arguments)
+    puts "=== Calling tool: #{name} ==="
+    result = send_request("tools/call", {
+      name: name,
+      arguments: arguments,
+    })
+    puts "Response: #{JSON.pretty_generate(result)}"
+
+    result
+  end
+
+  def list_prompts
+    puts "=== Listing prompts ==="
+    result = send_request("prompts/list")
+    puts "Response: #{JSON.pretty_generate(result)}"
+
+    result
+  end
+
+  def get_prompt(name, arguments)
+    puts "=== Getting prompt: #{name} ==="
+    result = send_request("prompts/get", {
+      name: name,
+      arguments: arguments,
+    })
+    puts "Response: #{JSON.pretty_generate(result)}"
+
+    result
+  end
+
+  def list_resources
+    puts "=== Listing resources ==="
+    result = send_request("resources/list")
+    puts "Response: #{JSON.pretty_generate(result)}"
+
+    result
+  end
+
+  def read_resource(uri)
+    puts "=== Reading resource: #{uri} ==="
+    result = send_request("resources/read", {
+      uri: uri,
+    })
+    puts "Response: #{JSON.pretty_generate(result)}"
+
+    result
+  end
+
+  def close_session
+    return unless @session_id
+
+    puts "=== Closing session ==="
+    uri = URI(@base_url)
+    http = Net::HTTP.new(uri.host, uri.port)
+
+    request = Net::HTTP::Delete.new(uri.path.empty? ? "/" : uri.path)
+    request["Mcp-Session-Id"] = @session_id
+
+    response = http.request(request)
+    result = JSON.parse(response.body)
+    puts "Response: #{JSON.pretty_generate(result)}"
+
+    @session_id = nil
+    result
+  end
+end
+
+# Main script
+if __FILE__ == $PROGRAM_NAME
+  puts <<~MESSAGE
+    MCP HTTP Client Example
+    Make sure the HTTP server is running (ruby examples/http_server.rb)
+    #{"=" * 50}
+  MESSAGE
+
+  client = MCPHTTPClient.new
+
+  begin
+    # Initialize session
+    client.initialize_session
+
+    # Test ping
+    client.ping
+
+    # List available tools
+    client.list_tools
+
+    # Call the example_tool (note: snake_case name)
+    client.call_tool("example_tool", { a: 5, b: 3 })
+
+    # Call the echo tool
+    client.call_tool("echo", { message: "Hello from client!" })
+
+    # List prompts
+    client.list_prompts
+
+    # Get a prompt (note: snake_case name)
+    client.get_prompt("example_prompt", { message: "This is a test message" })
+
+    # List resources
+    client.list_resources
+
+    # Read a resource
+    client.read_resource("test_resource")
+  rescue => e
+    puts "Error: #{e.message}"
+    puts e.backtrace
+  ensure
+    # Clean up session
+    client.close_session
+  end
+end

data/examples/http_server.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "mcp"
+require "mcp/server/transports/streamable_http_transport"
+require "rack"
+require "rackup"
+require "json"
+require "logger"
+
+# Create a simple tool
+class ExampleTool < MCP::Tool
+  description "A simple example tool that adds two numbers"
+  input_schema(
+    properties: {
+      a: { type: "number" },
+      b: { type: "number" },
+    },
+    required: ["a", "b"],
+  )
+
+  class << self
+    def call(a:, b:)
+      MCP::Tool::Response.new([{
+        type: "text",
+        text: "The sum of #{a} and #{b} is #{a + b}",
+      }])
+    end
+  end
+end
+
+# Create a simple prompt
+class ExamplePrompt < MCP::Prompt
+  description "A simple example prompt that echoes back its arguments"
+  arguments [
+    MCP::Prompt::Argument.new(
+      name: "message",
+      description: "The message to echo back",
+      required: true,
+    ),
+  ]
+
+  class << self
+    def template(args, server_context:)
+      MCP::Prompt::Result.new(
+        messages: [
+          MCP::Prompt::Message.new(
+            role: "user",
+            content: MCP::Content::Text.new(args[:message]),
+          ),
+        ],
+      )
+    end
+  end
+end
+
+# Set up the server
+server = MCP::Server.new(
+  name: "example_http_server",
+  tools: [ExampleTool],
+  prompts: [ExamplePrompt],
+  resources: [
+    MCP::Resource.new(
+      uri: "https://test_resource.invalid",
+      name: "test-resource",
+      title: "Test Resource",
+      description: "Test resource that echoes back the uri as its content",
+      mime_type: "text/plain",
+    ),
+  ],
+)
+
+server.define_tool(
+  name: "echo",
+  description: "A simple example tool that echoes back its arguments",
+  input_schema: { properties: { message: { type: "string" } }, required: ["message"] },
+) do |message:|
+  MCP::Tool::Response.new(
+    [
+      {
+        type: "text",
+        text: "Hello from echo tool! Message: #{message}",
+      },
+    ],
+  )
+end
+
+server.resources_read_handler do |params|
+  [{
+    uri: params[:uri],
+    mimeType: "text/plain",
+    text: "Hello from HTTP server resource!",
+  }]
+end
+
+# Create the Streamable HTTP transport
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+server.transport = transport
+
+# Create a logger for MCP-specific logging
+mcp_logger = Logger.new($stdout)
+mcp_logger.formatter = proc do |_severity, _datetime, _progname, msg|
+  "[MCP] #{msg}\n"
+end
+
+# Create a Rack application with logging
+app = proc do |env|
+  request = Rack::Request.new(env)
+
+  # Log MCP-specific details for POST requests
+  if request.post?
+    body = request.body.read
+    request.body.rewind
+    begin
+      parsed_body = JSON.parse(body)
+      mcp_logger.info("Request: #{parsed_body["method"]} (id: #{parsed_body["id"]})")
+      mcp_logger.debug("Request body: #{JSON.pretty_generate(parsed_body)}")
+    rescue JSON::ParserError
+      mcp_logger.warn("Request body (raw): #{body}")
+    end
+  end
+
+  # Handle the request
+  response = transport.handle_request(request)
+
+  # Log the MCP response details
+  _, _, body = response
+  if body.is_a?(Array) && !body.empty? && body.first
+    begin
+      parsed_response = JSON.parse(body.first)
+      if parsed_response["error"]
+        mcp_logger.error("Response error: #{parsed_response["error"]["message"]}")
+      else
+        mcp_logger.info("Response: #{parsed_response["result"] ? "success" : "empty"} (id: #{parsed_response["id"]})")
+      end
+      mcp_logger.debug("Response body: #{JSON.pretty_generate(parsed_response)}")
+    rescue JSON::ParserError
+      mcp_logger.warn("Response body (raw): #{body}")
+    end
+  end
+
+  response
+end
+
+# Wrap the app with Rack middleware
+rack_app = Rack::Builder.new do
+  # Use CommonLogger for standard HTTP request logging
+  use(Rack::CommonLogger, Logger.new($stdout))
+
+  # Add other useful middleware
+  use(Rack::ShowExceptions)
+
+  run(app)
+end
+
+# Start the server
+puts <<~MESSAGE
+  Starting MCP HTTP server on http://localhost:9292
+  Use POST requests to initialize and send JSON-RPC commands
+  Example initialization:
+    curl -i http://localhost:9292 --json '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
+
+  The server will return a session ID in the Mcp-Session-Id header.
+  Use this session ID for subsequent requests.
+
+  Press Ctrl+C to stop the server
+MESSAGE
+
+# Run the server
+# Use Rackup to run the server
+Rackup::Handler.get("puma").run(rack_app, Port: 9292, Host: "localhost")

data/examples/stdio_server.rb

@@ -1,9 +1,8 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "mcp"
-require "mcp/transports/stdio"
+require "mcp/server/transports/stdio_transport"
 
 # Create a simple tool
 class ExampleTool < MCP::Tool
@@ -59,8 +58,9 @@ server = MCP::Server.new(
   prompts: [ExamplePrompt],
   resources: [
     MCP::Resource.new(
-      uri: "test_resource",
-      name: "Test resource",
+      uri: "https://test_resource.invalid",
+      name: "test-resource",
+      title: "Test Resource",
       description: "Test resource that echoes back the uri as its content",
       mime_type: "text/plain",
     ),
@@ -86,10 +86,10 @@ server.resources_read_handler do |params|
   [{
     uri: params[:uri],
     mimeType: "text/plain",
-    text: "Hello, world!",
+    text: "Hello, world! URI: #{params[:uri]}",
   }]
 end
 
 # Create and start the transport
-transport = MCP::Transports::StdioTransport.new(server)
+transport = MCP::Server::Transports::StdioTransport.new(server)
 transport.open