Internal Release 0.5.0

Bump protocol version to 2025-03-26
Provide fallback value for tool_name
Make configuration per server
Add support for tool annotations
document tool annotations

Author: topherbullock

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    model_context_protocol (0.4.0)
+    model_context_protocol (0.5.0)
       json_rpc_handler (~> 0.1)
 
 GEM

README.md

@@ -76,6 +76,24 @@ module ModelContextProtocol
 end
 ```
 
+To see sample responses without setting up a client to hit the server, you can simply run
+
+```ruby
+server = ModelContextProtocol::Server.new(
+  name: "my_server",
+  tools: [SomeTool, AnotherTool],
+  prompts: [MyPrompt],
+  context: { user_id: current_user.id },
+)
+request = {
+  jsonrpc: "2.0",
+  method: "tools/list",
+  params: {},
+  id: "1"
+}
+server.handle(request)
+```
+
 ## Configuration
 
 The gem can be configured using the `ModelContextProtocol.configure` block:
@@ -92,6 +110,26 @@ ModelContextProtocol.configure do |config|
 
   config.instrumentation_callback = -> (data) { puts "Got instrumentation data #{data.inspect}" }
 end
+
+or by creating an explicit configuration and passing it into the server.
+This is useful for systems where an application hosts more than one MCP server but
+they might require different instrumentation callbacks.
+
+configuration = ModelContextProtocol::Configuration.new
+configuration.exception_reporter = ->(exception, context) do
+  # Your exception reporting logic here
+  # For example with Bugsnag:
+  Bugsnag.notify(exception) do |report|
+    report.add_metadata(:model_context_protocol, context)
+  end
+end
+
+configuration.instrumentation_callback = -> (data) { puts "Got instrumentation data #{data.inspect}" }
+
+server = ModelContextProtocol::Server.new(
+  # ... all other options
+  configuration:,
+)
 ```
 
 ### Exception Reporting
@@ -125,10 +163,23 @@ This gem provides a `ModelContextProtocol::Tool` class that can be used to creat
 ```ruby
 class MyTool < ModelContextProtocol::Tool
   description "This tool performs specific functionality..."
-  input_schema [{ type: "text", name: "message" }]
+  input_schema [{ type: "text", text: "message" }]
+  annotations(
+    title: "My Tool",
+    read_only_hint: true,
+    destructive_hint: false,
+    idempotent_hint: true,
+    open_world_hint: false
+  )
 
-  def self.call(message, context:)
-    Tool::Response.new([{ type: "text", content: "OK" }])
+  input_schema type: 'object',
+    properties: {
+      message: { type: 'string' },
+    },
+    required: ['message']
+
+  def self.call(message:, context:)
+    Tool::Response.new([{ type: "text", text: "OK" }])
   end
 end
 
@@ -138,14 +189,33 @@ tool = MyTool
 2. By using the `ModelContextProtocol::Tool.define` method with a block:
 
 ```ruby
