model-context-protocol-rb 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0127f55c18cd5b2886b93b9f939b2b1358b14d2700e1f9194b26e5f43935101f
-  data.tar.gz: c0ce5f9bc0891e5b20fb3b30acee6c6dee0ebc2d412fac31078839fcf94f0010
+  metadata.gz: aa9e49b895a1502fe4887f7e2089c24b69b980d9ac7c27754f97c52ad1541c7b
+  data.tar.gz: 92e343e66c69cd1e5ae9f9d8adb83567303a2aa5e48021b1dc964c172128426d
 SHA512:
-  metadata.gz: f17f3371c5c07b264b2a495fbc8b3e47fc8d18993cc3bd64f9fe91f4475720dde9ec536f266af1f22e7c7eb30ffd0bc4e5680f0a53f8a39c08d2eff034206e9f
-  data.tar.gz: 564433c1386b063560c17502b7346ae7db2cc523c47ab4ecd62fb986c51fba178432331a4ceed699ec9469c8d63e719acddce669c03d68969b8fc7086a85e640
+  metadata.gz: bcbfcb95e17f7e0deaa368f7e2b3dc7915be124b4c98b2b86b8e94c446fe18bd7d9e8c7dbfb6e4301edf6b1ad28e491701fec85bbd31dcd2d79d8b91a3f0c8c1
+  data.tar.gz: 284e545287ecacb83d42c7a5f72dbe9b0f5ab359d50c9d0cfcde1eb2e00d9c330e9cce3b6bcb15e68fb48963e8778888ca3dbdf1fab5ac0a0d27d36f1ca4e6bd

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [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.
@@ -16,7 +31,8 @@
 
 - Initial release
 
-[Unreleased]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.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

@@ -19,21 +19,29 @@ TODO's:
 
 ## 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
 
-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 = "MCP Development Server"
   config.version = "1.0.0"
   config.enable_log = true
+
+  # 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
@@ -56,7 +64,11 @@ Messages from the MCP client will be routed to the appropriate custom handler. T
 
 #### ModelContextProtocol::Server::Prompt
 
-The `Prompt` class is used 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, and then implement the call method to build your prompt. The `call` method should return a `Response` data object.
+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
@@ -90,14 +102,18 @@ class TestPrompt < ModelContextProtocol::Server::Prompt
       }
     ]
 
-    Response[messages:, prompt: self]
+    respond_with messages: messages
   end
 end
 ```
 
 #### ModelContextProtocol::Server::Resource
 
-The `Resource` class is used 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, and then implement the 'call' method to build your prompt. The `call` method should return a `TextResponse` or a `BinaryResponse` data object.
+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
@@ -111,35 +127,166 @@ class TestResource < ModelContextProtocol::Server::Resource
   end
 
   def call
-    TextResponse[resource: self, text: "Here's the data"]
+    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 `Tool` class is used 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, and then implement the `call` method to build your prompt. The `call` method should return a `TextResponse`, `ImageResponse`, `ResourceResponse`, or `ToolErrorResponse` data object.
+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 TestTool < ModelContextProtocol::Server::Tool
+class TestToolWithTextResponse < ModelContextProtocol::Server::Tool
   with_metadata do
     {
-      name: "test-tool",
-      description: "A test tool",
+      name: "double",
+      description: "Doubles the provided number",
       inputSchema: {
         type: "object",
         properties: {
-          message: {
-            type: "string"
+          number: {
+            type: "string",
           }
         },
-        required: ["message"]
+        required: ["number"]
       }
     }
   end
 
   def call
-    TextResponse[text: "You said: #{params["message"]}"]
+    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`.
+
+```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
 ```
@@ -166,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

@@ -9,6 +9,9 @@ module ModelContextProtocol
     # 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?
@@ -19,10 +22,47 @@ module ModelContextProtocol
       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

data/lib/model_context_protocol/server/prompt.rb

@@ -2,12 +2,6 @@ module ModelContextProtocol
   class Server::Prompt
     attr_reader :params, :description
 
-    Response = Data.define(:messages, :prompt) do
-      def serialized
-        {description: prompt.description, messages:}
-      end
-    end
-
     def initialize(params)
       validate!(params)
       @description = self.class.description
@@ -18,6 +12,17 @@ module ModelContextProtocol
       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] }

data/lib/model_context_protocol/server/resource.rb

@@ -2,25 +2,38 @@ module ModelContextProtocol
   class Server::Resource
     attr_reader :mime_type, :uri
 
