mcp-rb 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28e6b1fc53252ecd7717e71d06f0c124c61a8fbb9e389fa9514f3249b056930e
-  data.tar.gz: 454af20d33b8cbe80dad61214b0ca3680a8715bef024d4d26dd77a5b800e37ba
+  metadata.gz: 4ff3f38b8c9fec5aac8fce9d0906f956a77f481ac0477c273e9b677948d0a8cb
+  data.tar.gz: 116def752685bfa0792c6d2b1dc6bd75e6b029cec03205fb2a67b00d84532cfc
 SHA512:
-  metadata.gz: 6aca66d612f5851304248561e0eb73402ef30d30da6fd45c35aea89b43d6499c29da58a37f6deae55931a3ede9eb56de4cf447595adaee8f227836e8923f1823
-  data.tar.gz: cde9c8f9b18b6945d5e5e478ea18e1592c372393b1263f329b35bc0510df58110feda73ae1fcd785d93af0e701fe6bfaab200296845d7b601ba33525337f654c
+  metadata.gz: 3ed62e7606ff685a999c7f95118167e30d8ecb6a6ff35a260223b60fed2fc65599a79bd22424dfde3b0bfc4cd1b3bdf1cb46dcb6877c7720e8837021f456d8cf
+  data.tar.gz: 5536f506e8e2c89a73fe34acc6edc3981b444672ca8cb3730e089eea22fa9194cee33e6afe26a2442175441487283828aa29103e78b39c8387714d2f1c6a5a82

data/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.3.1] - 2025-03-05
+
+### Added
+- Add `resources/templates/list` method: https://github.com/funwarioisii/mcp-rb/pull/5
+
+## [0.3.0] - 2025-02-19
+
+- Allow specifying the version via DSL keyword: https://github.com/funwarioisii/mcp-rb/pull/2
+- Add MCP Client: https://github.com/funwarioisii/mcp-rb/pull/3
+
+### Breaking Changes
+- `MCP::PROTOCOL_VERSION` is moved to `MCP::Constants::PROTOCOL_VERSION`
+  - https://github.com/funwarioisii/mcp-rb/pull/3/commits/caad65500935a8eebfe024dbd25de0d16868c44e
+
 ## [0.2.0] - 2025-02-14
 
 ### Breaking Changes

data/README.md

@@ -19,6 +19,8 @@ require 'mcp'
 
 name "hello-world"
 
+version "1.0.0"
+
 # Define a resource
 resource "hello://world" do
   name "Hello World"
@@ -26,6 +28,13 @@ resource "hello://world" do
   call { "Hello, World!" }
 end
 
+# Define a resource template
+resource_template "hello://{user_name}" do
+  name "Hello User"
+  description "A simple hello user message"
+  call { |args| "Hello, #{args[:user_name]}!" }
+end
+
 # Define a tool
 tool "greet" do
   description "Greet someone by name"
@@ -36,6 +45,24 @@ tool "greet" do
 end
 ```
 
+## Supported specifications
+
+Reference: [MCP 2024-11-05](https://spec.modelcontextprotocol.io/specification/2024-11-05/)
+
+- [Base Protocol](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/)
+  - ping
+  - stdio transport
+- [Server features](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/)
+  - Resources
+    - resources/read
+    - resources/list
+    - resources/templates/list
+  - Tools
+    - tools/list
+    - tools/call
+
+Any capabilities are not supported yet.
+
 ## Testing
 
 ```bash
@@ -85,4 +112,3 @@ gem push mcp-rb-*.gem
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md)
-

data/lib/mcp/app/resource.rb

@@ -69,11 +69,11 @@ module MCP
 
         if page_size.nil?
           paginated = values[start_index..]
-          next_cursor = ""
+          next_cursor = nil
         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 : ""
