model-context-protocol-rb 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fffc016471f9e02baa6f9288860d65c7e9f4c9b573589d4abb31d824318b5ea1
-  data.tar.gz: 59b220de0291942879c34d7ca8cc47173b10d692a13e271c1458a59a7f2ff9fb
+  metadata.gz: aa9e49b895a1502fe4887f7e2089c24b69b980d9ac7c27754f97c52ad1541c7b
+  data.tar.gz: 92e343e66c69cd1e5ae9f9d8adb83567303a2aa5e48021b1dc964c172128426d
 SHA512:
-  metadata.gz: abda740fa404a916e3b30aa3b8e8c06e1731bb4e810b44b3d60f91742f92298fa66d2b4165f102679a49ee2246da6223ece27ad68302e96040148c2a83d00b3d
-  data.tar.gz: bc71626a2bec6b61a4e8e3de7a6ef8a44fb64a9e8d56f163734ff8a7e4ef42d05f552b0918f16e798ed15749b145fa901cbc4747a798ca9a274ef941b8f08e44
+  metadata.gz: bcbfcb95e17f7e0deaa368f7e2b3dc7915be124b4c98b2b86b8e94c446fe18bd7d9e8c7dbfb6e4301edf6b1ad28e491701fec85bbd31dcd2d79d8b91a3f0c8c1
+  data.tar.gz: 284e545287ecacb83d42c7a5f72dbe9b0f5ab359d50c9d0cfcde1eb2e00d9c330e9cce3b6bcb15e68fb48963e8778888ca3dbdf1fab5ac0a0d27d36f1ca4e6bd

data/.solargraph.yml

@@ -0,0 +1,13 @@
+include:
+  - "**/*.rb"
+exclude:
+  - spec/**/*
+  - ".bundle/**"
+require: []
+domains: []
+require_paths: []
+plugins:
+  - solargraph-standardrb
+reporters:
+  - standardrb
+max_files: 5000

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## [Unreleased]
 
+## [0.3.1] - 2025-04-04
+
+- Added support for environment variables to MCP servers (thanks @hmk):
+  - `require_environment_variable` method to specify required environment variables
+  - `set_environment_variable` method to programmatically set environment variables
+  - Environment variables accessible within tool/prompt/resource handlers
+- Added `respond_with` helper methods to simplify response creation:
+  - For tools: text, image, resource, and error responses
+  - For prompts: formatted message responses
+  - For resources: text and binary responses
+- Improved development tooling:
+  - Generated executable now loads all test classes
+  - Fixed test support classes for better compatibility with MCP inspector
+  - Organized test tools, prompts, and resources in dedicated directories
+
+## [0.3.0] - 2025-03-11
+
+- (Breaking) Replaced router initialization in favor of registry initialization during server configuration. The server now relies on the registry for auto-discovery of prompts, resources, and tools; this requires the use of SDK-provided builders to facilitate.
+- (Breaking) Implemented the use of `Data` objects across the implementation. As a result, responses from custom handlers must now respond with an object that responds to `serialized`.
+- Refactored the implementation to maintain separation of concerns and improve testability/maintainability.
+- Improved test coverage.
+- Improved development tooling.
+
 ## [0.2.0] - 2025-01-13
 
 - Added a basic, synchronous server implementation that routes requests to custom handlers.
@@ -8,6 +31,8 @@
 
 - Initial release
 
