ruby_mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 21d2e8bc121fd3b1156a684506219d5de9e7a8abe9f01c5ac0b40fa5638e5702
+  data.tar.gz: 205f2f1f5e46b7c1bb10530682d458fb1b62bf3315e8dae4705cc0e6c27958f8
+SHA512:
+  metadata.gz: d72708bfcab861296da00c8476cb744e3b3ed69340a0074c02b2d587684bbc04af339ea407eb770d9e92ce7ce777be20d325c234bd2bb0311df4345c49fbb4a7
+  data.tar.gz: c1d9083dbab6b2a5a82f47f226122b9764637e0eb6362ac8b5a0b85a11ade854cc37ee9c743121dd5271d58d2173ebbd7783eb6d18f5c68474b3b45f3a6ac9cb

data/.rubocop.yml

@@ -0,0 +1,2 @@
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Niklas Häusele
+
+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,71 @@
+# RubyMCP - Build a MCP Server with Ruby
+
+A low-level Model-Context-Protocol implementation for Ruby. Supports [prompts](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/prompts/) and [completions](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/utilities/completion/#protocol-messages).
+
+```ruby
+server = RubyMCP::Server.new
+
+server.add_prompt(
+  name: "ruby_example",
+  description: "Example usage of a method",
+  arguments: [
+    {
+      name: "snippet",
+      description: "small ruby snippet",
+      required: true,
+      completions: ->(*) { [ 'String#split', 'Array#join', 'tally', 'unpack' ] }
+    }
+  ],
+  result: ->(snippet:) {
+    {
+      description: "Explain '#{snippet}'",
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: <<~TXT
+              You're a coding assistant in the editor zed.
+              You give one practical example for the given ruby method.
+              Only answer with a single code snippet and one line of explanation.
+              For example:
+              INPUT: '''String#split'''
+              OUTPUT: 'abc'.split('') # ['a', 'b', 'c']\n Splits the string"
+            TXT
+          }
+        },
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: "INPUT: '''#{snippet}'''"
+          }
+        }
+      ]
+    }
+  },
+)
+
+transport = RubyMCP::Transport::Stdio.new
+server.connect(transport)
+```
+
+## Logging
+
+RubyMCP supports [mcp logging](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/utilities/logging/). Each logging level has a corresponding method prefixed with `send_` and suffixed with `_log_message`.
+
+- **Debug Level:**
+  ```ruby
+  server.send_debug_log_message({ text: "Debug information" })
+  ```
+
+- **Info Level:**
+  ```ruby
+  server.send_info_log_message({ text: "Informational message" })
+  ```
+
+A MCP client can configure change the log severity or it can be set during server creation. The default is "info".
+
+```ruby
+server = Server.new(logging_verbosity: "debug")
+```

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/exe/ruby_mcp

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "ruby_mcp"
+
+server = RubyMCP::Server.new
+
+if server_impl = ARGV[0]
+  server.instance_eval(File.read(server_impl))
+else
+  RubyMCP.logger.info("No implementation given, starting default server")
+end
+
+transport = RubyMCP::Transport::Stdio.new
+server.connect(transport)

data/lib/ruby_mcp/capabilities/logging.rb

@@ -0,0 +1,27 @@
+module RubyMCP::Capabilities::Logging
+  LEVELS = {
+    "debug" =>     0,
+    "info" =>      1,
+    "notice" =>    2,
+    "warning" =>   3,
+    "error" =>     4,
+    "critical" =>  5,
+    "alert" =>     6,
+    "emergency" => 7
+  }
+
+  def logging_verbosity
+    @level ||= @default_logging_verbosity
+  end
+
+  def logging_verbosity=(level)
+    @level = level
+  end
+
+  LEVELS.each do |name, value|
+    define_method("send_#{name}_log_message") do |msg|
+      send_message(
+        jsonrpc: "2.0", method: "notifications/message", params: msg.merge(level: name)) if value <= LEVELS[logging_verbosity]
+    end
+  end
+end

data/lib/ruby_mcp/handlers/completion_complete.rb

@@ -0,0 +1,16 @@
+class RubyMCP::Handlers::CompletionComplete
+  def handle(server, request)
+    referenced_prompt = server.prompts.find_by_name(request.ref["name"])
+    RubyMCP.logger.debug(referenced_prompt[:arguments])
+    referenced_argument = referenced_prompt[:arguments].find { |argument| argument[:name] == request.argument_name }
+    computed_values = referenced_argument[:completions].call(**request.param)
+
+    server.answer(request,
+      completion: {
+        hasMore: false,
+        total: computed_values.count,
+        values: computed_values
+      }
+    )
+  end
+end

data/lib/ruby_mcp/handlers/initialize.rb

@@ -0,0 +1,22 @@
+class RubyMCP::Handlers::Initialize
+  def handle(server, request)
+    server.answer(request,
+      protocolVersion: "2024-11-05",
+      capabilities: {
+        logging: {},
+        prompts: {
+          listChanged: true
+        },
+        resources: {},
+        tools: {
+          listChanged: true
+        }
+      },
+      serverInfo: {
+        name: "RubyMCP",
+        version: RubyMCP::VERSION
+      }
+    )
+    server.lifecycle.initialize_response_sent!
+  end
+end

data/lib/ruby_mcp/handlers/logging_set_level.rb

@@ -0,0 +1,10 @@
+class RubyMCP::Handlers::LoggingSetLevel
+  def handle(server, request)
+    if request.level_valid?
+      server.logging_verbosity = request.level
+      server.answer(request, {})
+    else
+      server.error(request, code: -32602, message: "Invalid loglevel")
+    end
+  end
+end

data/lib/ruby_mcp/handlers/notifications_initialized.rb

@@ -0,0 +1,6 @@
+class RubyMCP::Handlers::NotificationsInitialized
+  def handle(server, request)
+    server.lifecycle.operation_phase!
+    RubyMCP.logger.info "Operation Phase started"
+  end
+end

data/lib/ruby_mcp/handlers/ping.rb

@@ -0,0 +1,5 @@
+class RubyMCP::Handlers::Ping
+  def handle(server, request)
+    server.answer(request, {})
+  end
+end

data/lib/ruby_mcp/handlers/prompts_get.rb

@@ -0,0 +1,15 @@
+class RubyMCP::Handlers::PromptsGet
+  def handle(server, request)
+    if prompt = server.prompts.find_by_name(request.name)
+      required_arguments = prompt[:arguments].filter_map { _1[:name].to_sym if _1[:required] }
+      all_required_arguments_given = (required_arguments - request.arguments.keys).empty?
+      if all_required_arguments_given
+        server.answer(request, **prompt[:result].call(**request.arguments))
+      else
+        server.error(request, code: -32602, message: "Missing required param")
+      end
+    else
+      server.error(request, code: -32602, message: "Invalid params")
+    end
+  end
+end

data/lib/ruby_mcp/handlers/prompts_list.rb

@@ -0,0 +1,5 @@
+class RubyMCP::Handlers::PromptsList
+  def handle(server, request)
+    server.answer(request, prompts: server.prompts.list)
+  end
+end

data/lib/ruby_mcp/handlers/resources_list.rb

@@ -0,0 +1,5 @@
+class RubyMCP::Handlers::ResourcesList
+  def handle(server, request)
+    server.answer(request, resources: server.resources.as_json)
+  end
+end

data/lib/ruby_mcp/handlers/resources_read.rb

@@ -0,0 +1,22 @@
+class RubyMCP::Handlers::ResourcesRead
+  def handle(server, request)
+    if resource = server.resources.find(request.uri)
+      server.answer(request,
+        contents: [ {
+          uri: resource.uri,
+          mimeType: resource.mime_type,
+          text: resource.reader.call(resource)
+        } ]
+      )
+    else
+      server.error(
+        request,
+        code: -32002,
+        message: "Resource not found",
+        data: {
+          uri: request.uri
+        }
+      )
+    end
+  end
+end

data/lib/ruby_mcp/handlers.rb

@@ -0,0 +1,27 @@
+module RubyMCP
+  class Handlers
+    def self.parse(json)
+      parsed = JSON.parse(json)
+      case parsed.fetch("method")
+      when "initialize"
+        Initialize
+      when "notifications/initialized"
+        NotificationsInitialized
+      when "ping"
+        Ping
+      when "prompts/get"
+        PromptsGet
+      when "prompts/list"
+        PromptsList
+      when "completion/complete"
+        CompletionComplete
+      when "resources/list"
+        ResourcesList
+      when "resources/read"
+        ResourcesRead
+      when "logging/setLevel"
+        LoggingSetLevel
+      end.new
+    end
+  end
+end

data/lib/ruby_mcp/prompts.rb

@@ -0,0 +1,25 @@
+module RubyMCP
+  class Prompts
+    def initialize
+      @prompts = {}
+    end
+
+    def add(name:, description:, arguments: [], result: Proc.new { [] }, completions: nil)
+      @prompts[name] = { description:, arguments:, result:, completions: }
+    end
+
+    def list
+      @prompts.map do |name, details|
+        {
+          name: name,
+          description: details[:description],
+          arguments: details[:arguments].map { _1.slice(:name, :description, :required) }
+        }
+      end
+    end
+
+    def find_by_name(name)
+      @prompts[name]
+    end
+  end
+end

data/lib/ruby_mcp/request.rb

@@ -0,0 +1,17 @@
+class RubyMCP::Request
+  def initialize(json)
+    @json = json
+  end
+
+  def method
+    @json["method"]
+  end
+
+  def id
+    @json["id"]
+  end
+
+  def allowed_in_lifecycle?(lifecycle)
+    true
+  end
+end

data/lib/ruby_mcp/requests/completion_complete.rb

@@ -0,0 +1,19 @@
+class RubyMCP::Requests::CompletionComplete < RubyMCP::Request
+  def ref
+    @json.dig("params", "ref")
+  end
+
+  def argument_name
+    @json.dig("params", "argument", "name")
+  end
+
+  def param
+    {
+      @json.dig("params", "argument", "name").to_sym => @json.dig("params", "argument", "value")
+    }
+  end
+
+  def allowed_in_lifecycle?(lifecycle)
+    lifecycle.operation_phase?
+  end
+end

data/lib/ruby_mcp/requests/initialize.rb

@@ -0,0 +1,5 @@
+class RubyMCP::Requests::Initialize < RubyMCP::Request
+  def allowed_in_lifecycle?(lifecycle)
+    lifecycle.initialization_pending?
+  end
+end

data/lib/ruby_mcp/requests/logging_set_level.rb

@@ -0,0 +1,9 @@
+class RubyMCP::Requests::LoggingSetLevel < RubyMCP::Request
+  def level
+    @json.dig("params", "level")
+  end
+
+  def level_valid?
+    RubyMCP::Capabilities::Logging::LEVELS.keys.include? level
+  end
+end

data/lib/ruby_mcp/requests/notifications_initialized.rb

@@ -0,0 +1,5 @@
+class RubyMCP::Requests::NotificationsInitialized < RubyMCP::Request
+  def allowed_in_lifecycle?(lifecycle)
+    lifecycle.initialize_response_sent?
+  end
+end

data/lib/ruby_mcp/requests/ping.rb

@@ -0,0 +1,2 @@
+class RubyMCP::Requests::Ping < RubyMCP::Request
+end

data/lib/ruby_mcp/requests/prompts_get.rb

@@ -0,0 +1,15 @@
+class RubyMCP::Requests::PromptsGet < RubyMCP::Request
+  attr_reader :json
+
+  def name
+    @json.dig("params", "name")
+  end
+
+  def arguments
+    @json.dig("params", "arguments").transform_keys(&:to_sym)
+  end
+
+  def allowed_in_lifecycle?(lifecycle)
+    lifecycle.operation_phase?
+  end
+end

data/lib/ruby_mcp/requests/prompts_list.rb

@@ -0,0 +1,5 @@
+class RubyMCP::Requests::PromptsList < RubyMCP::Request
+  def allowed_in_lifecycle?(lifecycle)
+    lifecycle.operation_phase?
+  end
+end

data/lib/ruby_mcp/requests/resources_list.rb

@@ -0,0 +1,5 @@
+class RubyMCP::Requests::ResourcesList < RubyMCP::Request
+  def allowed_in_lifecycle?(lifecycle)
+    lifecycle.operation_phase?
+  end
+end

data/lib/ruby_mcp/requests/resources_read.rb

@@ -0,0 +1,13 @@
+class RubyMCP::Requests::ResourcesRead < RubyMCP::Request
+  def params
+    @json.dig("params")
+  end
+
+  def uri
+    params["uri"]
+  end
+
+  def allowed_in_lifecycle?(lifecycle)
+    lifecycle.operation_phase?
+  end
+end

data/lib/ruby_mcp/requests.rb

@@ -0,0 +1,29 @@
+module RubyMCP
+  class Requests
+    def self.parse(json)
+      parsed = JSON.parse(json)
+      case parsed.fetch("method")
+      when "initialize"
+        Initialize
+      when "notifications/initialized"
+        NotificationsInitialized
+      when "ping"
+        Ping
+      when "prompts/get"
+        PromptsGet
+      when "prompts/list"
+        PromptsList
+      when "completion/complete"
+        CompletionComplete
+      when "resources/list"
+        ResourcesList
+      when "resources/read"
+        ResourcesRead
+      when "logging/setLevel"
+        LoggingSetLevel
+      else
+        Request
+      end.new(parsed)
+    end
+  end
+end

data/lib/ruby_mcp/resources.rb

@@ -0,0 +1,28 @@
+module RubyMCP
+  Resource = Data.define(:uri, :name, :description, :mime_type, :reader)
+
+  class Resources
+    def initialize
+      @resources = {}
+    end
+
+    def add(uri:, name:, description: nil, mime_type: nil, reader: nil)
+      @resources[uri] = Resource.new(uri, name, description, mime_type, reader)
+    end
+
+    def find(uri)
+      @resources[uri]
+    end
+
+    def as_json
+      @resources.map do |uri, resource|
+        {
+          uri: uri,
+          name: resource.name,
+          description: resource.description,
+          mimeType: resource.mime_type
+        }
+      end
+    end
+  end
+end

data/lib/ruby_mcp/server/lifecycle.rb

@@ -0,0 +1,33 @@
+class RubyMCP::Server::Lifecycle
+  STATES = [ :initialization_pending, :initialize_response_sent, :operation_phase_started ]
+
+  def initialize
+    @current = 0
+  end
+
+  def initialize_response_sent!
+    @current = 1
+  end
+
+  def operation_phase!
+    @current = 2
+  end
+
+  def operation_phase?
+    current == :operation_phase_started
+  end
+
+  def initialization_pending?
+    current == :initialization_pending
+  end
+
+  def initialize_response_sent?
+    current == :initialize_response_sent
+  end
+
+  private
+
+  def current
+    STATES[@current]
+  end
+end

data/lib/ruby_mcp/server.rb

@@ -0,0 +1,84 @@
+module RubyMCP
+  class Server
+    include Capabilities::Logging
+
+    attr_reader :lifecycle, :prompts, :resources
+
+    def initialize(logging_verbosity: "info")
+      @lifecycle = Lifecycle.new
+      @prompts = Prompts.new
+      @resources = Resources.new
+
+      @default_logging_verbosity = logging_verbosity
+    end
+
+    def connect(transport)
+      @transport = transport
+
+      setup_trap
+      setup_message_handler
+      setup_close_handler
+      start_transport
+    end
+
+    def add_prompt(...)
+      @prompts.add(...)
+    end
+
+    def add_resource(...)
+      @resources.add(...)
+    end
+
+    def send_message(message)
+      RubyMCP.logger.debug "S -> C : #{message}"
+      @transport.send(message)
+    end
+
+    def answer(request, result)
+      send_answer(request, result:)
+    end
+
+    def error(request, error)
+      send_answer(request, error:)
+    end
+
+    private
+
+    def send_answer(request, **message)
+      send_message(
+        id: request.id,
+        jsonrpc: "2.0",
+        **message
+      )
+    end
+
+    def setup_trap
+      trap("INT") do
+        @transport.close
+        exit
+      end
+    end
+
+    def setup_message_handler
+      @transport.on_message do |message|
+        request = Requests.parse(message)
+        handler = Handlers.parse(message)
+
+        RubyMCP.logger.debug "C -> S : #{request.method}"
+
+        handler.handle(self, request) if request.allowed_in_lifecycle?(@lifecycle)
+      end
+    end
+
+    def setup_close_handler
+      @transport.on_close do
+        RubyMCP.logger.info "Server stopped"
+      end
+    end
+
+    def start_transport
+      RubyMCP.logger.info("Server connecting with #{@transport.class}")
+      @transport.start
+    end
+  end
+end

data/lib/ruby_mcp/transport/stdio.rb

@@ -0,0 +1,33 @@
+module RubyMCP
+  class Transport
+    class Stdio < Transport
+      def start
+        @running = true
+
+        while @running
+          begin
+            line = $stdin.gets
+
+            break if line.nil?
+
+            @on_message.call(line.strip)
+          rescue StandardError => e
+            RubyMCP.logger.error("Exception: #{e}")
+          end
+        end
+
+        @on_close.call
+      end
+
+      def send(message)
+        $stdout.puts(JSON.generate(message))
+        $stdout.flush
+      end
+
+
+      def on_close(&block)
+        @on_close = block
+      end
+    end
+  end
+end

data/lib/ruby_mcp/transport/test.rb

@@ -0,0 +1,25 @@
+class RubyMCP::Transport::Test < RubyMCP::Transport
+  attr_reader :responses
+  attr_reader :client_message_queue
+
+  def initialize
+    @client_message_queue = []
+    @responses = []
+  end
+
+  def start
+    @running = true
+  end
+
+  def send(message)
+    @responses << JSON.generate(message)
+  end
+
+  def client_message(message)
+    @client_message_queue << JSON.generate(message)
+  end
+
+  def process_message
+    @on_message.call(@client_message_queue.shift)
+  end
+end

data/lib/ruby_mcp/transport.rb

@@ -0,0 +1,15 @@
+module RubyMCP
+  class Transport
+    def close
+      @running = false
+    end
+
+    def on_message(&block)
+      @on_message = block
+    end
+
+    def on_close(&block)
+      @on_close = block
+    end
+  end
+end

data/lib/ruby_mcp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubyMCP
+  VERSION = "0.1.0"
+end

data/lib/ruby_mcp.rb

@@ -0,0 +1,20 @@
+require "json"
+require "securerandom"
+require "logger"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect("ruby_mcp" => "RubyMCP")
+loader.setup
+
+module RubyMCP
+  def self.logger
+    @logger ||= ::Logger.new($stderr).tap do |log|
+      log.formatter = proc do |severity, datetime, progname, msg|
+        "[RubyMCP] #{severity[0]}, #{msg}\n"
+      end
+    end
+  end
+end
+
+loader.eager_load

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: ruby_mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Niklas Häusele
+bindir: exe
+cert_chain: []
+date: 2025-03-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.7.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.7.2
+email:
+- niklas.haeusele@hey.com
+executables:
+- ruby_mcp
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- LICENSE
+- README.md
+- Rakefile
+- exe/ruby_mcp
+- lib/ruby_mcp.rb
+- lib/ruby_mcp/capabilities/logging.rb
+- lib/ruby_mcp/handlers.rb
+- lib/ruby_mcp/handlers/completion_complete.rb
+- lib/ruby_mcp/handlers/initialize.rb
+- lib/ruby_mcp/handlers/logging_set_level.rb
+- lib/ruby_mcp/handlers/notifications_initialized.rb
+- lib/ruby_mcp/handlers/ping.rb
+- lib/ruby_mcp/handlers/prompts_get.rb
+- lib/ruby_mcp/handlers/prompts_list.rb
+- lib/ruby_mcp/handlers/resources_list.rb
+- lib/ruby_mcp/handlers/resources_read.rb
+- lib/ruby_mcp/prompts.rb
+- lib/ruby_mcp/request.rb
+- lib/ruby_mcp/requests.rb
+- lib/ruby_mcp/requests/completion_complete.rb
+- lib/ruby_mcp/requests/initialize.rb
+- lib/ruby_mcp/requests/logging_set_level.rb
+- lib/ruby_mcp/requests/notifications_initialized.rb
+- lib/ruby_mcp/requests/ping.rb
+- lib/ruby_mcp/requests/prompts_get.rb
+- lib/ruby_mcp/requests/prompts_list.rb
+- lib/ruby_mcp/requests/resources_list.rb
+- lib/ruby_mcp/requests/resources_read.rb
+- lib/ruby_mcp/resources.rb
+- lib/ruby_mcp/server.rb
+- lib/ruby_mcp/server/lifecycle.rb
+- lib/ruby_mcp/transport.rb
+- lib/ruby_mcp/transport/stdio.rb
+- lib/ruby_mcp/transport/test.rb
+- lib/ruby_mcp/version.rb
+homepage: https://github.com/codergeek121/ruby_mcp
+licenses: []
+metadata:
+  homepage_uri: https://github.com/codergeek121/ruby_mcp
+  source_code_uri: https://github.com/codergeek121/ruby_mcp
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.6
+specification_version: 4
+summary: Low-level MCP protocol sdk for Ruby.
+test_files: []