+          next_cursor = has_next ? (start_index + page_size).to_s : nil
         end
 
         {
@@ -84,6 +84,29 @@ module MCP
 
       def read_resource(uri)
         resource = resources[uri]
+
+        # If no direct match, check if it matches a template
+        if resource.nil? && respond_to?(:find_matching_template)
+          template, variable_values = find_matching_template(uri)
+
+          if template
+            begin
+              # Call the template handler with the extracted variables
+              content = template[:handler].call(variable_values)
+              return {
+                contents: [{
+                  uri: uri,
+                  mimeType: template[:mime_type],
+                  text: content
+                }]
+              }
+            rescue => e
+              raise ArgumentError, "Error reading resource from template: #{e.message}"
+            end
+          end
+        end
+
+        # If we still don't have a resource, raise an error
         raise ArgumentError, "Resource not found: #{uri}" unless resource
 
         begin

data/lib/mcp/app/resource_template.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module MCP
+  class App
+    module ResourceTemplate
+      def resource_templates
+        @resource_templates ||= {}
+      end
+
+      class ResourceTemplateBuilder
+        attr_reader :uri_template, :name, :description, :mime_type, :handler
+
+        def initialize(uri_template)
+          raise ArgumentError, "Resource URI template cannot be nil or empty" if uri_template.nil? || uri_template.empty?
+          @uri_template = uri_template
+          @name = ""
+          @description = ""
+          @mime_type = "text/plain"
+          @handler = nil
+          @variables = extract_variables(uri_template)
+        end
+
+        # standard:disable Lint/DuplicateMethods,Style/TrivialAccessors
+        def name(value)
+          @name = value
+        end
+        # standard:enable Lint/DuplicateMethods,Style/TrivialAccessors
+
+        # standard:disable Lint/DuplicateMethods,Style/TrivialAccessors
+        def description(text)
+          @description = text
+        end
+        # standard:enable Lint/DuplicateMethods,Style/TrivialAccessors
+
+        # standard:disable Lint/DuplicateMethods,Style/TrivialAccessors
+        def mime_type(value)
+          @mime_type = value
+        end
+        # standard:enable Lint/DuplicateMethods,Style/TrivialAccessors
+
+        def call(&block)
+          @handler = block
+        end
+
+        def to_resource_template_hash
+          raise ArgumentError, "Name must be provided" if @name.empty?
+
+          {
+            uri_template: @uri_template,
+            name: @name,
+            mime_type: @mime_type,
+            description: @description,
+            handler: @handler,
+            variables: @variables
+          }
+        end
+
+        # Extract variables from a URI template
+        # e.g., "channels://{channel_id}" => ["channel_id"]
+        def extract_variables(uri_template)
+          variables = []
+          uri_template.scan(/\{([^}]+)\}/) do |match|
+            variables << match[0]&.to_sym
+          end
+          variables
+        end
+
+        # Creates a pattern for matching URIs against this template
+        def to_pattern
+          pattern_string = Regexp.escape(@uri_template).gsub(/\\\{[^}]+\\\}/) do |match|
+            "([^/]+)"
+          end
+          Regexp.new("^#{pattern_string}$")
+        end
+
+        # Extract variable values from a concrete URI based on the template
+        # e.g., template: "channels://{channel_id}", uri: "channels://123" => {"channel_id" => "123"}
+        def extract_variable_values(uri)
+          pattern = to_pattern
+          match = pattern.match(uri)
+          return {} unless match
+
+          result = {}
+          @variables.each_with_index do |var_name, index|
+            result[var_name] = match[index + 1]
+          end
+          result
+        end
+      end
+
+      def register_resource_template(uri_template, &block)
+        builder = ResourceTemplateBuilder.new(uri_template)
+        builder.instance_eval(&block)
+        template_hash = builder.to_resource_template_hash
+        resource_templates[uri_template] = template_hash
+        template_hash
+      end
+
+      # Find a template that matches the given URI and extract variable values
+      def find_matching_template(uri)
+        resource_templates.each do |template_uri, template|
+          builder = ResourceTemplateBuilder.new(template_uri)
+          variable_values = builder.extract_variable_values(uri)
+          return [template, variable_values] unless variable_values.empty?
+        end
+        [nil, {}]
+      end
+
+      def list_resource_templates(cursor: nil, page_size: nil)
+        start_index = cursor&.to_i || 0
+        values = resource_templates.values
+
+        if page_size.nil?
+          paginated = values[start_index..]
+          next_cursor = nil
+        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 : nil
+        end
+
+        {
+          resourceTemplates: paginated.map { |t| format_resource_template(t) },
+          nextCursor: next_cursor
+        }
+      end
+
+      private
+
+      def format_resource_template(template)
+        {
+          uriTemplate: template[:uri_template],
+          name: template[:name],
+          description: template[:description],
+          mimeType: template[:mime_type]
+        }
+      end
+    end
+  end
+end

