model-context-protocol-rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9da483d392c30f83fc52293db51b1d807bc054889e6cd29d54d1dd96e9043ea6
-  data.tar.gz: 07f07aa7d469b674d57718ce3cb4d7abfffc64f1f0b4a159613dd6bfb13b4957
+  metadata.gz: fffc016471f9e02baa6f9288860d65c7e9f4c9b573589d4abb31d824318b5ea1
+  data.tar.gz: 59b220de0291942879c34d7ca8cc47173b10d692a13e271c1458a59a7f2ff9fb
 SHA512:
-  metadata.gz: 37f34d68b99ebf423c8500def91c848662820bdf3c8b295e443e8aaecd588ed030b2b76838e8e94b42f5e488e5bf85c4b9f5390cfd910676993309b6152344cb
-  data.tar.gz: 22b094b711874327767cddbf77c95a8f0ab35d23710656925cc8bcadab0aa6fcf01d602dedeb90d05d3fb7320b034150f85590e54539d4045392722426d2e967
+  metadata.gz: abda740fa404a916e3b30aa3b8e8c06e1731bb4e810b44b3d60f91742f92298fa66d2b4165f102679a49ee2246da6223ece27ad68302e96040148c2a83d00b3d
+  data.tar.gz: bc71626a2bec6b61a4e8e3de7a6ef8a44fb64a9e8d56f163734ff8a7e4ef42d05f552b0918f16e798ed15749b145fa901cbc4747a798ca9a274ef941b8f08e44

data/.standard.yml

@@ -1,3 +1,3 @@
 # For available configuration options, see:
 #   https://github.com/testdouble/standard
-ruby_version: 2.6
+ruby_version: 3.2

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-01-13
+
+- Added a basic, synchronous server implementation that routes requests to custom handlers.
+
 ## [0.1.0] - 2025-01-10
 
 - Initial release
+
+[Unreleased]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/dickdavis/model-context-protocol-rb/releases/tag/v0.1.0

data/README.md

