mcp 0.7.1 → 0.9.0

data/examples/README.md

@@ -1,197 +0,0 @@
-# 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

@@ -1,184 +0,0 @@
-# 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

@@ -1,169 +0,0 @@
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "mcp"
-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,94 +0,0 @@
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "mcp"
-
-# 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_server",
-  version: "1.0.0",
-  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, world! URI: #{params[:uri]}",
-  }]
-end
-
-# Create and start the transport
-transport = MCP::Server::Transports::StdioTransport.new(server)
-transport.open