add stdio transport

Author: topherbullock

examples/stdio_client.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "mcp"
+require "mcp/client/transports/stdio"
+
+# Create a client with stdio transport
+transport = MCP::Client::Transports::Stdio.new(timeout: 10)
+client = MCP::Client.new(transport: transport)
+
+begin
+  # Initialize the session
+  result = client.initialize_session(
+    protocol_version: "2025-03-26",
+    capabilities: {},
+    client_info: {
+      name: "example_stdio_client",
+      version: "1.0.0",
+    },
+  )
+
+  puts "Connected to server: #{result[:serverInfo][:name]} v#{result[:serverInfo][:version]}"
+  puts "Server capabilities: #{result[:capabilities].keys.join(", ")}"
+
+  # Test ping
+  ping_result = client.ping
+  puts "Ping successful: #{ping_result}"
+
+  # List available tools
+  tools_result = client.list_tools
+  puts "Available tools:"
+  tools_result[:tools].each do |tool|
+    puts "  - #{tool[:name]}: #{tool[:description]}"
+  end
+
+  # Call a tool if available
+  if tools_result[:tools].any?
+    tool_name = tools_result[:tools].first[:name]
+    puts "\nCalling tool: #{tool_name}"
+
+    # Example arguments - adjust based on the actual tool
+    tool_result = client.call_tool(
+      name: tool_name,
+      arguments: tool_name == "echo" ? { message: "Hello from stdio client!" } : {},
+    )
+
+    puts "Tool result:"
+    tool_result[:content].each do |content|
+      puts "  #{content[:text]}" if content[:type] == "text"
+    end
+  end
+rescue MCP::Client::ClientError => e
+  puts "Client error: #{e.message}"
+  puts "Error type: #{e.error_type}"
+rescue MCP::Client::Transports::Stdio::StdioError => e
+  puts "Stdio transport error: #{e.message}"
+  puts "Original error: #{e.original_error}" if e.original_error
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+  puts e.backtrace.join("\n")
+end

lib/mcp/client/transports/stdio.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require "stringio"
+
+module MCP
+  class Client
+    module Transports
+      class Stdio
+        class StdioError < StandardError
+          attr_reader :original_error
+
+          def initialize(message, original_error: nil)
+            super(message)
+            @original_error = original_error
+          end
+        end
+
+        attr_reader :timeout
+
+        def initialize(timeout: 30)
+          @timeout = timeout
+          @stdin = $stdin
+          @stdout = $stdout
+          @stdin.set_encoding("UTF-8")
+          @stdout.set_encoding("UTF-8")
+        end
+
+        def send_request(request)
+          json_request = JSON.generate(request)
+
+          begin
+            # Send request to stdout
+            @stdout.puts(json_request)
+            @stdout.flush
+
+            # Read response from stdin with timeout
+            response_line = read_with_timeout(@timeout)
+
+            unless response_line
+              raise StdioError.new("No response received within #{@timeout} seconds")
+            end
+
+            # Parse the JSON response
+            JSON.parse(response_line.strip, symbolize_names: true)
+          rescue JSON::ParserError => e
+            raise StdioError.new("Invalid JSON response: #{e.message}", original_error: e)
+          rescue Errno::EPIPE => e
+            raise StdioError.new("Broken pipe: #{e.message}", original_error: e)
+          rescue IOError => e
+            raise StdioError.new("IO error: #{e.message}", original_error: e)
+          rescue StandardError => e
+            raise StdioError.new("Stdio transport error: #{e.message}", original_error: e)
+          end
+        end
+
+        private
+
+        def read_with_timeout(timeout)
+          # Handle StringIO for testing
+          if @stdin.is_a?(StringIO)
+            @stdin.gets
+          elsif IO.select([@stdin], nil, nil, timeout)
+            @stdin.gets
+          else
+            nil
+          end
+        end
+      end
+    end
+  end
+end

