model-context-protocol-rb 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0127f55c18cd5b2886b93b9f939b2b1358b14d2700e1f9194b26e5f43935101f
-  data.tar.gz: c0ce5f9bc0891e5b20fb3b30acee6c6dee0ebc2d412fac31078839fcf94f0010
+  metadata.gz: 99ee11ebae0c9c984a15954b386e89489f6715a1d371b288ece0438d066436d7
+  data.tar.gz: cdf41e8742941e9a0a41c714127d02f5a189d901a95a35e6f61a16f1f7b8a704
 SHA512:
-  metadata.gz: f17f3371c5c07b264b2a495fbc8b3e47fc8d18993cc3bd64f9fe91f4475720dde9ec536f266af1f22e7c7eb30ffd0bc4e5680f0a53f8a39c08d2eff034206e9f
-  data.tar.gz: 564433c1386b063560c17502b7346ae7db2cc523c47ab4ecd62fb986c51fba178432331a4ceed699ec9469c8d63e719acddce669c03d68969b8fc7086a85e640
+  metadata.gz: aad64bd6e42b2ecea2b742bb23b902ea1bfae3e77cffc5009b0a83712df7efac417b680bb460649bb73fff31d2d554d33a17d6fe96adb35f3cc9d0addbbcf9be
+  data.tar.gz: 6fa834a1c2bf4494748474dc26a29bede650b1a1913c7c543a7c195fd24fe99eda5f1610c40a63067f454b50f669b1fb47030e106fa6ba80cbde522bccfb9518

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.3.2] - 2025-05-10
+
+- Added resource template support.
+- Added completion support for prompts and resources.
+- Improved metadata definition for prompts, resources, and tools using simple DSL.
+
+## [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 +37,9 @@
 
 - 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.2...HEAD
+[0.3.1]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.1...v0.3.2
+[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

@@ -8,32 +8,37 @@ 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
 
-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, resource templates, 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
@@ -43,6 +48,10 @@ server = ModelContextProtocol::Server.new do |config|
       register TestResource
     end
 
+    resource_templates do
+      register TestResourceTemplate
+    end
+
     tools list_changed: true do
       register TestTool
     end
@@ -54,29 +63,34 @@ server.start
 
 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
+#### Prompts
+
+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.
+
+Define any arguments using the `with_argument` block. You can mark an argument as required, and you can optionally provide the class name of a service object that provides completions. See [Completions](#completions) for more information.
+
+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.
 
-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.
+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
-        }
-      ]
-    }
+    name "test_prompt"
+    description "A test prompt"
+  end
+
+  with_argument do
+    name "message"
+    description "The thing to do"
+    required true
+    completion TestCompletion
+  end
+
+  with_argument do
+    name "other"
+    description "Another thing to do"
+    required false
   end
 
   def call
@@ -90,56 +104,238 @@ class TestPrompt < ModelContextProtocol::Server::Prompt
       }
     ]
 
-    Response[messages:, prompt: self]
+    respond_with messages: messages
   end
 end
 ```
 
-#### ModelContextProtocol::Server::Resource
+#### Resources
 
-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
   with_metadata do
-    {
-      name: "Test Resource",
-      description: "A test resource",
-      mime_type: "text/plain",
-      uri: "resource://test-resource"
-    }
+    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
+```
+
+#### Resource Templates
 
