Internal Release 0.3.0

Add configurable exception reporter
Avoid leaking tool exceptions by sending them to a configurable exception reporter
Add optional context to pass to tools
Add basic instrumentation data/labels

Author: topherbullock

Gemfile.lock

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

README.md

@@ -47,14 +47,50 @@ module ModelContextProtocol
       server = ModelContextProtocol::Server.new(
         name: "my_server",
         tools: [someTool, anotherTool],
-        prompts: [myPrompt]
+        prompts: [myPrompt],
+        context: nil,
       )
       render(json: server.handle(request.body.read).to_h)
     end
   end
 end
 ```
 
+## Configuration
+
+The gem can be configured using the `ModelContextProtocol.configure` block:
+
+```ruby
+ModelContextProtocol.configure do |config|
+  config.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
+
+  config.instrumentation_callback = -> (data) { puts "Got instrumentation data #{data.inspect}" }
+end
+```
+
+### Exception Reporting
+
+The exception reporter receives two arguments:
+- `exception`: The Ruby exception object that was raised
+- `context`: A hash containing contextual information about where the error occurred
+
+The context hash includes:
+- For tool calls: `{ tool_name: "name", arguments: { ... } }`
+- For general request handling: `{ request: { ... } }`
+
+When an exception occurs:
+1. The exception is reported via the configured reporter
+2. For tool calls, a generic error response is returned to the client: `{ error: "Internal error occurred", is_error: true }`
+3. For other requests, the exception is re-raised after reporting
+
+If no exception reporter is configured, a default no-op reporter is used that silently ignores exceptions.
+
 ## Tools
 
 MCP spec includes [Tools](https://modelcontextprotocol.io/docs/concepts/tools) which provide functionality to LLM apps.
@@ -65,11 +101,10 @@ This gem provides a `ModelContextProtocol::Tool` class that can be used to creat
 
 ```ruby
 class MyTool < ModelContextProtocol::Tool
-  tool_name "my_tool"
-  tool_description "This tool performs specific functionality..."
-  tool_input_schema [{ type: "text", name: "message" }]
+  description "This tool performs specific functionality..."
+  input_schema [{ type: "text", name: "message" }]
 
-  def call(message)
+  def call(message, context:)
     Tool::Response.new([{ type: "text", content: "OK" }])
   end
 end
@@ -80,11 +115,14 @@ tool = MyTool.new
 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|