+    def initialize
+      @mime_type = self.class.mime_type
+      @uri = self.class.uri
+    end
+
+    def call
+      raise NotImplementedError, "Subclasses must implement the call method"
+    end
+
     TextResponse = Data.define(:resource, :text) do
       def serialized
         {contents: [{mimeType: resource.mime_type, text:, uri: resource.uri}]}
       end
     end
+    private_constant :TextResponse
 
     BinaryResponse = Data.define(:blob, :resource) do
       def serialized
         {contents: [{blob:, mimeType: resource.mime_type, uri: resource.uri}]}
       end
     end
+    private_constant :BinaryResponse
 
-    def initialize
-      @mime_type = self.class.mime_type
-      @uri = self.class.uri
-    end
-
-    def call
-      raise NotImplementedError, "Subclasses must implement the call method"
+    private def respond_with(type, **options)
+      case [type, options]
+      in [:text, {text:}]
+        TextResponse[resource: self, text:]
+      in [:binary, {blob:}]
+        BinaryResponse[blob:, resource: self]
+      else
+        raise ModelContextProtocol::Server::ResponseArgumentsError, "Invalid arguments: #{type}, #{options}"
+      end
     end
 
     class << self

data/lib/model_context_protocol/server/router.rb

@@ -3,8 +3,9 @@ module ModelContextProtocol
     # Raised when an invalid method is provided.
     class MethodNotFoundError < StandardError; end
 
-    def initialize
+    def initialize(configuration: nil)
       @handlers = {}
+      @configuration = configuration
     end
 
     def map(method, &handler)
@@ -16,7 +17,20 @@ module ModelContextProtocol
       handler = @handlers[method]
       raise MethodNotFoundError, "Method not found: #{method}" unless handler
 
-      handler.call(message)
+      with_environment(@configuration&.environment_variables) do
+        handler.call(message)
+      end
+    end
+
+    private
+
+    def with_environment(vars)
+      original = ENV.to_h
+      vars&.each { |key, value| ENV[key] = value }
+      yield
+    ensure
+      ENV.clear
+      original.each { |key, value| ENV[key] = value }
     end
   end
 end

data/lib/model_context_protocol/server/tool.rb

@@ -4,11 +4,21 @@ module ModelContextProtocol
   class Server::Tool
     attr_reader :params
 
+    def initialize(params)
+      validate!(params)
+      @params = params
+    end
+
+    def call
+      raise NotImplementedError, "Subclasses must implement the call method"
+    end
+
     TextResponse = Data.define(:text) do
       def serialized
         {content: [{type: "text", text:}], isError: false}
       end
     end
+    private_constant :TextResponse
 
     ImageResponse = Data.define(:data, :mime_type) do
       def initialize(data:, mime_type: "image/png")
@@ -19,6 +29,7 @@ module ModelContextProtocol
         {content: [{type: "image", data:, mimeType: mime_type}], isError: false}
       end
     end
+    private_constant :ImageResponse
 
     ResourceResponse = Data.define(:uri, :text, :mime_type) do
       def initialize(uri:, text:, mime_type: "text/plain")
@@ -29,20 +40,32 @@ module ModelContextProtocol
         {content: [{type: "resource", resource: {uri:, mimeType: mime_type, text:}}], isError: false}
       end
     end
+    private_constant :ResourceResponse
 
     ToolErrorResponse = Data.define(:text) do
       def serialized
         {content: [{type: "text", text:}], isError: true}
       end
     end
-
-    def initialize(params)
-      validate!(params)
-      @params = params
-    end
-
-    def call
-      raise NotImplementedError, "Subclasses must implement the call method"
+    private_constant :ToolErrorResponse
+
+    private def respond_with(type, **options)
+      case [type, options]
+      in [:text, {text:}]
+        TextResponse[text:]
+      in [:image, {data:, mime_type:}]
+        ImageResponse[data:, mime_type:]
+      in [:image, {data:}]
+        ImageResponse[data:]
+      in [:resource, {mime_type:, text:, uri:}]
+        ResourceResponse[mime_type:, text:, uri:]
+      in [:resource, {text:, uri:}]
+        ResourceResponse[text:, uri:]
+      in [:error, {text:}]
+        ToolErrorResponse[text:]
+      else
+        raise ModelContextProtocol::Server::ResponseArgumentsError, "Invalid arguments: #{type}, #{options}"
+      end
     end
 
     private def validate!(params)
@@ -68,8 +91,10 @@ module ModelContextProtocol
 
       def call(params)
         new(params).call
