mcp-sdk.rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11e337fa046c8b12a083f96718f78b050af34cbfdcd3df7599c6240625123039
+  data.tar.gz: 492711d7e4b5796548f669d593eff579dc906ea3eeabdf29839c25187e2d0b32
+SHA512:
+  metadata.gz: 9f51739d8bf36abc3f9fcf356d7fc679f434590eb90c7abb2aa1a955d5a9e99b1c802beb5bc09bbb3c31e0078fa547a420042e3b3f34c0491e3d38a6fe49178f
+  data.tar.gz: cd9a155aa772476ffaa2c7cf3aa8ae509dd824292483e5133168df86bbdf5ef7522e88c8bd38e7df9b711d71c48e881d0cb031a1db55cd0eab10e7fa651d44d1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+# MCP SDK for Ruby
+
+[![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.
+
+## Features
+
+- Supports both SSE (Server-Sent Events) and Stdio-based MCP servers
+- Type-safe client interfaces
+- Easy integration with Ruby applications
+- Comprehensive error handling
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mcp-sdk.rb'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install mcp-sdk.rb
+```
+
+## Usage
+
+### Connecting to an SSE-based MCP server
+
+```ruby
+require 'mcp-sdk.rb'
+client = MCP::SSEClient.new('http://example.com/sse?key=api_key')
+client.start
+mcp_server_json = client.list_tools
+puts JSON.pretty_generate(convertFormat(mcp_server_json))
+```
+
+### Connecting to a Stdio-based MCP server
+
+```ruby
+require 'mcp-sdk.rb'
+
+client = MCP::StdioClient.new('nodejs path/to/server_executable.js')
+client.start
+mcp_server_json = client.list_tools
+puts JSON.pretty_generate(convertFormat(mcp_server_json))
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/zhuangbiaowei/mcp-sdk.rb.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/mcp/client.rb

@@ -0,0 +1,108 @@
+require "json"
+require "childprocess"
+require "timeout"
+
+module MCP
+  class Error < StandardError; end
+
+  class Client
+    def initialize(server_cmd)
+      cmd, server_path = server_cmd.split(" ")
+      @server = ChildProcess.build(cmd, server_path)
+      @stdout, @stdout_writer = IO.pipe
+      @stderr, @stderr_writer = IO.pipe
+      @server.io.stdout = @stdout_writer
+      @server.io.stderr = @stderr_writer
+      @server.duplex = true
+      @request_id = 0
+      @pending_requests = {}
+      @response_queue = Queue.new
+      @running = false
+    end
+
+    def start
+      @server.start
+      sleep 0.5 # Wait for server startup
+      @running = true
+      setup_io_handlers
+    end
+
+    def stop
+      @running = false
+      @stdout_writer.close
+      @stderr_writer.close
+      @reader.join if @reader
+      @server.stop
+      @stdout.close
+      @stderr.close
+    end
+
+    def list_tools()
+      request_id = next_id
+      request = ListToolsRequest.new(request_id: request_id).to_json
+      write_request(request)
+      read_response(request_id)
+    end
+
+    def call_method(params)
+      request_id = next_id
+      request = CallMethodRequest.new(
+        request_id: request_id,
+        params: params,
+      ).to_json
+      write_request(request)
+      read_response(request_id)
+    end
+
+    private
+
+    def next_id
+      @request_id += 1
+    end
+
+    def write_request(request)
+      @server.io.stdin.puts request
+    end
+
+    def setup_io_handlers
+      @reader = Thread.new do
+        while @running
+          begin
+            if line = @stdout.gets
+              handle_response(line)
+            end
+          rescue IOError => e
+            break unless @running
+            raise e
+          end
+        end
+      end
+    end
+
+    def handle_response(line)
+      response = JSON.parse(line)
+      @pending_requests[response["id"]] = response
+    rescue JSON::ParserError
+      raise Error, "Invalid JSON response: #{line}"
+    end
+
+    def read_response(request_id, timeout = 10)
+      Timeout.timeout(timeout) do
+        while !@pending_requests.key?(request_id)
+          sleep 0.1
+        end
+        response = @pending_requests.delete(request_id)
+        process_response(response)
+      end
+    rescue Timeout::Error
+      raise Error, "Timeout waiting for response"
+    end
+
+    def process_response(response)
+      if response["error"]
+        raise Error.new(response["error"]["message"])
+      end
+      response["result"]
+    end
+  end
+end

data/lib/mcp/convert.rb

@@ -0,0 +1,29 @@
+def convertFormat(mcp_server_json)
+  toolCalling_json = {}
+  toolCalling_json["tools"] ||= []
+  mcp_server_json["tools"].each do |tool|
+    function = {}
+    function["name"] = tool["name"]
+    function["description"] = tool["description"]
+    function["parameters"] = {}
+    function["parameters"]["type"] = "object"
+    function["parameters"]["required"] = tool["inputSchema"]["required"] || []
+    tool["inputSchema"]["properties"].each do |prop_name, prop_def|
+      param_def = {
+        type: prop_def["type"],
+        description: prop_def["description"],
+      }
+
+      if prop_def["enum"]
+        param_def["enum"] = prop_def["enum"]
+      end
+      function["parameters"]["properties"] ||= {}
+      function["parameters"]["properties"][prop_name] = param_def
+    end
+    toolCalling_json["tools"] << {
+      "type": "function",
+      "function": function,
+    }
+  end
+  toolCalling_json
+end

data/lib/mcp/sse_client.rb

@@ -0,0 +1,90 @@
+require "faraday"
+require "uri"
+require "json"
+
+module MCP
+  class SSEClient < StdioClient
+    def initialize(url, opt = {})
+      @request_id = 0
+      @pending_requests = {}
+      @response_queue = Queue.new
+      @running = false
+      @endpoint = nil
+      @temp_chunk = nil
+      uri = URI(url)
+      @conn = Faraday.new(url: uri.origin) do |f|
+        f.adapter :net_http
+        f.options.timeout = 30           # read timeout
+        f.options.open_timeout = 10      # connection timeout
+      end
+      @thread = Thread.new do
+        loop do
+          begin
+            @conn.get do |req|
+              req.url uri.request_uri
+              req.headers["Accept"] = "text/event-stream; charset=utf-8"
+              req.headers["Accept-Encoding"] = "identity"
+              req.headers["Content-Type"] = "application/json"
+
+              req.options.on_data = proc do |chunk, overall_received_bytes|
+                if @temp_chunk == nil
+                  @temp_chunk = chunk
+                else
+                  @temp_chunk += chunk
+                end
+                event_type = @temp_chunk.split("\n")[0].split(":")[1].strip
+                data = @temp_chunk.split("\n")[1][5..-1].strip
+                if event_type == "endpoint"
+                  @endpoint = data
+                  @temp_chunk = nil
+                else
+                  if verify_json(data) && event_type == "message"
+                    handle_response(data)
+                    @temp_chunk = nil
+                  end
+                end
+              end
+            end
+          rescue Faraday::Error => e
+            #puts "SSE connection error: #{e.message}"
+            sleep 1
+          rescue => e
+            #puts "Unexpected error in SSE thread: #{e.message}"
+            sleep 1
+          end
+        end
+      end
+    end
+
+    def verify_json(str)
+      JSON.parse(str)
+      true
+    rescue JSON::ParserError
+      false
+    end
+
+    def write_request(message)
+      while (@endpoint == nil)
+        sleep(0.2)
+      end
+      if @endpoint
+        @conn.post(@endpoint, message, { "content-type" => "application/json" })
+      end
+    end
+
+    def start
+      request_id = next_id
+      write_request({
+        jsonrpc: "2.0",
+        id: request_id,
+        method: "initialize",
+        params: {
+          protocolVersion: "2025-04-28",
+          clientInfo: { name: "mcp-ruby-client", version: "0.0.1" },
+        },
+      }.to_json)
+      read_response(request_id)
+      write_request({ jsonrpc: "2.0", method: "notifications/initialized" }.to_json)
+    end
+  end
+end

data/lib/mcp/stdio_client.rb

@@ -0,0 +1,112 @@
+require "json"
+require "childprocess"
+require "timeout"
+
+module MCP
+  class Error < StandardError; end
+
+  class StdioClient
+    def initialize(server_cmd)
+      cmds = server_cmd.split(" ")
+      @server = ChildProcess.build(*cmds)
+      @stdout, @stdout_writer = IO.pipe
+      @stderr, @stderr_writer = IO.pipe
+      @server.io.stdout = @stdout_writer
+      @server.io.stderr = @stderr_writer
+      @server.duplex = true
+      @request_id = 0
+      @pending_requests = {}
+      @response_queue = Queue.new
+      @running = false
+    end
+
+    def start
+      @server.start
+      sleep 0.5 # Wait for server startup
+      @running = true
+      setup_io_handlers
+    end
+
+    def stop
+      @running = false
+      @stdout_writer.close
+      @stderr_writer.close
+      @reader.join if @reader
+      @server.stop
+      @stdout.close
+      @stderr.close
+    end
+
+    def list_tools()
+      request_id = next_id
+      request = ListToolsRequest.new(request_id: request_id).to_json
+      write_request(request)
+      read_response(request_id)
+    end
+
+    def call_method(params)
+      request_id = next_id
+      request = CallMethodRequest.new(
+        request_id: request_id,
+        params: params,
+      ).to_json
+      write_request(request)
+      read_response(request_id)
+    end
+
+    private
+
+    def next_id
+      @request_id += 1
+    end
+
+    def write_request(request)
+      begin
+        @server.io.stdin.puts request
+      rescue Errno::EPIPE => e
+        raise Error, "Server connection broken: #{e.message}"
+      end
+    end
+
+    def setup_io_handlers
+      @reader = Thread.new do
+        while @running
+          begin
+            if line = @stdout.gets
+              handle_response(line)
+            end
+          rescue IOError => e
+            break unless @running
+            raise e
+          end
+        end
+      end
+    end
+
+    def handle_response(line)
+      response = JSON.parse(line)
+      @pending_requests[response["id"]] = response
+    rescue JSON::ParserError
+      raise Error, "Invalid JSON response: #{line}"
+    end
+
+    def read_response(request_id, timeout = 10)
+      Timeout.timeout(timeout) do
+        while !@pending_requests.key?(request_id)
+          sleep 0.1
+        end
+        response = @pending_requests.delete(request_id)
+        process_response(response)
+      end
+    rescue Timeout::Error
+      raise Error, "Timeout waiting for response"
+    end
+
+    def process_response(response)
+      if response["error"]
+        raise Error.new(response["error"]["message"])
+      end
+      response["result"]
+    end
+  end
+end

data/lib/mcp/types.rb

@@ -0,0 +1,37 @@
+module MCP
+  class Request
+    def initialize(jsonrpc: nil, request_id: nil, method: nil, params: {})
+      @jsonrpc = jsonrpc
+      @id = request_id
+      @method = method
+      @params = params
+    end
+
+    def to_json
+      {
+        "jsonrpc": @jsonrpc,
+        "id": @id,
+        "method": @method,
+        "params": @params,
+      }.to_json
+    end
+  end
+
+  class JSONRPCRequest < Request
+    def initialize(request_id: nil, method: nil, params: {})
+      super(jsonrpc: "2.0", request_id: request_id, method: method, params: params)
+    end
+  end
+
+  class ListToolsRequest < JSONRPCRequest
+    def initialize(request_id: 0)
+      super(request_id: request_id, method: "tools/list")
+    end
+  end
+
+  class CallMethodRequest < JSONRPCRequest
+    def initialize(request_id: 0, params:)
+      super(request_id: request_id, method: "tools/call", params: params)
+    end
+  end
+end

data/lib/mcp.rb

@@ -0,0 +1,9 @@
+require File.expand_path("../mcp/types", __FILE__)
+require File.expand_path("../mcp/client", __FILE__)
+require File.expand_path("../mcp/stdio_client", __FILE__)
+require File.expand_path("../mcp/sse_client", __FILE__)
+require File.expand_path("../mcp/convert", __FILE__)
+
+module MCP
+  LATEST_PROTOCOL_VERSION = "2024-11-05".freeze
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: mcp-sdk.rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zhuang Biaowei
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.7.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.7.1
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A Ruby SDK for the MCP (Multi-Channel Protocol) implementation
+email:
+- zbw@kaiyuanshe.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mcp.rb
+- lib/mcp/client.rb
+- lib/mcp/convert.rb
+- lib/mcp/sse_client.rb
+- lib/mcp/stdio_client.rb
+- lib/mcp/types.rb
+homepage: https://github.com/zhuangbiaowei/mcp-sdk.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: MCP SDK for Ruby
+test_files: []