Add support for _meta field on tool schema

lib/mcp/server.rb

@@ -99,8 +99,8 @@ def handle_json(request)
       end
     end
 
-    def define_tool(name: nil, title: nil, description: nil, input_schema: nil, annotations: nil, &block)
-      tool = Tool.define(name:, title:, description:, input_schema:, annotations:, &block)
+    def define_tool(name: nil, title: nil, description: nil, input_schema: nil, annotations: nil, metadata: nil, &block)
+      tool = Tool.define(name:, title:, description:, input_schema:, annotations:, metadata:, &block)
       @tools[tool.name_value] = tool
     end
 

lib/mcp/tool.rb

@@ -8,6 +8,7 @@ class << self
       attr_reader :title_value
       attr_reader :description_value
       attr_reader :annotations_value
+      attr_reader :metadata_value
 
       def call(*args, server_context: nil)
         raise NotImplementedError, "Subclasses must implement call"
@@ -20,6 +21,7 @@ def to_h
           description: description_value,
           inputSchema: input_schema_value.to_h,
         }
+        result[:_meta] = metadata_value if metadata_value
         result[:annotations] = annotations_value.to_h if annotations_value
         result
       end
@@ -31,6 +33,7 @@ def inherited(subclass)
         subclass.instance_variable_set(:@description_value, nil)
         subclass.instance_variable_set(:@input_schema_value, nil)
         subclass.instance_variable_set(:@annotations_value, nil)
+        subclass.instance_variable_set(:@metadata_value, nil)
       end
 
       def tool_name(value = NOT_SET)
@@ -77,6 +80,14 @@ def input_schema(value = NOT_SET)
         end
       end
 
+      def metadata(value = NOT_SET)
+        if value == NOT_SET
+          @metadata_value
+        else
+          @metadata_value = value
+        end
+      end
+
       def annotations(hash = NOT_SET)
         if hash == NOT_SET
           @annotations_value
@@ -85,12 +96,13 @@ def annotations(hash = NOT_SET)
         end
       end
 
-      def define(name: nil, title: nil, description: nil, input_schema: nil, annotations: nil, &block)
+      def define(name: nil, title: nil, description: nil, input_schema: nil, metadata: nil, annotations: nil, &block)
         Class.new(self) do
           tool_name name
           title title
           description description
           input_schema input_schema
+          metadata metadata
           self.annotations(annotations) if annotations
           define_singleton_method(:call, &block) if block
         end

test/mcp/server_test.rb

@@ -11,6 +11,7 @@ class ServerTest < ActiveSupport::TestCase
         name: "test_tool",
         title: "Test tool",
         description: "A test tool",
+        metadata: { foo: "bar" },
       )
 
       @tool_that_raises = Tool.define(
@@ -196,6 +197,7 @@ class ServerTest < ActiveSupport::TestCase
       assert_equal "Test tool", result[:tools][0][:title]
       assert_equal "A test tool", result[:tools][0][:description]
       assert_equal({ type: "object" }, result[:tools][0][:inputSchema])
+      assert_equal({ foo: "bar" }, result[:tools][0][:_meta])
       assert_instrumentation_data({ method: "tools/list" })
     end
 
@@ -212,6 +214,7 @@ class ServerTest < ActiveSupport::TestCase
       assert_equal "test_tool", result[:tools][0][:name]
       assert_equal "Test tool", result[:tools][0][:title]
       assert_equal "A test tool", result[:tools][0][:description]
+      assert_equal({ foo: "bar" }, result[:tools][0][:_meta])
     end
 
     test "#tools_list_handler sets the tools/list handler" do
@@ -827,6 +830,7 @@ def call(message:, server_context: nil)
         name: "defined_tool",
         description: "Defined tool",
         input_schema: { type: "object", properties: { message: { type: "string" } }, required: ["message"] },
+        metadata: { foo: "bar" },
       ) do |message:|
         Tool::Response.new(message)
       end

test/mcp/tool_test.rb

@@ -16,6 +16,9 @@ class TestTool < Tool
         read_only_hint: true,
         title: "Test Tool",
       )
+      metadata(
+        foo: "bar",
+      )
 
       class << self
         def call(message:, server_context: nil)
@@ -45,6 +48,14 @@ def call(message:, server_context: nil)
       assert_equal expected_annotations, tool.to_h[:annotations]
     end
 
+    test "#to_h includes metadata when present" do
+      tool = TestTool
+      expected_metadata = {
+        foo: "bar",
+      }
+      assert_equal expected_metadata, tool.to_h[:_meta]
+    end
+
     test "#call invokes the tool block and returns the response" do
       tool = TestTool
       response = tool.call(message: "test")
@@ -145,6 +156,23 @@ class InputSchemaTool < Tool
       assert_equal({ destructiveHint: true, idempotentHint: false, openWorldHint: true, readOnlyHint: true, title: "Mock Tool" }, tool.annotations_value.to_h)
     end
 
+    test ".define allows definition of tools with metadata" do
+      tool = Tool.define(
+        name: "mock_tool",
+        title: "Mock Tool",
+        description: "a mock tool for testing",
+        metadata: { foo: "bar" },
+      ) do |_|
+        Tool::Response.new([{ type: "text", content: "OK" }])
+      end
+
+      assert_equal "mock_tool", tool.name_value
+      assert_equal "Mock Tool", tool.title
+      assert_equal "a mock tool for testing", tool.description
+      assert_equal tool.input_schema, Tool::InputSchema.new
+      assert_equal({ foo: "bar" }, tool.metadata_value)
+    end
+
     test "Tool class method annotations can be set and retrieved" do
       class AnnotationsTestTool < Tool
         tool_name "annotations_test"
@@ -173,6 +201,30 @@ class UpdatableAnnotationsTool < Tool
       assert_equal "Updated", tool.annotations_value.title
     end
 
+    test "Tool class method metadata can be set and retrieved" do
+      class MetadataTestTool < Tool
+        tool_name "annotations_test"
+        metadata(foo: "bar")
+      end
+
+      tool = MetadataTestTool
+      assert_instance_of Hash, tool.metadata_value
+      assert_equal "bar", tool.metadata_value[:foo]
+    end
+
+    test "Tool class method metadata can be updated" do
+      class UpdatableMetadataTool < Tool
+        tool_name "updatable_metadata"
+      end
+
+      tool = UpdatableMetadataTool
+      tool.metadata(foo: "baz")
+      assert_equal({ foo: "baz" }, tool.metadata_value)
+
+      tool.metadata(foo: "qux")
+      assert_equal({ foo: "qux" }, tool.metadata_value)
+    end
+
     test "#call with Sorbet typed tools invokes the tool block and returns the response" do
       class TypedTestTool < Tool
         tool_name "test_tool"