data/lib/mcp/app/tool.rb

@@ -77,7 +77,7 @@ module MCP
         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 : ""
+        next_cursor = (start_index + page_size < tool_values.length) ? (start_index + page_size).to_s : nil
 
         {
           tools: paginated.map { |t| format_tool(t) },

data/lib/mcp/app.rb

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

data/lib/mcp/client.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "securerandom"
+require_relative "constants"
+
+module MCP
+  class Client
+    attr_reader :command, :args, :process, :stdin, :stdout, :stderr, :wait_thread
+
+    def initialize(command:, args: [], name: "mcp-client", version: VERSION)
+      @command = command
+      @args = args
+      @process = nil
+      @name = name
+      @version = version
+    end
+
+    def connect
+      return if @process
+
+      start_server
+      initialize_connection
+      self
+    end
+
+    def running? = !@process.nil?
+
+    def list_tools
+      ensure_running
+      send_request({
+        jsonrpc: Constants::JSON_RPC_VERSION,
+        method: Constants::RequestMethods::TOOLS_LIST,
+        params: {},
+        id: SecureRandom.uuid
+      })
+    end
+
+    def call_tool(name:, args: {})
+      ensure_running
+      send_request({
+        jsonrpc: Constants::JSON_RPC_VERSION,
+        method: Constants::RequestMethods::TOOLS_CALL,
+        params: {
+          name: name,
+          arguments: args
+        },
+        id: SecureRandom.uuid
+      })
+    end
+
+    def close
+      return unless @process
+
+      @stdin.close
+      @stdout.close
+      @stderr.close
+      Process.kill("TERM", @process)
+      @wait_thread.join
+      @process = nil
+    rescue IOError, Errno::ESRCH
+      # プロセスが既に終了している場合は無視
+      @process = nil
+    end
+
+    private
+
+    def ensure_running
+      raise "Server process not running. Call #start first." unless running?
+    end
+
+    def initialize_connection
+      response = send_request({
+        jsonrpc: Constants::JSON_RPC_VERSION,
+        method: "initialize",
+        params: {
+          protocolVersion: Constants::PROTOCOL_VERSION,
+          client: {
+            name: @name,
+            version: @version
+          }
+        },
+        id: SecureRandom.uuid
+      })
+
+      @stdin.puts(JSON.generate({
+        jsonrpc: Constants::JSON_RPC_VERSION,
+        method: "notifications/initialized"
+      }))
+
+      response
+    end
+
+    def start_server
+      @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@command, *@args)
+      @process = @wait_thread.pid
+
+      Thread.new do
+        while (line = @stderr.gets)
+          warn "[MCP Server] #{line}"
+        end
+      rescue IOError
+        # ignore when stream is closed
+      end
+    end
+
+    def send_request(request)
+      @stdin.puts(JSON.generate(request))
+      response = @stdout.gets
+      raise "No response from server" unless response
+
+      result = JSON.parse(response, symbolize_names: true)
+      if result[:error]
+        raise "Server error: #{result[:error][:message]} (#{result[:error][:code]})"
+      end
+
+      result[:result]
+    rescue JSON::ParserError => e
+      raise "Invalid JSON response: #{e.message}"
+    end
+  end
+end

