mcp-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 610a73e9025b6400f091beeec7e0e0b9b51e917ba57b068f7132fd2dad3fa207
+  data.tar.gz: 8a5533dd1abdb1fbdde067facfe0ceeeb50d9fac332ba4ec4c4815a9b8f1a199
+SHA512:
+  metadata.gz: be76a1399e5121d0e0886489630fe7695b9fba3cea55835d6da2d67d5b74d3a714f68c354dbf447e8953f965c0c65e416e12417ee109fe4695f47cc4c940bdc6
+  data.tar.gz: d0ec9f439c4bc497c264241000269b7c5928167f0623a3a34335e6c28b597c95967b38819051a954f96323e861ea6553d218bc639df7b52697185463da1ac158

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-02-12
+
+### Added
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 funwarioisii
+
+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,67 @@
+# MCP-RB
+
+A lightweight Ruby framework for implementing MCP (Model Context Protocol) servers with a Sinatra-like DSL.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mcp-rb'
+```
+
+## Usage
+
+Here's a simple example of how to create an MCP server:
+
+```ruby
+require 'mcp'
+
+name "hello-world"
+
+# リソースの定義
+resource "hello://world",
+  name: "Hello World",
+  description: "A simple hello world message" do
+  "Hello, World!"
+end
+
+tool "greet",
+  description: "Greet someone by name",
+  input_schema: {
+    type: :object,
+    properties: {
+      name: {
+        type: :string,
+        description: "Name to greet"
+      }
+    },
+    required: [:name]
+  } do |args|
+  "Hello, #{args[:name]}!"
+end
+```
+
+## Testing
+
+```bash
+ruby -Ilib:test -e "Dir.glob('./test/**/*_test.rb').each { |f| require f }"
+```
+
+Test with MCP Inspector
+
+```bash
+bunx @modelcontextprotocol/inspector $(pwd)/examples/hello_world.rb
+```
+
+Find broken using `hello_world.rb`
+
+```bash
+./test/test_requests.sh
+```
+
+## Formatting
+
+```bash
+bundle exec standardrb --fix
+```

data/lib/mcp/app/resource.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module MCP
+  class App
+    module Resource
+      def register_resource(uri, name:, mime_type: "text/plain", description: "", &block)
+        raise ArgumentError, "Resource name cannot be nil or empty" if uri.nil? || uri.empty?
+        raise ArgumentError, "Block must be provided" unless block_given?
+
+        resources[uri] = {
+          uri:, name:, mime_type:, description:,
+          handler: block
+        }
+      end
+
+      def list_resources(cursor: nil, page_size: nil)
+        start_index = cursor&.to_i || 0
+        values = resources.values
+
+        if page_size.nil?
+          paginated = values[start_index..]
+          next_cursor = ""
+        else
+          paginated = values[start_index, page_size]
+          has_next = start_index + page_size < values.length
+          next_cursor = has_next ? (start_index + page_size).to_s : ""
+        end
+
+        {
+          resources: paginated.map { |r| format_resource(r) },
+          nextCursor: next_cursor
+        }
+      end
+
+      def read_resource(uri)
+        resource = resources[uri]
+        raise ArgumentError, "Resource not found: #{uri}" unless resource
+
+        begin
+          content = resource[:handler].call
+          {
+            contents: [{
+              uri: resource[:uri],
+              mimeType: resource[:mime_type],
+              text: content
+            }]
+          }
+        rescue => e
+          raise ArgumentError, "Error reading resource: #{e.message}"
+        end
+      end
+
+      private
+
+      def resources
+        @resources ||= {}
+      end
+
+      def format_resource(resource)
+        {
+          uri: resource[:uri],
+          name: resource[:name],
+          description: resource[:description],
+          mimeType: resource[:mime_type]
+        }
+      end
+    end
+  end
+end

data/lib/mcp/app/tool.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module MCP
+  class App
+    module Tool
+      def register_tool(name, description: "", input_schema: {}, &block)
+        raise ArgumentError, "Tool name cannot be nil or empty" if name.nil? || name.empty?
+        raise ArgumentError, "Block must be provided" unless block_given?
+
+        tools[name] = {
+          name: name,
+          description: description,
+          input_schema: input_schema,
+          handler: block
+        }
+      end
+
+      def list_tools(cursor: nil, page_size: 10)
+        tool_values = tools.values
+        start_index = cursor ? cursor.to_i : 0
+        paginated = tool_values[start_index, page_size]
+        next_cursor = (start_index + page_size < tool_values.length) ? (start_index + page_size).to_s : ""
+
+        {
+          tools: paginated.map { |t| format_tool(t) },
+          nextCursor: next_cursor
+        }
+      end
+
+      def call_tool(name, **arguments)
+        tool = tools[name]
+        raise ArgumentError, "Tool not found: #{name}" unless tool
+
+        begin
+          result = tool[:handler].call(arguments)
+          {
+            content: [
+              {
+                type: "text",
+                text: result.to_s
+              }
+            ],
+            isError: false
+          }
+        rescue => e
+          {
+            content: [
+              {
+                type: "text",
+                text: "Error: #{e.message}"
+              }
+            ],
+            isError: true
+          }
+        end
+      end
+
+      private
+
+      def tools
+        @tools ||= {}
+      end
+
+      def format_tool(tool)
+        {
+          name: tool[:name],
+          description: tool[:description],
+          inputSchema: tool[:input_schema]
+        }
+      end
+    end
+  end
+end

data/lib/mcp/app.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "app/resource"
+require_relative "app/tool"
+
+module MCP
+  class App
+    include Resource
+    include Tool
+  end
+end

data/lib/mcp/constants.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module MCP
+  module Constants
+    JSON_RPC_VERSION = "2.0"
+
+    module ErrorCodes
+      NOT_INITIALIZED = -32_002
+      ALREADY_INITIALIZED = -32_002
+
+      INVALID_REQUEST = -32_600
+      METHOD_NOT_FOUND = -32_601
+      UNSUPPORTED_PROTOCOL_VERSION = -32_602
+      INTERNAL_ERROR = -32_603
+    end
+
+    module RequestMethods
+      INITIALIZE = "initialize"
+      INITIALIZED = "notifications/initialized"
+      PING = "ping"
+      TOOLS_LIST = "tools/list"
+      TOOLS_CALL = "tools/call"
+      RESOURCES_LIST = "resources/list"
+      RESOURCES_READ = "resources/read"
+      RESOURCES_TEMPLATES_LIST = "resources/templates/list"
+    end
+  end
+end.freeze

data/lib/mcp/delegator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module MCP
+  module Delegator
+    def self.delegate(*methods)
+      methods.each do |method_name|
+        define_method(method_name) do |*args, **kwargs, &block|
+          # name が呼ばれたら Server インスタンスを生成
+          # もうすこしいい感じにしたい
+          if method_name == :name && !MCP.server
+            MCP.initialize_server(name: args.first || "default")
+          end
+          MCP.server.send(method_name, *args, **kwargs, &block)
+        end
+      end
+    end
+
+    delegate :name, :resource, :tool
+  end
+end

data/lib/mcp/server.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "json"
+require "English"
+require "uri"
+
+module MCP
+  class Server
+    attr_accessor :name
+    attr_reader :initialized
+
+    def initialize(name:, version: VERSION)
+      @name = name
+      @version = version
+      @app = App.new
+      @initialized = false
+      @supported_protocol_versions = [PROTOCOL_VERSION]
+    end
+
+    def name(value = nil) # standard:disable Lint/DuplicateMethods
+      return @name if value.nil?
+
+      @name = value
+    end
+
+    def tool(name, description: "", input_schema: {}, &block)
+      @app.register_tool(name, description: description, input_schema: input_schema, &block)
+    end
+
+    def resource(uri, name:, mime_type: "text/plain", description: "", &block)
+      @app.register_resource(uri, name: name, mime_type: mime_type, description: description, &block)
+    end
+
+    def run
+      while (input = $stdin.gets)
+        process_input(input)
+      end
+    end
+
+    def list_tools
+      @app.list_tools[:tools]
+    end
+
+    def call_tool(name, **args)
+      @app.call_tool(name, **args).dig(:content, 0, :text)
+    end
+
+    def list_resources
+      @app.list_resources[:resources]
+    end
+
+    def read_resource(uri)
+      @app.read_resource(uri).dig(:contents, 0, :text)
+    end
+
+    private
+
+    def process_input(line)
+      request = JSON.parse(line, symbolize_names: true)
+      response = handle_request(request)
+      return unless response # 通知の場合はnilが返されるので、何も出力しない
+
+      response_json = JSON.generate(response)
+      $stdout.puts(response_json)
+      $stdout.flush
+    rescue JSON::ParserError => e
+      error_response(nil, Constants::ErrorCodes::INVALID_REQUEST, "Invalid JSON: #{e.message}")
+    rescue => e
+      error_response(nil, Constants::ErrorCodes::INTERNAL_ERROR, e.message)
+    end
+
+    def handle_request(request)
+      allowed_methods = [
+        Constants::RequestMethods::INITIALIZE,
+        Constants::RequestMethods::INITIALIZED,
+        Constants::RequestMethods::PING
+      ]
+      if !@initialized && !allowed_methods.include?(request[:method])
+        return error_response(request[:id], Constants::ErrorCodes::NOT_INITIALIZED, "Server not initialized")
+      end
+
+      case request[:method]
+      when Constants::RequestMethods::INITIALIZE then handle_initialize(request)
+      when Constants::RequestMethods::INITIALIZED then handle_initialized(request)
+      when Constants::RequestMethods::PING then handle_ping(request)
+      when Constants::RequestMethods::TOOLS_LIST then handle_list_tools(request)
+      when Constants::RequestMethods::TOOLS_CALL then handle_call_tool(request)
+      when Constants::RequestMethods::RESOURCES_LIST then handle_list_resources(request)
+      when Constants::RequestMethods::RESOURCES_READ then handle_read_resource(request)
+      when Constants::RequestMethods::RESOURCES_TEMPLATES_LIST then handle_list_resources_templates(request)
+      else
+        error_response(request[:id], Constants::ErrorCodes::METHOD_NOT_FOUND, "Unknown method: #{request[:method]}")
+      end
+    end
+
+    def handle_initialize(request)
+      return error_response(request[:id], Constants::ErrorCodes::ALREADY_INITIALIZED, "Server already initialized") if @initialized
+
+      client_version = request.dig(:params, :protocolVersion)
+      unless @supported_protocol_versions.include?(client_version)
+        return error_response(
+          request[:id],
+          Constants::ErrorCodes::UNSUPPORTED_PROTOCOL_VERSION,
+          "Unsupported protocol version",
+          {
+            supported: @supported_protocol_versions,
+            requested: client_version
+          }
+        )
+      end
+
+      {
+        jsonrpc: MCP::Constants::JSON_RPC_VERSION,
+        id: request[:id],
+        result: {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: {
+            logging: {},
+            prompts: {
+              listChanged: false
+            },
+            resources: {
+              subscribe: false,
+              listChanged: false
+            },
+            tools: {
+              listChanged: false
+            }
+          },
+          serverInfo: {
+            name: @name,
+            version: @version
+          }
+        }
+      }
+    end
+
+    def handle_initialized(request)
+      return error_response(request[:id], Constants::ErrorCodes::ALREADY_INITIALIZED, "Server already initialized") if @initialized
+
+      @initialized = true
+      nil  # 通知に対しては応答を返さない
+    end
+
+    def handle_list_tools(request)
+      cursor = request.dig(:params, :cursor)
+      result = @app.list_tools(cursor: cursor)
+      success_response(request[:id], result)
+    end
+
+    def handle_call_tool(request)
+      name = request.dig(:params, :name)
+      arguments = request.dig(:params, :arguments)
+      begin
+        result = @app.call_tool(name, **arguments.transform_keys(&:to_sym))
+        success_response(request[:id], result)
+      rescue ArgumentError => e
+        error_response(request[:id], Constants::ErrorCodes::INVALID_REQUEST, e.message)
+      end
+    end
+
+    def handle_list_resources(request)
+      cursor = request.dig(:params, :cursor)
+      result = @app.list_resources(cursor:)
+      success_response(request[:id], result)
+    end
+
+    def handle_read_resource(request)
+      uri = request.dig(:params, :uri)
+      result = @app.read_resource(uri)
+
+      if result
+        success_response(request[:id], result)
+      else
+        error_response(request[:id], Constants::ErrorCodes::INVALID_REQUEST, "Resource not found", {uri: uri})
+      end
+    end
+
+    def handle_ping(request)
+      success_response(request[:id], {})
+    end
+
+    def success_response(id, result)
+      {
+        jsonrpc: MCP::Constants::JSON_RPC_VERSION,
+        id: id,
+        result: result
+      }
+    end
+
+    def error_response(id, code, message, data = nil)
+      response = {
+        jsonrpc: MCP::Constants::JSON_RPC_VERSION,
+        id: id,
+        error: {
+          code: code,
+          message: message
+        }
+      }
+      response[:error][:data] = data if data
+      response
+    end
+  end
+end

data/lib/mcp/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MCP
+  PROTOCOL_VERSION = "2024-11-05"
+  VERSION = "0.1.0"
+end

data/lib/mcp.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "English"
+require "json"
+
+require_relative "mcp/version"
+require_relative "mcp/constants"
+require_relative "mcp/app"
+require_relative "mcp/server"
+require_relative "mcp/delegator"
+
+module MCP
+  class << self
+    attr_reader :server
+
+    def initialize_server(name:, **options)
+      @server ||= Server.new(name: name, **options)
+    end
+  end
+
+  # require 'mcp' したファイルで最後に到達したら実行されるようにするため
+  # https://docs.ruby-lang.org/ja/latest/method/Kernel/m/at_exit.html
+  at_exit { server.run if $ERROR_INFO.nil? && server }
+
+  def self.new(**options, &block)
+    @server = Server.new(**options)
+    return @server if block.nil?
+
+    if block.arity.zero?
+      @server.instance_eval(&block)
+    else
+      (block.arity == 1) ? yield(@server) : yield
+    end
+
+    @server
+  end
+end
+
+extend MCP::Delegator # standard:disable Style/MixinUsage

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: mcp-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- funwarioisii
+bindir: bin
+cert_chain: []
+date: 2025-02-12 00:00:00.000000000 Z
+dependencies: []
+description: MCP-RB is a Ruby framework that provides a Sinatra-like DSL for implementing
+  Model Context Protocol servers.
+email:
+- kazuyukihashimoto2006@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/mcp.rb
+- lib/mcp/app.rb
+- lib/mcp/app/resource.rb
+- lib/mcp/app/tool.rb
+- lib/mcp/constants.rb
+- lib/mcp/delegator.rb
+- lib/mcp/server.rb
+- lib/mcp/version.rb
+homepage: https://github.com/funwarioisii/mcp-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/funwarioisii/mcp-rb
+  source_code_uri: https://github.com/funwarioisii/mcp-rb
+  changelog_uri: https://github.com/funwarioisii/mcp-rb/blob/main/CHANGELOG.md
+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.2
+specification_version: 4
+summary: A lightweight Ruby framework for implementing MCP (Model Context Protocol)
+  servers
+test_files: []