-tool = ModelContextProtocol::Tool.define(name: "my_tool", description: "This tool performs specific functionality...") do |args, context|
-  Tool::Response.new([{ type: "text", content: "OK" }])
+tool = ModelContextProtocol::Tool.define(
+  name: "my_tool",
+  description: "This tool performs specific functionality...",
+  annotations: {
+    title: "My Tool",
+    read_only_hint: true
+  }
+) do |args, context|
+  Tool::Response.new([{ type: "text", text: "OK" }])
 end
 ```
 
 The context parameter is the context passed into the server and can be used to pass per request information,
 e.g. around authentication state.
 
+### Tool Annotations
+
+Tools can include annotations that provide additional metadata about their behavior. The following annotations are supported:
+
+- `title`: A human-readable title for the tool
+- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state)
+- `destructive_hint`: Indicates if the tool performs destructive operations
+- `idempotent_hint`: Indicates if the tool's operations are idempotent
+- `open_world_hint`: Indicates if the tool operates in an open world context
+
+Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
+
 ## Prompts
 
 MCP spec includes [Prompts](https://modelcontextprotocol.io/docs/concepts/prompts), which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.

lib/model_context_protocol/configuration.rb

@@ -2,12 +2,57 @@
 
 module ModelContextProtocol
   class Configuration
-    attr_accessor :exception_reporter
-    attr_accessor :instrumentation_callback
+    attr_writer :exception_reporter, :instrumentation_callback
 
-    def initialize
-      @exception_reporter = ->(exception, context) {} # Default no-op reporter
-      @instrumentation_callback = ->(data) {} # Default no-op callback
+    def initialize(exception_reporter: nil, instrumentation_callback: nil)
+      @exception_reporter = exception_reporter
+      @instrumentation_callback = instrumentation_callback
+    end
+
+    def exception_reporter
+      @exception_reporter || default_exception_reporter
+    end
+
+    def exception_reporter?
+      !@exception_reporter.nil?
+    end
+
+    def instrumentation_callback
+      @instrumentation_callback || default_instrumentation_callback
+    end
+
+    def instrumentation_callback?
+      !@instrumentation_callback.nil?
+    end
+
+    def merge(other)
+      return self if other.nil?
+
+      exception_reporter = if other.exception_reporter?
+        other.exception_reporter
+      else
+        @exception_reporter
+      end
+      instrumentation_callback = if other.instrumentation_callback?
+        other.instrumentation_callback
+      else
+        @instrumentation_callback
+      end
+
+      Configuration.new(
+        exception_reporter:,
+        instrumentation_callback:,
+      )
+    end
+
+    private
+
+    def default_exception_reporter
+      @default_exception_reporter ||= ->(exception, context) {}
+    end
+
+    def default_instrumentation_callback
+      @default_instrumentation_callback ||= ->(data) {}
     end
   end
 end

lib/model_context_protocol/content.rb

@@ -12,7 +12,7 @@ def initialize(text, annotations: nil)
       end
 
       def to_h
-        { text:, annotations: }.compact
+        { text:, annotations:, type: "text" }.compact
       end
     end
 
@@ -26,7 +26,7 @@ def initialize(data, mime_type, annotations: nil)
       end
 
       def to_h
-        { data:, mime_type:, annotations: }.compact
+        { data:, mime_type:, annotations:, type: "image" }.compact
       end
     end
   end

lib/model_context_protocol/instrumentation.rb

@@ -12,7 +12,7 @@ def instrument_call(method, &block)
       end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       add_instrumentation_data(duration: end_time - start_time)
 
-      ModelContextProtocol.configuration.instrumentation_callback.call(@instrumentation_data)
+      configuration.instrumentation_callback.call(@instrumentation_data)
 
       result
     end

lib/model_context_protocol/prompt.rb

@@ -114,7 +114,7 @@ def validate_arguments!(args)
       private
 
       def required_args
-        arguments_value.filter_map { |arg| arg.name if arg.required }
+        arguments_value.filter_map { |arg| arg.name.to_sym if arg.required }
       end
     end
   end

lib/model_context_protocol/server.rb

@@ -12,19 +12,21 @@ def initialize(message, request)
       end
     end
 
-    PROTOCOL_VERSION = "2024-11-05"
+    PROTOCOL_VERSION = "2025-03-26"
 
     include Instrumentation
 
-    attr_accessor :name, :tools, :prompts, :resources, :context
+    attr_accessor :name, :tools, :prompts, :resources, :context, :configuration
 
-    def initialize(name: "model_context_protocol", tools: [], prompts: [], resources: [], context: nil)
+    def initialize(name: "model_context_protocol", tools: [], prompts: [], resources: [], context: nil,
+      configuration: nil)
       @name = name
       @tools = tools.to_h { |t| [t.name_value, t] }
       @prompts = prompts.to_h { |p| [p.name_value, p] }
       @resources = resources
       @resource_index = resources.index_by(&:uri)
       @context = context
+      @configuration = ModelContextProtocol.configuration.merge(configuration)
       @handlers = {
         "resources/list" => method(:list_resources),
         "resources/read" => method(:read_resource),
@@ -186,7 +188,7 @@ def read_resource(request)
     end
 
     def report_exception(exception, context = {})
-      ModelContextProtocol.configuration.exception_reporter.call(exception, context)
+      configuration.exception_reporter.call(exception, context)
     end
   end
 end

lib/model_context_protocol/tool.rb

@@ -15,30 +15,60 @@ def to_h
       end
     end
 
+    class Annotations
+      attr_reader :title, :read_only_hint, :destructive_hint, :idempotent_hint, :open_world_hint
+
+      def initialize(title: nil, read_only_hint: nil, destructive_hint: nil, idempotent_hint: nil, open_world_hint: nil)
+        @title = title
+        @read_only_hint = read_only_hint
+        @destructive_hint = destructive_hint
+        @idempotent_hint = idempotent_hint
+        @open_world_hint = open_world_hint
+      end
+
+      def to_h
+        {
+          title:,
+          readOnlyHint: read_only_hint,
+          destructiveHint: destructive_hint,
+          idempotentHint: idempotent_hint,
+          openWorldHint: open_world_hint,
+        }.compact
+      end
+    end
+
     class << self
       NOT_SET = Object.new
 
       attr_reader :description_value
       attr_reader :input_schema_value
+      attr_reader :annotations_value
 
       def call(*args, context:)
         raise NotImplementedError, "Subclasses must implement call"
       end
 
       def to_h
-        { name: name_value, description: description_value, inputSchema: input_schema_value }
+        result = {
+          name: name_value,
+          description: description_value,
+          inputSchema: input_schema_value,
+        }
+        result[:annotations] = annotations_value.to_h if annotations_value
+        result
       end
 
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@name_value, nil)
         subclass.instance_variable_set(:@description_value, nil)
         subclass.instance_variable_set(:@input_schema_value, nil)
+        subclass.instance_variable_set(:@annotations_value, nil)
       end
 
       def tool_name(value = NOT_SET)
         if value == NOT_SET
-          @name_value
+          name_value
         else
           @name_value = value
         end
@@ -64,11 +94,20 @@ def input_schema(value = NOT_SET)
         end
       end
 
-      def define(name: nil, description: nil, input_schema: nil, &block)
+      def annotations(hash = NOT_SET)
+        if hash == NOT_SET
+          @annotations_value
+        else
+          @annotations_value = Annotations.new(**hash)
+        end
+      end
+
+      def define(name: nil, description: nil, input_schema: nil, annotations: nil, &block)
         Class.new(self) do
           tool_name name
           description description
           input_schema input_schema
+          self.annotations(annotations) if annotations
           define_singleton_method(:call) do |*args, context:|
             instance_exec(*args, context:, &block)
           end

lib/model_context_protocol/version.rb

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

test/model_context_protocol/instrumentation_test.rb

@@ -6,12 +6,11 @@ module ModelContextProtocol
   class InstrumentationTest < ActiveSupport::TestCase
     class Subject
       include Instrumentation
-      attr_reader :instrumentation_data_received
+      attr_reader :instrumentation_data_received, :configuration
 
       def initialize
-        ModelContextProtocol.configure do |config|
-          config.instrumentation_callback = ->(data) { @instrumentation_data_received = data }
-        end
+        @configuration = ModelContextProtocol::Configuration.new
+        @configuration.instrumentation_callback = ->(data) { @instrumentation_data_received = data }
       end
 
       def instrumented_method