data/lib/mcp/constants.rb

@@ -3,6 +3,7 @@
 module MCP
   module Constants
     JSON_RPC_VERSION = "2.0"
+    PROTOCOL_VERSION = "2024-11-05"
 
     module ErrorCodes
       NOT_INITIALIZED = -32_002

data/lib/mcp/delegator.rb

@@ -15,6 +15,6 @@ module MCP
       end
     end
 
-    delegate :name, :resource, :tool
+    delegate :name, :version, :resource, :resource_template, :tool
   end
 end

data/lib/mcp/server.rb

@@ -3,26 +3,34 @@
 require "json"
 require "English"
 require "uri"
+require_relative "constants"
 
 module MCP
   class Server
-    attr_accessor :name
+    attr_writer :name, :version
     attr_reader :initialized
 
-    def initialize(name:, version: VERSION)
+    def initialize(name:, version: "0.1.0")
       @name = name
       @version = version
       @app = App.new
       @initialized = false
-      @supported_protocol_versions = [PROTOCOL_VERSION]
+      @supported_protocol_versions = [Constants::PROTOCOL_VERSION]
     end
 
-    def name(value = nil) # standard:disable Lint/DuplicateMethods
+    def name(value = nil)
       return @name if value.nil?
 
       @name = value
     end
 
+    def version(value = nil)
+      return @version if value.nil?
+
+      @version = value
+      @supported_protocol_versions << value
+    end
+
     def tool(name, &block)
       @app.register_tool(name, &block)
     end
@@ -31,6 +39,10 @@ module MCP
       @app.register_resource(uri, &block)
     end
 
+    def resource_template(uri_template, &block)
+      @app.register_resource_template(uri_template, &block)
+    end
+
     def run
       while (input = $stdin.gets)
         process_input(input)
@@ -49,6 +61,10 @@ module MCP
       @app.list_resources[:resources]
     end
 
+    def list_resource_templates
+      @app.list_resource_templates[:resourceTemplates]
+    end
+
     def read_resource(uri)
       @app.read_resource(uri).dig(:contents, 0, :text)
     end
@@ -113,7 +129,7 @@ module MCP
         jsonrpc: MCP::Constants::JSON_RPC_VERSION,
         id: request[:id],
         result: {
-          protocolVersion: PROTOCOL_VERSION,
+          protocolVersion: Constants::PROTOCOL_VERSION,
           capabilities: {
             logging: {},
             prompts: {
@@ -165,6 +181,12 @@ module MCP
       success_response(request[:id], result)
     end
 
+    def handle_list_resources_templates(request)
+      cursor = request.dig(:params, :cursor)
+      result = @app.list_resource_templates(cursor:)
+      success_response(request[:id], result)
+    end
+
     def handle_read_resource(request)
       uri = request.dig(:params, :uri)
       result = @app.read_resource(uri)

data/lib/mcp/version.rb

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

data/lib/mcp.rb

@@ -8,6 +8,7 @@ require_relative "mcp/constants"
 require_relative "mcp/app"
 require_relative "mcp/server"
 require_relative "mcp/delegator"
+require_relative "mcp/client"
 
 module MCP
   class << self

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mcp-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - funwarioisii
 bindir: bin
 cert_chain: []
-date: 2025-02-14 00:00:00.000000000 Z
+date: 2025-03-04 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.
@@ -23,7 +23,9 @@ files:
 - lib/mcp.rb
 - lib/mcp/app.rb
 - lib/mcp/app/resource.rb
+- lib/mcp/app/resource_template.rb
 - lib/mcp/app/tool.rb
+- lib/mcp/client.rb
 - lib/mcp/constants.rb
 - lib/mcp/delegator.rb
 - lib/mcp/server.rb
@@ -49,7 +51,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.3
 specification_version: 4
 summary: A lightweight Ruby framework for implementing MCP (Model Context Protocol)
   servers