test/mcp/client/transports/stdio_test.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "mcp/client/transports/stdio"
+require "json"
+
+module MCP
+  class Client
+    module Transports
+      class StdioTest < ActiveSupport::TestCase
+        setup do
+          @transport = Stdio.new(timeout: 1)
+        end
+
+        test "initializes with default timeout" do
+          transport = Stdio.new
+          assert_equal 30, transport.timeout
+        end
+
+        test "initializes with custom timeout" do
+          transport = Stdio.new(timeout: 10)
+          assert_equal 10, transport.timeout
+        end
+
+        test "sends request and receives response successfully" do
+          request = {
+            jsonrpc: "2.0",
+            method: "ping",
+            id: 1,
+          }
+
+          response = {
+            jsonrpc: "2.0",
+            id: 1,
+            result: {},
+          }
+
+          # Mock stdin and stdout
+          mock_stdin = StringIO.new(JSON.generate(response) + "\n")
+          mock_stdout = StringIO.new
+
+          @transport.instance_variable_set(:@stdin, mock_stdin)
+          @transport.instance_variable_set(:@stdout, mock_stdout)
+
+          result = @transport.send_request(request)
+
+          # Verify request was sent to stdout
+          assert_equal JSON.generate(request) + "\n", mock_stdout.string
+
+          # Verify response was parsed correctly
+          assert_equal response, result
+        end
+
+        test "raises error on timeout" do
+          request = { jsonrpc: "2.0", method: "ping", id: 1 }
+
+          # Mock stdin that never returns data
+          mock_stdin = StringIO.new("")
+          mock_stdout = StringIO.new
+
+          @transport.instance_variable_set(:@stdin, mock_stdin)
+          @transport.instance_variable_set(:@stdout, mock_stdout)
+
+          error = assert_raises(Stdio::StdioError) do
+            @transport.send_request(request)
+          end
+          assert_match(/No response received within 1 seconds/, error.message)
+        end
+
+        test "raises error on invalid JSON response" do
+          request = { jsonrpc: "2.0", method: "ping", id: 1 }
+
+          # Mock stdin with invalid JSON
+          mock_stdin = StringIO.new("invalid json\n")
+          mock_stdout = StringIO.new
+
+          @transport.instance_variable_set(:@stdin, mock_stdin)
+          @transport.instance_variable_set(:@stdout, mock_stdout)
+
+          error = assert_raises(Stdio::StdioError) do
+            @transport.send_request(request)
+          end
+          assert_match(/Invalid JSON response/, error.message)
+          assert_instance_of JSON::ParserError, error.original_error
+        end
+
+        test "raises error on broken pipe" do
+          request = { jsonrpc: "2.0", method: "ping", id: 1 }
+
+          mock_stdout = StringIO.new
+          @transport.instance_variable_set(:@stdout, mock_stdout)
+
+          # Mock puts to raise EPIPE
+          mock_stdout.define_singleton_method(:puts) do |*args|
+            raise Errno::EPIPE.new("Broken pipe")
+          end
+
+          error = assert_raises(Stdio::StdioError) do
+            @transport.send_request(request)
+          end
+          assert_match(/Broken pipe/, error.message)
+          assert_instance_of Errno::EPIPE, error.original_error
+        end
+
+        test "raises error on IO error" do
+          request = { jsonrpc: "2.0", method: "ping", id: 1 }
+
+          mock_stdout = StringIO.new
+          @transport.instance_variable_set(:@stdout, mock_stdout)
+
+          # Mock puts to raise IOError
+          mock_stdout.define_singleton_method(:puts) do |*args|
+            raise IOError.new("IO error")
+          end
+
+          error = assert_raises(Stdio::StdioError) do
+            @transport.send_request(request)
+          end
+          assert_match(/IO error/, error.message)
+          assert_instance_of IOError, error.original_error
+        end
+      end
+    end
+  end
+end