-      rescue JSON::Schema::ValidationError => error
-        raise ModelContextProtocol::Server::ParameterValidationError, error.message
+      rescue JSON::Schema::ValidationError => validation_error
+        raise ModelContextProtocol::Server::ParameterValidationError, validation_error.message
+      rescue ModelContextProtocol::Server::ResponseArgumentsError => response_arguments_error
+        raise response_arguments_error
       rescue => error
         ToolErrorResponse[text: error.message]
       end

data/lib/model_context_protocol/server.rb

@@ -2,6 +2,9 @@ require "logger"
 
 module ModelContextProtocol
   class Server
+    # Raised when invalid response arguments are provided.
+    class ResponseArgumentsError < StandardError; end
+
     # Raised when invalid parameters are provided.
     class ParameterValidationError < StandardError; end
 
@@ -10,7 +13,7 @@ module ModelContextProtocol
     def initialize
       @configuration = Configuration.new
       yield(@configuration) if block_given?
-      @router = Router.new
+      @router = Router.new(configuration:)
       map_handlers
     end
 

data/lib/model_context_protocol/version.rb

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

data/tasks/mcp.rake

@@ -0,0 +1,62 @@
+require "fileutils"
+
+namespace :mcp do
+  desc "Generate the development server executable with the correct Ruby path"
+  task :generate_executable do
+    destination_path = "bin/dev"
+    template_path = File.expand_path("templates/dev.erb", __dir__)
+
+    # Create directory if it doesn't exist
+    FileUtils.mkdir_p(File.dirname(destination_path))
+
+    # Get the Ruby path
+    ruby_path = detect_ruby_path
+
+    # Read and process the template
+    template = File.read(template_path)
+    content = template.gsub("<%= @ruby_path %>", ruby_path)
+
+    # Write the executable
+    File.write(destination_path, content)
+
+    # Set permissions
+    FileUtils.chmod(0o755, destination_path)
+
+    # Show success message
+    puts "\nCreated executable at: #{File.expand_path(destination_path)}"
+    puts "Using Ruby path: #{ruby_path}"
+  end
+
+  def detect_ruby_path
+    # Get Ruby version from project config
+    ruby_version = get_project_ruby_version
+
+    if ruby_version && ruby_version.strip != ""
+      # Find the absolute path to the Ruby executable via ASDF
+      asdf_ruby_path = `asdf where ruby #{ruby_version}`.strip
+
+      if asdf_ruby_path && !asdf_ruby_path.empty? && File.directory?(asdf_ruby_path)
+        return File.join(asdf_ruby_path, "bin", "ruby")
+      end
+    end
+
+    # Fallback to current Ruby
+    `which ruby`.strip
+  end
+
+  def get_project_ruby_version
+    # Try ASDF first
+    if File.exist?(".tool-versions")
+      content = File.read(".tool-versions")
+      ruby_line = content.lines.find { |line| line.start_with?("ruby ") }
+      return ruby_line.split[1].strip if ruby_line
+    end
+
+    # Try .ruby-version file
+    if File.exist?(".ruby-version")
+      return File.read(".ruby-version").strip
+    end
+
+    nil
+  end
+end

data/tasks/templates/dev.erb

@@ -0,0 +1,33 @@
+#!/usr/bin/env <%= @ruby_path %>
+
+require "bundler/setup"
+require_relative "../lib/model_context_protocol"
+
+Dir[File.join(__dir__, "../spec/support/**/*.rb")].each { |file| require file }
+
+server = ModelContextProtocol::Server.new do |config|
+  config.name = "MCP Development Server"
+  config.version = "1.0.0"
+  config.enable_log = true
+  config.registry = ModelContextProtocol::Server::Registry.new do
+    prompts list_changed: true do
+      register TestPrompt
+    end
+
+    resources list_changed: true, subscribe: true do
+      register TestResource
+      register TestBinaryResource
+    end
+
+    tools list_changed: true do
+      register TestToolWithTextResponse
+      register TestToolWithImageResponse
+      register TestToolWithImageResponseDefaultMimeType
+      register TestToolWithResourceResponse
+      register TestToolWithResourceResponseDefaultMimeType
+      register TestToolWithToolErrorResponse
+    end
+  end
+end
+
+server.start

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: model-context-protocol-rb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Dick Davis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-11 00:00:00.000000000 Z
+date: 2025-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json-schema
@@ -50,6 +50,8 @@ files:
 - lib/model_context_protocol/server/stdio_transport.rb
 - lib/model_context_protocol/server/tool.rb
 - lib/model_context_protocol/version.rb
+- tasks/mcp.rake
+- tasks/templates/dev.erb
 homepage: https://github.com/dickdavis/model-context-protocol-rb
 licenses:
 - MIT