+The `ModelContextProtocol::Server::ResourceTemplate` base class allows subclasses to define a resource template that the MCP client can use. Define the [appropriate metadata](https://modelcontextprotocol.io/specification/2024-11-05/server/resources#resource-templates) in the `with_metadata` block.
+
+This is an example resource template that provides a completion for a parameter of the URI template:
+
+```ruby
+class TestResourceTemplateCompletion < ModelContextProtocol::Server::Completion
   def call
-    TextResponse[resource: self, text: "Here's the data"]
+    hints = {
+      "name" => ["test-resource", "project-logo"]
+    }
+    values = hints[argument_name].grep(/#{argument_value}/)
+
+    respond_with values:
+  end
+end
+
+class TestResourceTemplate < ModelContextProtocol::Server::ResourceTemplate
+  with_metadata do
+    name "Test Resource Template"
+    description "A test resource template"
+    mime_type "text/plain"
+    uri_template "resource://{name}" do
+      completion :name, TestResourceTemplateCompletion
+    end
   end
 end
 ```
 
-#### ModelContextProtocol::Server::Tool
+#### Tools
+
+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.
 
-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.
+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",
-      inputSchema: {
+    name "double"
+    description "Doubles the provided number"
+    input_schema do
+      {
         type: "object",
         properties: {
-          message: {
+          number: {
             type: "string"
           }
         },
-        required: ["message"]
+        required: ["number"]
       }
-    }
+    end
+  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"
+    input_schema do
+      {
+        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
+  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"
+    input_schema do
+      {
+        type: "object",
+        properties: {
+          chart_type: {
+            type: "string",
+            description: "Type of chart (pie, bar, line)"
+          }
+        },
+        required: ["chart_type"]
+      }
+    end
+  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"
+    input_schema do
+      {
+        type: "object",
+        properties: {
+          title: {
+            type: "string",
+            description: "The title of the document"
+          }
+        },
+        required: ["title"]
+      }
+    end
+  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
+```
+
+### Completions
+
+The `ModelContextProtocol::Server::Completion` base class allows subclasses to define a completion that the MCP client can use to obtain hints or suggestions for arguments to prompts and resources.
 
+implement the `call` method to build your completion. Use the `respond_with` instance method to ensure your completion responds with appropriately formatted response data.
+
+This is an example completion that returns an array of values in the response:
+
+```ruby
+class TestCompletion < ModelContextProtocol::Server::Completion
   def call
-    TextResponse[text: "You said: #{params["message"]}"]
+    hints = {
+      "message" => ["hello", "world", "foo", "bar"]
+    }
+    values = hints[argument_name].grep(/#{argument_value}/)
+
+    respond_with values:
   end
 end
 ```
@@ -166,7 +362,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/completion.rb

@@ -0,0 +1,45 @@
+module ModelContextProtocol
+  class Server::Completion
+    attr_reader :argument_name, :argument_value
+
+    def initialize(argument_name, argument_value)
+      @argument_name = argument_name
+      @argument_value = argument_value
+    end
+
+    def call
+      raise NotImplementedError, "Subclasses must implement the call method"
+    end
+
+    def self.call(...)
+      new(...).call
+    end
+
+    private
+
+    Response = Data.define(:values, :total, :hasMore) do
+      def serialized
+        {completion: {values:, total:, hasMore:}}
+      end
+    end
+
+    def respond_with(values:)
+      values_to_return = values.take(100)
+      total = values.size
+      has_more = values_to_return.size != total
+      Response[values:, total:, hasMore: has_more]
+    end
+  end
+
+  class Server::NullCompletion
+    Response = Data.define(:values, :total, :hasMore) do
+      def serialized
+        {completion: {values:, total:, hasMore:}}
+      end
+    end
+
+    def self.call(_argument_name, _argument_value)
+      Response[values: [], total: 0, hasMore: false]
+    end
+  end
+end

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

@@ -1,16 +1,9 @@
 module ModelContextProtocol
   class Server::Prompt
-    attr_reader :params, :description
-
-    Response = Data.define(:messages, :prompt) do
-      def serialized
-        {description: prompt.description, messages:}
-      end
-    end
+    attr_reader :params
 
     def initialize(params)
       validate!(params)
-      @description = self.class.description
       @params = params
     end
 
@@ -18,6 +11,17 @@ module ModelContextProtocol
       raise NotImplementedError, "Subclasses must implement the call method"
     end
 
+    Response = Data.define(:messages, :description) do
+      def serialized
+        {description:, messages:}
+      end
+    end
+    private_constant :Response
+
+    private def respond_with(messages:)
+      Response[messages:, description: self.class.description]
+    end
+
     private def validate!(params = {})
       arguments = self.class.arguments || []
       required_args = arguments.select { |arg| arg[:required] }.map { |arg| arg[:name] }
@@ -40,17 +44,33 @@ module ModelContextProtocol
       attr_reader :name, :description, :arguments
 
       def with_metadata(&block)
-        metadata = instance_eval(&block)
+        @arguments ||= []
+
+        metadata_dsl = MetadataDSL.new
+        metadata_dsl.instance_eval(&block)
+
+        @name = metadata_dsl.name
+        @description = metadata_dsl.description
+      end
+
+      def with_argument(&block)
+        @arguments ||= []
 
-        @name = metadata[:name]
-        @description = metadata[:description]
-        @arguments = metadata[:arguments]
+        argument_dsl = ArgumentDSL.new
+        argument_dsl.instance_eval(&block)
+
+        @arguments << {
+          name: argument_dsl.name,
+          description: argument_dsl.description,
+          required: argument_dsl.required,
+          completion: argument_dsl.completion
+        }
       end
 
       def inherited(subclass)
         subclass.instance_variable_set(:@name, @name)
         subclass.instance_variable_set(:@description, @description)
-        subclass.instance_variable_set(:@arguments, @arguments)
+        subclass.instance_variable_set(:@arguments, @arguments&.dup)
       end
 
       def call(params)
@@ -62,6 +82,46 @@ module ModelContextProtocol
       def metadata
         {name: @name, description: @description, arguments: @arguments}
       end
+
+      def complete_for(arg_name, value)
+        arg = @arguments&.find { |a| a[:name] == arg_name.to_s }
+        completion = (arg && arg[:completion]) ? arg[:completion] : ModelContextProtocol::Server::NullCompletion
+        completion.call(arg_name.to_s, value)
+      end
+    end
+
+    class MetadataDSL
+      def name(value = nil)
+        @name = value if value
+        @name
+      end
+
+      def description(value = nil)
+        @description = value if value
+        @description
+      end
+    end
+
+    class ArgumentDSL
+      def name(value = nil)
+        @name = value if value
+        @name
+      end
+
+      def description(value = nil)
+        @description = value if value
+        @description
+      end
+
+      def required(value = nil)
+        @required = value unless value.nil?
+        @required
+      end
+
+      def completion(klass = nil)
+        @completion = klass unless klass.nil?
+        @completion
+      end
     end
   end
 end

data/lib/model_context_protocol/server/registry.rb

@@ -12,6 +12,7 @@ module ModelContextProtocol
     def initialize
       @prompts = []
       @resources = []
+      @resource_templates = []
       @tools = []
       @prompts_options = {}
       @resources_options = {}
@@ -28,6 +29,10 @@ module ModelContextProtocol
       instance_eval(&block) if block
     end
 
+    def resource_templates(&block)
+      instance_eval(&block) if block
+    end
+
     def tools(options = {}, &block)
       @tools_options = options
       instance_eval(&block) if block
@@ -42,6 +47,8 @@ module ModelContextProtocol
         @prompts << entry
       when ->(ancestors) { ancestors.include?(ModelContextProtocol::Server::Resource) }
         @resources << entry
+      when ->(ancestors) { ancestors.include?(ModelContextProtocol::Server::ResourceTemplate) }
+        @resource_templates << entry
       when ->(ancestors) { ancestors.include?(ModelContextProtocol::Server::Tool) }
         @tools << entry
       else
@@ -58,6 +65,11 @@ module ModelContextProtocol
       entry ? entry[:klass] : nil
     end
 
+    def find_resource_template(uri)
+      entry = @resource_templates.find { |r| uri == r[:uriTemplate] }
+      entry ? entry[:klass] : nil
+    end
+
     def find_tool(name)
       find_by_name(@tools, name)
     end
@@ -70,6 +82,10 @@ module ModelContextProtocol
       ResourcesData[resources: @resources.map { |entry| entry.except(:klass) }]
     end
 
+    def resource_templates_data
+      ResourceTemplatesData[resource_templates: @resource_templates.map { |entry| entry.except(:klass, :completions) }]
+    end
+
     def tools_data
       ToolsData[tools: @tools.map { |entry| entry.except(:klass) }]
     end
@@ -88,6 +104,12 @@ module ModelContextProtocol
       end
     end
 
+    ResourceTemplatesData = Data.define(:resource_templates) do
+      def serialized
+        {resourceTemplates: resource_templates}
+      end
+    end
+
     ToolsData = Data.define(:tools) do
       def serialized
         {tools:}

data/lib/model_context_protocol/server/resource.rb

@@ -2,37 +2,51 @@ 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
       attr_reader :name, :description, :mime_type, :uri
 
       def with_metadata(&block)
-        metadata = instance_eval(&block)
+        metadata_dsl = MetadataDSL.new
+        metadata_dsl.instance_eval(&block)
 
-        @name = metadata[:name]
-        @description = metadata[:description]
-        @mime_type = metadata[:mime_type]
-        @uri = metadata[:uri]
+        @name = metadata_dsl.name
+        @description = metadata_dsl.description
+        @mime_type = metadata_dsl.mime_type
+        @uri = metadata_dsl.uri
       end
 
       def inherited(subclass)
@@ -47,7 +61,29 @@ module ModelContextProtocol
       end
 
       def metadata
-        {name: @name, description: @description, mime_type: @mime_type, uri: @uri}
+        {name: @name, description: @description, mimeType: @mime_type, uri: @uri}
+      end
+    end
+
+    class MetadataDSL
+      def name(value = nil)
+        @name = value if value
+        @name
+      end
+
+      def description(value = nil)
+        @description = value if value
+        @description
+      end
+
+      def mime_type(value = nil)
+        @mime_type = value if value
+        @mime_type
+      end
+
+      def uri(value = nil)
+        @uri = value if value
+        @uri
       end
     end
   end

data/lib/model_context_protocol/server/resource_template.rb

@@ -0,0 +1,93 @@
+module ModelContextProtocol
+  class Server::ResourceTemplate
+    class << self
+      attr_reader :name, :description, :mime_type, :uri_template, :completions
+
+      def with_metadata(&block)
+        metadata_dsl = MetadataDSL.new
+        metadata_dsl.instance_eval(&block)
+
+        @name = metadata_dsl.name
+        @description = metadata_dsl.description
+        @mime_type = metadata_dsl.mime_type
+        @uri_template = metadata_dsl.uri_template
+        @completions = metadata_dsl.completions
+      end
+
+      def inherited(subclass)
+        subclass.instance_variable_set(:@name, @name)
+        subclass.instance_variable_set(:@description, @description)
+        subclass.instance_variable_set(:@mime_type, @mime_type)
+        subclass.instance_variable_set(:@uri_template, @uri_template)
+        subclass.instance_variable_set(:@completions, @completions&.dup)
+      end
+
+      def complete_for(param_name, value)
+        completion = if @completions && @completions[param_name.to_s]
+          @completions[param_name.to_s]
+        else
+          ModelContextProtocol::Server::NullCompletion
+        end
+
+        completion.call(param_name.to_s, value)
+      end
+
+      def metadata
+        {
+          name: @name,
+          description: @description,
+          mimeType: @mime_type,
+          uriTemplate: @uri_template,
+          completions: @completions&.transform_keys(&:to_s)
+        }
+      end
+    end
+
+    class MetadataDSL
+      attr_reader :completions
+
+      def initialize
+        @completions = {}
+      end
+
+      def name(value = nil)
+        @name = value if value
+        @name
+      end
+
+      def description(value = nil)
+        @description = value if value
+        @description
+      end
+
+      def mime_type(value = nil)
+        @mime_type = value if value
+        @mime_type
+      end
+
+      def uri_template(value = nil, &block)
+        @uri_template = value if value
+
+        if block_given?
+          completion_dsl = CompletionDSL.new
+          completion_dsl.instance_eval(&block)
+          @completions = completion_dsl.completions
+        end
+
+        @uri_template
+      end
+    end
+
+    class CompletionDSL
+      attr_reader :completions
+
+      def initialize
+        @completions = {}
+      end
+
+      def completion(param_name, completion_class)
+        @completions[param_name.to_s] = completion_class
+      end
+    end
+  end
+end

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)
@@ -53,11 +76,12 @@ module ModelContextProtocol
       attr_reader :name, :description, :input_schema
 
       def with_metadata(&block)
-        metadata = instance_eval(&block)
+        metadata_dsl = MetadataDSL.new
+        metadata_dsl.instance_eval(&block)
 
-        @name = metadata[:name]
-        @description = metadata[:description]
-        @input_schema = metadata[:inputSchema]
+        @name = metadata_dsl.name
+        @description = metadata_dsl.description
+        @input_schema = metadata_dsl.input_schema
       end
 
       def inherited(subclass)
@@ -68,8 +92,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
@@ -78,5 +104,22 @@ module ModelContextProtocol
         {name: @name, description: @description, inputSchema: @input_schema}
       end
     end
+
+    class MetadataDSL
+      def name(value = nil)
+        @name = value if value
+        @name
+      end
+
+      def description(value = nil)
+        @description = value if value
+        @description
+      end
+
+      def input_schema(&block)
+        @input_schema = instance_eval(&block) if block_given?
+        @input_schema
+      end
+    end
   end
 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
 
@@ -57,12 +60,45 @@ module ModelContextProtocol
         PingResponse[]
       end
 
+      router.map("completion/complete") do |message|
+        type = message["params"]["ref"]["type"]
+
+        completion_source = case type
+        when "ref/prompt"
+          name = message["params"]["ref"]["name"]
+          configuration.registry.find_prompt(name)
+        when "ref/resource"
+          uri = message["params"]["ref"]["uri"]
+          configuration.registry.find_resource_template(uri)
+        else
+          raise ModelContextProtocol::Server::ParameterValidationError, "ref/type invalid"
+        end
+
+        arg_name, arg_value = message["params"]["argument"].values_at("name", "value")
+
+        if completion_source
+          completion_source.complete_for(arg_name, arg_value)
+        else
+          ModelContextProtocol::Server::NullCompletion.call(arg_name, arg_value)
+        end
+      end
+
       router.map("resources/list") do
         configuration.registry.resources_data
       end
 
       router.map("resources/read") do |message|
-        configuration.registry.find_resource(message["params"]["uri"]).call
+        uri = message["params"]["uri"]
+        resource = configuration.registry.find_resource(uri)
+        unless resource
+          raise ModelContextProtocol::Server::ParameterValidationError, "resource not found for #{uri}"
+        end
+
+        resource.call
+      end
+
+      router.map("resources/templates/list") do |message|
+        configuration.registry.resource_templates_data
       end
 
       router.map("prompts/list") do
@@ -84,6 +120,7 @@ module ModelContextProtocol
 
     def build_capabilities
       {}.tap do |capabilities|
+        capabilities[:completions] = {}
         capabilities[:logging] = {} if configuration.logging_enabled?
 
         registry = configuration.registry
@@ -91,7 +128,7 @@ module ModelContextProtocol
         if registry.prompts_options.any? && !registry.instance_variable_get(:@prompts).empty?
           capabilities[:prompts] = {
             listChanged: registry.prompts_options[:list_changed]
-          }.compact
+          }.except(:completions).compact
         end
 
         if registry.resources_options.any? && !registry.instance_variable_get(:@resources).empty?

data/lib/model_context_protocol/version.rb

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

data/lib/model_context_protocol.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+require "addressable/template"
 
 Dir[File.join(__dir__, "model_context_protocol/", "**", "*.rb")].sort.each { |file| require_relative file }
 

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,37 @@
+#!/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
+
+    resource_templates do
+      register TestResourceTemplate
+    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.2
 platform: ruby
 authors:
 - Dick Davis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-11 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json-schema
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
 description:
 email:
 - dick@hey.com
@@ -42,14 +56,18 @@ files:
 - Rakefile
 - lib/model_context_protocol.rb
 - lib/model_context_protocol/server.rb
+- lib/model_context_protocol/server/completion.rb
 - lib/model_context_protocol/server/configuration.rb
 - lib/model_context_protocol/server/prompt.rb
 - lib/model_context_protocol/server/registry.rb
 - lib/model_context_protocol/server/resource.rb
+- lib/model_context_protocol/server/resource_template.rb
 - lib/model_context_protocol/server/router.rb
 - 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