-[Unreleased]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.2.0...v0.3.0
 [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

@@ -2,38 +2,57 @@
 
 An implementation of the [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/specification/2024-11-05/) in Ruby.
 
+This SDK is experimental and subject to change. The initial focus is to implement MCP server support with the goal of providing a stable API by version `0.4`. MCP client support will follow. 
+
+You are welcome to contribute.
+
+TODO's:
+
+* [Completion](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/utilities/completion/)
+* [Logging](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/utilities/logging/)
+* [Pagination](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/utilities/pagination/)
+* [Prompt list changed notifications](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/#list-changed-notification)
+* [Resource list changed notifications](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/#list-changed-notification)
+* [Resource subscriptions](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/#subscriptions)
+* [Resource templates](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/#resource-templates)
+* [Tool list changed notifications](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/#list-changed-notification)
+
 ## Usage
 
-Include `model-context-protocol-rb` in your project.
+Include `model_context_protocol` in your project.
 
 ```ruby
-require 'model-context-protocol-rb'
+require 'model_context_protocol'
 ```
 
-# Building an MCP Server
+### Building an MCP Server
 
-Build a simple MCP server by routing methods to your custom handlers. Then, configure and run the server.
+Build a simple MCP server by registering your prompts, resources, and tools. Then, configure and run the server.
 
 ```ruby
 server = ModelContextProtocol::Server.new do |config|
-  config.name = "My MCP Server"
-  config.router = router
+  config.name = "MCP Development Server"
   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
+
+  # Environment Variables - https://modelcontextprotocol.io/docs/tools/debugging#environment-variables
+  # Require specific environment variables to be set
+  config.require_environment_variable("API_KEY")
+
+  # Set environment variables programmatically
+  config.set_environment_variable("DEBUG_MODE", "true")
+
+  config.registry = ModelContextProtocol::Server::Registry.new do
+    prompts list_changed: true do
+      register TestPrompt
     end
 
-    resources do
-      list Resource::List, broadcast_changes: true
-      read Resource::Read, allow_subscriptions: true
+    resources list_changed: true, subscribe: true do
+      register TestResource
     end
 
-    tools do
-      list Tool::List, broadcast_changes: true
-      call Tool::Call
+    tools list_changed: true do
+      register TestTool
     end
   end
 end
@@ -41,9 +60,236 @@ 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.
+Messages from the MCP client will be routed to the appropriate custom handler. This SDK provides several classes that should be used to build your handlers.
+
+#### ModelContextProtocol::Server::Prompt
+
+The `ModelContextProtocol::Server::Prompt` base class allows subclasses to define a prompt that the MCP client can use. Define the [appropriate metadata](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/) in the `with_metadata` block.
+
+Then implement the `call` method to build your prompt. Use the `respond_with` instance method to ensure your prompt responds with appropriately formatted response data.
+
+This is an example prompt that returns a properly formatted response:
+
+```ruby
+class TestPrompt < ModelContextProtocol::Server::Prompt
+  with_metadata do
+    {
+      name: "Test Prompt",
+      description: "A test prompt",
+      arguments: [
+        {
+          name: "message",
+          description: "The thing to do",
+          required: true
+        },
+        {
+          name: "other",
+          description: "Another thing to do",
+          required: false
+        }
+      ]
+    }
+  end
+
+  def call
+    messages = [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "Do this: #{params["message"]}"
+        }
+      }
+    ]
+
+    respond_with messages: messages
+  end
+end
+```
+
+#### ModelContextProtocol::Server::Resource
+
+The `ModelContextProtocol::Server::Resource` base class allows subclasses to define a resource that the MCP client can use. Define the [appropriate metadata](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/) in the `with_metadata` block.
+
+Then, implement the `call` method to build your resource. Use the `respond_with` instance method to ensure your resource responds with appropriately formatted response data.
+
+This is an example resource that returns a text response:
+
+```ruby
+class TestResource < ModelContextProtocol::Server::Resource
+  with_metadata do
+    {
+      name: "Test Resource",
+      description: "A test resource",
+      mime_type: "text/plain",
+      uri: "resource://test-resource"
+    }
+  end
+
+  def call
+    respond_with :text, text: "Here's the data"
+  end
+end
+```
+
+This is an example resource that returns binary data:
+
+```ruby
+class TestBinaryResource < ModelContextProtocol::Server::Resource
+  with_metadata do
+    {
+      name: "Project Logo",
+      description: "The logo for the project",
+      mime_type: "image/jpeg",
+      uri: "resource://project-logo"
+    }
+  end
+
+  def call
+    # In a real implementation, we would retrieve the binary resource
+    data = "dGVzdA=="
+    respond_with :binary, blob: data
+  end
+end
+```
+
+#### ModelContextProtocol::Server::Tool
+
+The `ModelContextProtocol::Server::Tool` base class allows subclasses to define a tool that the MCP client can use. Define the [appropriate metadata](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/) in the `with_metadata` block.
+
+Then implement the `call` method to build your tool. Use the `respond_with` instance method to ensure your tool responds with appropriately formatted response data.
+
+This is an example tool that returns a text response:
+
+```ruby
+class TestToolWithTextResponse < ModelContextProtocol::Server::Tool
+  with_metadata do
+    {
+      name: "double",
+      description: "Doubles the provided number",
+      inputSchema: {
+        type: "object",
+        properties: {
+          number: {
+            type: "string",
+          }
+        },
+        required: ["number"]
+      }
+    }
+  end
+
+  def call
+    number = params["number"].to_i
+    result = number * 2
+    respond_with :text, text: "#{number} doubled is #{result}"
+  end
+end
+```
+
+This is an example of a tool that returns an image:
+
+```ruby
+class TestToolWithImageResponse < ModelContextProtocol::Server::Tool
+  with_metadata do
+    {
+      name: "custom-chart-generator",
+      description: "Generates a chart in various formats",
+      inputSchema: {
+        type: "object",
+        properties: {
+          chart_type: {
+            type: "string",
+            description: "Type of chart (pie, bar, line)"
+          },
+          format: {
+            type: "string",
+            description: "Image format (jpg, svg, etc)"
+          }
+        },
+        required: ["chart_type", "format"]
+      }
+    }
+  end
+
+  def call
+    # Map format to mime type
+    mime_type = case params["format"].downcase
+    when "svg"
+      "image/svg+xml"
+    when "jpg", "jpeg"
+      "image/jpeg"
+    else
+      "image/png"
+    end
+
+    # In a real implementation, we would generate an actual chart
+    # This is a small valid base64 encoded string (represents "test")
+    chart_data = "dGVzdA=="
+    respond_with :image, data: chart_data, mime_type:
+  end
+end
+```
+
+If you don't provide a mime type, it will default to `image/png`.
 
-Your handler should return a valid JSONRPC 2.0 response.
+```ruby
+class TestToolWithImageResponseDefaultMimeType < ModelContextProtocol::Server::Tool
+  with_metadata do
+    {
+      name: "other-custom-chart-generator",
+      description: "Generates a chart",
+      inputSchema: {
+        type: "object",
+        properties: {
+          chart_type: {
+            type: "string",
+            description: "Type of chart (pie, bar, line)"
+          }
+        },
+        required: ["chart_type"]
+      }
+    }
+  end
+
+  def call
+    # In a real implementation, we would generate an actual chart
+    # This is a small valid base64 encoded string (represents "test")
+    chart_data = "dGVzdA=="
+    respond_with :image, data: chart_data
+  end
+end
+```
+
+This is an example of a tool that returns a resource response:
+
+```ruby
+class TestToolWithResourceResponse < ModelContextProtocol::Server::Tool
+  with_metadata do
+    {
+      name: "document-finder",
+      description: "Finds a the document with the given title",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: {
+            type: "string",
+            description: "The title of the document"
+          }
+        },
+        required: ["title"]
+      }
+    }
+  end
+
+  def call
+    title = params["title"].downcase
+    # In a real implementation, we would do a lookup to get the document data
+    document = "richtextdata"
+    respond_with :resource, uri: "resource://document/#{title}", text: document, mime_type: "application/rtf"
+  end
+end
+```
 
 ## Installation
 
@@ -67,7 +313,17 @@ gem install model-context-protocol-rb
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake  spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake  spec` to run the tests.
+
+Generate an executable that you can use for testing:
+
+```bash
+bundle exec rake mcp:generate_executable
+```
+
+This will generate a `bin/dev` executable you can provide to MCP clients.
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/Rakefile

@@ -7,4 +7,6 @@ RSpec::Core::RakeTask.new(:spec)
 
 require "standard/rake"
 
+Dir.glob("tasks/*.rake").each { |r| load r }
+
 task default: %i[spec standard]

data/lib/model_context_protocol/server/configuration.rb

@@ -0,0 +1,78 @@
+module ModelContextProtocol
+  class Server::Configuration
+    # Raised when configured with invalid name.
+    class InvalidServerNameError < StandardError; end
+
+    # Raised when configured with invalid version.
+    class InvalidServerVersionError < StandardError; end
+
+    # Raised when configured with invalid registry.
+    class InvalidRegistryError < StandardError; end
+
+    # Raised when a required environment variable is not set
+    class MissingRequiredEnvironmentVariable < StandardError; end
+
+    attr_accessor :enable_log, :name, :registry, :version
+
+    def logging_enabled?
+      enable_log || false
+    end
+
+    def validate!
+      raise InvalidServerNameError unless valid_name?
+      raise InvalidRegistryError unless valid_registry?
+      raise InvalidServerVersionError unless valid_version?
+
+      validate_environment_variables!
+    end
+
+    def environment_variables
+      @environment_variables ||= {}
+    end
+
+    def environment_variable(key)
+      environment_variables[key.to_s.upcase] || ENV[key.to_s.upcase] || nil
+    end
+
+    def require_environment_variable(key)
+      required_environment_variables << key.to_s.upcase
+    end
+
+    # Programatically set an environment variable - useful if an alternative
+    # to environment variables is used for security purposes. Despite being
+    # more like 'configuration variables', these are called environment variables
+    # to align with the Model Context Protocol terminology.
+    #
+    # see: https://modelcontextprotocol.io/docs/tools/debugging#environment-variables
+    #
+    # @param key [String] The key to set the environment variable for
+    # @param value [String] The value to set the environment variable to
+    def set_environment_variable(key, value)
+      environment_variables[key.to_s.upcase] = value
+    end
+
+    private
+
+    def required_environment_variables
+      @required_environment_variables ||= []
+    end
+
+    def validate_environment_variables!
+      required_environment_variables.each do |key|
+        raise MissingRequiredEnvironmentVariable, "#{key} is not set" unless environment_variable(key)
+      end
+    end
+
+    def valid_name?
+      name&.is_a?(String)
+    end
+
+    def valid_registry?
+      registry&.is_a?(ModelContextProtocol::Server::Registry)
+    end
+
+    def valid_version?
+      version&.is_a?(String)
+    end
+  end
+end

data/lib/model_context_protocol/server/prompt.rb

@@ -0,0 +1,72 @@
+module ModelContextProtocol
+  class Server::Prompt
+    attr_reader :params, :description
+
+    def initialize(params)
+      validate!(params)
+      @description = self.class.description
+      @params = params
+    end
+
+    def call
+      raise NotImplementedError, "Subclasses must implement the call method"
+    end
+
+    Response = Data.define(:messages, :prompt) do
+      def serialized
+        {description: prompt.description, messages:}
+      end
+    end
+    private_constant :Response
+
+    private def respond_with(messages:)
+      Response[messages:, prompt: self]
+    end
+
+    private def validate!(params = {})
+      arguments = self.class.arguments || []
+      required_args = arguments.select { |arg| arg[:required] }.map { |arg| arg[:name] }
+      valid_arg_names = arguments.map { |arg| arg[:name] }
+
+      missing_args = required_args - params.keys
+      unless missing_args.empty?
+        missing_args_list = missing_args.join(", ")
+        raise ArgumentError, "Missing required arguments: #{missing_args_list}"
+      end
+
+      extra_args = params.keys - valid_arg_names
+      unless extra_args.empty?
+        extra_args_list = extra_args.join(", ")
+        raise ArgumentError, "Unexpected arguments: #{extra_args_list}"
+      end
+    end
+
+    class << self
+      attr_reader :name, :description, :arguments
+
+      def with_metadata(&block)
+        metadata = instance_eval(&block)
+
+        @name = metadata[:name]
+        @description = metadata[:description]
+        @arguments = metadata[:arguments]
+      end
+
+      def inherited(subclass)
+        subclass.instance_variable_set(:@name, @name)
+        subclass.instance_variable_set(:@description, @description)
+        subclass.instance_variable_set(:@arguments, @arguments)
+      end
+
+      def call(params)
+        new(params).call
+      rescue ArgumentError => error
+        raise ModelContextProtocol::Server::ParameterValidationError, error.message
+      end
+
+      def metadata
+        {name: @name, description: @description, arguments: @arguments}
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/registry.rb

@@ -0,0 +1,102 @@
+module ModelContextProtocol
+  class Server::Registry
+    attr_reader :prompts_options, :resources_options, :tools_options
+
+    def self.new(&block)
+      registry = allocate
+      registry.send(:initialize)
+      registry.instance_eval(&block) if block
+      registry
+    end
+
+    def initialize
+      @prompts = []
+      @resources = []
+      @tools = []
+      @prompts_options = {}
+      @resources_options = {}
+      @tools_options = {}
+    end
+
+    def prompts(options = {}, &block)
+      @prompts_options = options
+      instance_eval(&block) if block
+    end
+
+    def resources(options = {}, &block)
+      @resources_options = options
+      instance_eval(&block) if block
+    end
+
+    def tools(options = {}, &block)
+      @tools_options = options
+      instance_eval(&block) if block
+    end
+
+    def register(klass)
+      metadata = klass.metadata
+      entry = {klass: klass}.merge(metadata)
+
+      case klass.ancestors
+      when ->(ancestors) { ancestors.include?(ModelContextProtocol::Server::Prompt) }
+        @prompts << entry
+      when ->(ancestors) { ancestors.include?(ModelContextProtocol::Server::Resource) }
+        @resources << entry
+      when ->(ancestors) { ancestors.include?(ModelContextProtocol::Server::Tool) }
+        @tools << entry
+      else
+        raise ArgumentError, "Unknown class type: #{klass}"
+      end
+    end
+
+    def find_prompt(name)
+      find_by_name(@prompts, name)
+    end
+
+    def find_resource(uri)
+      entry = @resources.find { |r| r[:uri] == uri }
+      entry ? entry[:klass] : nil
+    end
+
+    def find_tool(name)
+      find_by_name(@tools, name)
+    end
+
+    def prompts_data
+      PromptsData[prompts: @prompts.map { |entry| entry.except(:klass) }]
+    end
+
+    def resources_data
+      ResourcesData[resources: @resources.map { |entry| entry.except(:klass) }]
+    end
+
+    def tools_data
+      ToolsData[tools: @tools.map { |entry| entry.except(:klass) }]
+    end
+
+    private
+
+    PromptsData = Data.define(:prompts) do
+      def serialized
+        {prompts:}
+      end
+    end
+
+    ResourcesData = Data.define(:resources) do
+      def serialized
+        {resources:}
+      end
+    end
+
+    ToolsData = Data.define(:tools) do
+      def serialized
+        {tools:}
+      end
+    end
+
+    def find_by_name(collection, name)
+      entry = collection.find { |item| item[:name] == name }
+      entry ? entry[:klass] : nil
+    end
+  end
+end