@@ -10,7 +10,40 @@ Include `model-context-protocol-rb` in your project.
 require 'model-context-protocol-rb'
 ```
 
-TODO: Write usage instructions here once implementation lands
+# Building an MCP Server
+
+Build a simple MCP server by routing methods to your custom handlers. Then, configure and run the server.
+
+```ruby
+server = ModelContextProtocol::Server.new do |config|
+  config.name = "My MCP Server"
+  config.router = router
+  config.version = "1.0.0"
+  config.enable_log = true
+  config.router = ModelContextProtocol::Router.new do
+    prompts do
+      list Prompt::List, broadcast_changes: true
+      get Prompt::Get
+    end
+
+    resources do
+      list Resource::List, broadcast_changes: true
+      read Resource::Read, allow_subscriptions: true
+    end
+
+    tools do
+      list Tool::List, broadcast_changes: true
+      call Tool::Call
+    end
+  end
+end
+
+server.start
+```
+
+Messages from the MCP client will be routed to the appropriate custom handler. Your customer handler must respond to `call`; the router will pass the message to the handler as an argument.
+
+Your handler should return a valid JSONRPC 2.0 response.
 
 ## Installation
 

data/lib/model_context_protocol/server/router/base_map.rb

@@ -0,0 +1,22 @@
+module ModelContextProtocol
+  class Server
+    class Router
+      ##
+      # Base class for route maps.
+      class BaseMap
+        def initialize(routes)
+          @routes = routes
+        end
+
+        private
+
+        def register(method, handler, **options)
+          @routes[method] = {
+            handler: handler,
+            options: options
+          }
+        end
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/router/prompts_map.rb

@@ -0,0 +1,17 @@
+module ModelContextProtocol
+  class Server
+    class Router
+      ##
+      # Maps prompt operations to handlers.
+      class PromptsMap < BaseMap
+        def list(handler, broadcast_changes: false)
+          register("prompts/list", handler, broadcast_changes:)
+        end
+
+        def get(handler)
+          register("prompts/get", handler)
+        end
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/router/resources_map.rb

@@ -0,0 +1,17 @@
+module ModelContextProtocol
+  class Server
+    class Router
+      ##
+      # Maps resource operations to handlers.
+      class ResourcesMap < BaseMap
+        def list(handler, broadcast_changes: false)
+          register("resources/list", handler, broadcast_changes:)
+        end
+
+        def read(handler, allow_subscriptions: false)
+          register("resources/read", handler, allow_subscriptions:)
+        end
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/router/tools_map.rb

@@ -0,0 +1,17 @@
+module ModelContextProtocol
+  class Server
+    class Router
+      ##
+      # Maps tool operations to handlers.
+      class ToolsMap < BaseMap
+        def list(handler, broadcast_changes: false)
+          register("tools/list", handler, broadcast_changes:)
+        end
+
+        def call(handler)
+          register("tools/call", handler)
+        end
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/router.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Server
+    class Router
+      attr_accessor :server
+
+      def self.new(&block)
+        router = allocate
+        router.send(:initialize)
+        router.instance_eval(&block) if block
+        router
+      end
+
+      def initialize
+        @routes = {}
+        register_protocol_routes
+      end
+
+      def prompts(&block)
+        PromptsMap.new(@routes).instance_eval(&block)
+      end
+
+      def resources(&block)
+        ResourcesMap.new(@routes).instance_eval(&block)
+      end
+
+      def tools(&block)
+        ToolsMap.new(@routes).instance_eval(&block)
+      end
+
+      def route(message)
+        handler_config = @routes[message["method"]]
+        return nil unless handler_config
+
+        handler_config[:handler].call(message)
+      end
+
+      private
+
+      def server_info
+        if server&.configuration
+          {
+            name: server.configuration.name,
+            version: server.configuration.version
+          }
+        else
+          {name: "mcp-server", version: "1.0.0"}
+        end
+      end
+
+      def register_protocol_routes
+        register("initialize") do |_message|
+          {
+            protocolVersion: ModelContextProtocol::Server::PROTOCOL_VERSION,
+            capabilities: build_capabilities,
+            serverInfo: server_info
+          }
+        end
+
+        register("notifications/initialized") do |_message|
+          nil # No-op notification handler
+        end
+
+        register("ping") do |_message|
+          {} # Simple pong response
+        end
+      end
+
+      def register(method, handler = nil, **options, &block)
+        @routes[method] = {
+          handler: block || handler,
+          options: options
+        }
+      end
+
+      def build_capabilities
+        {
+          prompts: has_prompt_routes? ? {broadcast_changes: prompt_broadcasts_changes?} : nil,
+          resources: has_resource_routes? ? {
+            broadcast_changes: resource_broadcasts_changes?,
+            subscribe: resource_allows_subscriptions?
+          } : nil,
+          tools: has_tool_routes? ? {broadcast_changes: tool_broadcasts_changes?} : nil
+        }.compact
+      end
+
+      def has_prompt_routes?
+        @routes.key?("prompts/list") || @routes.key?("prompts/get")
+      end
+
+      def prompt_broadcasts_changes?
+        @routes.dig("prompts/list", :options, :broadcast_changes)
+      end
+
+      def has_resource_routes?
+        @routes.key?("resources/list") || @routes.key?("resources/read")
+      end
+
+      def resource_broadcasts_changes?
+        @routes.dig("resources/list", :options, :broadcast_changes)
+      end
+
+      def resource_allows_subscriptions?
+        @routes.dig("resources/read", :options, :allow_subscriptions)
+      end
+
+      def has_tool_routes?
+        @routes.key?("tools/list") || @routes.key?("tools/call")
+      end
+
+      def tool_broadcasts_changes?
+        @routes.dig("tools/list", :options, :broadcast_changes)
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server.rb

@@ -0,0 +1,81 @@
+require "json"
+
+module ModelContextProtocol
+  class Server
+    class Configuration
+      attr_accessor :enable_log, :name, :router, :version
+
+      def logging_enabled?
+        enable_log || false
+      end
+
+      def validate!
+        raise InvalidServerNameError unless valid_name?
+        raise InvalidRouterError unless valid_router?
+        raise InvalidServerVersionError unless valid_version?
+      end
+
+      private
+
+      def valid_name?
+        true
+      end
+
+      def valid_router?
+        true
+      end
+
+      def valid_version?
+        true
+      end
+    end
+
+    PROTOCOL_VERSION = "2024-11-05".freeze
+
+    attr_reader :configuration
+
+    def initialize
+      @configuration = Configuration.new
+      yield(@configuration) if block_given?
+      @configuration.router.server = self if @configuration.router
+    end
+
+    def start
+      log("Server starting")
+
+      configuration.validate!
+
+      loop do
+        line = $stdin.gets
+        break unless line
+
+        message = JSON.parse(line.chomp)
+        log("Received message: #{message.inspect}")
+
+        response = configuration.router.route(message)
+        send_response(message["id"], response) if response
+      end
+    rescue => e
+      log("Error: #{e.message}")
+      log(e.backtrace)
+    end
+
+    private
+
+    def log(output)
+      warn(output) if configuration.logging_enabled?
+    end
+
+    def send_response(id, result)
+      return unless result
+
+      response = {
+        jsonrpc: "2.0",
+        id: id,
+        result: result
+      }
+      $stdout.puts(JSON.generate(response))
+      $stdout.flush
+    end
+  end
+end

data/lib/model_context_protocol/version.rb

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

data/lib/model_context_protocol.rb

@@ -5,5 +5,4 @@ Dir[File.join(__dir__, "model_context_protocol/", "**", "*.rb")].sort.each { |fi
 ##
 # Top-level namespace
 module ModelContextProtocol
-  # TODO: everything
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: model-context-protocol-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Dick Davis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-11 00:00:00.000000000 Z
+date: 2025-01-14 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -26,6 +26,13 @@ files:
 - README.md
 - Rakefile
 - lib/model_context_protocol.rb
+- lib/model_context_protocol/server.rb
+- lib/model_context_protocol/server/router.rb
+- lib/model_context_protocol/server/router/base_map.rb
+- lib/model_context_protocol/server/router/prompts_map.rb
+- lib/model_context_protocol/server/router/protocol_map.rb
+- lib/model_context_protocol/server/router/resources_map.rb
+- lib/model_context_protocol/server/router/tools_map.rb
 - lib/model_context_protocol/version.rb
 homepage: https://github.com/dickdavis/model-context-protocol-rb
 licenses:
@@ -43,7 +50,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.2.4
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="