+tool = ModelContextProtocol::Tool.define(name: "my_tool", description: "This tool performs specific functionality...") do |args, context|
   Tool::Response.new([{ type: "text", content: "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.
+
 ## 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.
@@ -167,7 +205,8 @@ Register prompts with the MCP server:
 ```ruby
 server = ModelContextProtocol::Server.new(
   name: "my_server",
-  prompts: [MyPrompt.new]
+  prompts: [MyPrompt.new],
+  context: nil,
 )
 ```
 
@@ -176,6 +215,28 @@ The server will handle prompt listing and execution through the MCP protocol met
 - `prompts/list` - Lists all registered prompts and their schemas
 - `prompts/get` - Retrieves and executes a specific prompt with arguments
 
+### Instrumentation
+
+The server allows registering a callback to receive information about instrumentation.
+To register a handler pass a proc/lambda to as `instrumentation_callback` into the server constructor.
+
+```ruby
+ModelContextProtocol.configure do |config|
+  config.instrumentation_callback = -> (data) { puts "Got instrumentation data #{data.inspect}" }
+end
+```
+
+The data contains the following keys:
+`method`: the metod called, e.g. `ping`, `tools/list`, `tools/call` etc
+`tool_name`: the name of the tool called
+`prompt_name`: the name of the prompt called
+`resource_uri`: the uri of the resource called
+`error`: if looking up tools/prompts etc failed, e.g. `tool_not_found`
+`duration`: the duration of the call in seconds
+
+`tool_name`, `prompt_name` and `resource_uri` are only populated if a matching handler is registered.
+This is to avoid potential issues with metric cardinality
+
 ## Releases
 
 TODO

lib/model_context_protocol.rb

@@ -8,8 +8,19 @@
 require "model_context_protocol/resource"
 require "model_context_protocol/prompt"
 require "model_context_protocol/version"
+require "model_context_protocol/configuration"
 
 module ModelContextProtocol
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+
   class Annotations
     attr_reader :audience, :priority
 

lib/model_context_protocol/configuration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Configuration
+    attr_accessor :exception_reporter
+    attr_accessor :instrumentation_callback
+
+    def initialize
+      @exception_reporter = ->(exception, context) {} # Default no-op reporter
+      @instrumentation_callback = ->(data) {} # Default no-op callback
+    end
+  end
+end

lib/model_context_protocol/instrumentation.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  module Instrumentation
+    def instrument_call(method, &block)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @instrumentation_data = {}
+      add_instrumentation_data(method:)
+
+      result = yield block
+
+      end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      add_instrumentation_data(duration: end_time - start_time)
+
+      ModelContextProtocol.configuration.instrumentation_callback.call(@instrumentation_data)
+
+      result
+    end
+
+    def add_instrumentation_data(**kwargs)
+      @instrumentation_data.merge!(kwargs)
+    end
+  end
+end

lib/model_context_protocol/server.rb

@@ -1,20 +1,30 @@
 # frozen_string_literal: true
 
 require "json_rpc_handler"
+require_relative "instrumentation"
 
 module ModelContextProtocol
   class Server
+    class RequestHandlerError < StandardError
+      def initialize(message, request)
+        super(message)
+        @request = request
+      end
+    end
+
     PROTOCOL_VERSION = "2024-11-05"
 
-    attr_accessor :name, :tools, :prompts, :resources
+    include Instrumentation
+
+    attr_accessor :name, :tools, :prompts, :resources, :context
 
-    def initialize(name: "model_context_protocol", tools: [], prompts: [], resources: [])
+    def initialize(name: "model_context_protocol", tools: [], prompts: [], resources: [], context: nil)
       @name = name
       @tools = tools.to_h { |t| [t.name, t] }
       @prompts = prompts.to_h { |p| [p.name, p] }
       @resources = resources
       @resource_index = resources.index_by(&:uri)
-
+      @context = context
       @handlers = {
         "resources/list" => method(:list_resources),
         "resources/read" => method(:read_resource),
@@ -29,18 +39,21 @@ def initialize(name: "model_context_protocol", tools: [], prompts: [], resources
 
     def handle(request)
       JsonRpcHandler.handle(request) do |method|
-        handler = case method
-        when "tools/list"
-          ->(params) { { tools: @handlers["tools/list"].call(params) } }
-        when "prompts/list"
-          ->(params) { { prompts: @handlers["prompts/list"].call(params) } }
-        when "resources/list"
-          ->(params) { { resources: @handlers["resources/list"].call(params) } }
-        else
-          @handlers[method]
+        instrument_call(method) do
+          case method
+          when "tools/list"
+            ->(params) { { tools: @handlers["tools/list"].call(params) } }
+          when "prompts/list"
+            ->(params) { { prompts: @handlers["prompts/list"].call(params) } }
+          when "resources/list"
+            ->(params) { { resources: @handlers["resources/list"].call(params) } }
+          else
+            @handlers[method]
+          end
+        rescue => e
+          report_exception(e, { request: request })
+          raise RequestHandlerError.new("Internal error handling #{request[:method]} request", request)
         end
-
-        handler
       end
     end
 
@@ -86,6 +99,7 @@ def server_info
     end
 
     def init(request)
+      add_instrumentation_data(method: "initialize")
       {
         protocolVersion: PROTOCOL_VERSION,
         capabilities: capabilities,
@@ -94,47 +108,76 @@ def init(request)
     end
 
     def list_tools(request)
+      add_instrumentation_data(method: "tools/list")
       @tools.map { |_, tool| tool.to_h }
     end
 
     def call_tool(request)
+      add_instrumentation_data(method: "tools/call")
       tool_name = request[:name]
       tool = tools[tool_name]
-      raise "Tool not found #{tool_name}" unless tool
+      unless tool
+        add_instrumentation_data(error: :tool_not_found)
+        raise "Tool not found #{tool_name}"
+      end
+
+      add_instrumentation_data(tool_name:)
 
-      result = tool.call(**request[:arguments])
-      result.to_h
+      begin
+        result = tool.call(**request[:arguments], context:)
+        result.to_h
+      rescue => e
+        report_exception(e, { tool_name: tool_name, arguments: request[:arguments] })
+        add_instrumentation_data(error: :internal_error)
+        raise RequestHandlerError.new("Internal error calling tool #{tool_name}", request)
+      end
     end
 
     def list_prompts(request)
+      add_instrumentation_data(method: "prompts/list")
       @prompts.map { |_, prompt| prompt.to_h }
     end
 
     def get_prompt(request)
+      add_instrumentation_data(method: "prompts/get")
       prompt_name = request[:name]
       prompt = @prompts[prompt_name]
+      unless prompt
+        add_instrumentation_data(error: :prompt_not_found)
+        raise "Prompt not found #{prompt_name}"
+      end
 
-      raise "Prompt not found #{prompt_name}" unless prompt
+      add_instrumentation_data(prompt_name:)
 
       prompt_args = request[:arguments]
       prompt.validate_arguments!(prompt_args)
 
-      result = prompt.template(prompt_args)
-
-      result.to_h
+      prompt.template(prompt_args).to_h
     end
 
     def list_resources(request)
+      add_instrumentation_data(method: "resources/list")
+
       @resources.map(&:to_h)
     end
 
     def read_resource(request)
+      add_instrumentation_data(method: "resources/read")
       resource_uri = request[:uri]
 
       resource = @resource_index[resource_uri]
-      raise "Resource not found #{resource_uri}" unless resource
+      unless resource
+        add_instrumentation_data(error: :resource_not_found)
+        raise "Resource not found #{resource_uri}"
+      end
+
+      add_instrumentation_data(resource_uri:)
 
       resource.to_h
     end
+
+    def report_exception(exception, context = {})
+      ModelContextProtocol.configuration.exception_reporter.call(exception, context)
+    end
   end
 end

lib/model_context_protocol/tool.rb

@@ -44,8 +44,8 @@ def input_schema(value)
 
       def define(name: nil, description: nil, input_schema: nil, &block)
         new(name:, description:, input_schema:).tap do |tool|
-          tool.define_singleton_method(:call) do |*args|
-            instance_exec(*args, &block)
+          tool.define_singleton_method(:call) do |*args, context:|
+            instance_exec(*args, context:, &block)
           end
         end
       end
@@ -59,7 +59,7 @@ def initialize(name: nil, description: nil, input_schema: nil)
       @input_schema = input_schema || self.class.input_schema_value
     end
 
-    def call(*args)
+    def call(*args, context:)
       raise NotImplementedError, "Subclasses must implement call"
     end
 

lib/model_context_protocol/version.rb

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