Merge remote-tracking branch 'upstream/main' into add-basic-http-client-support

Author: jcat4

README.md

@@ -160,6 +160,7 @@ class ApplicationController < ActionController::Base
   def index
     server = MCP::Server.new(
       name: "my_server",
+      title: "Example Server Display Name", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
       version: "1.0.0",
       instructions: "Use the tools of this server as a last resort",
       tools: [SomeTool, AnotherTool],
@@ -216,6 +217,7 @@ You can run this script and then type in requests to the server at the command l
 $ ruby examples/stdio_server.rb
 {"jsonrpc":"2.0","id":"1","method":"ping"}
 {"jsonrpc":"2.0","id":"2","method":"tools/list"}
+{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"example_tool","arguments":{"message":"Hello"}}}
 ```
 
 ### Configuration
@@ -422,10 +424,10 @@ e.g. around authentication state.
 
 Tools can include annotations that provide additional metadata about their behavior. The following annotations are supported:
 
-- `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
-- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state)
+- `destructive_hint`: Indicates if the tool performs destructive operations. Defaults to true
+- `idempotent_hint`: Indicates if the tool's operations are idempotent. Defaults to false
+- `open_world_hint`: Indicates if the tool operates in an open world context. Defaults to true
+- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state). Defaults to false
 - `title`: A human-readable title for the tool
 
 Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
@@ -560,6 +562,8 @@ This is to avoid potential issues with metric cardinality
 
 MCP spec includes [Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources).
 
+### Reading Resources
+
 The `MCP::Resource` class provides a way to register resources with the server.
 
 ```ruby
@@ -587,11 +591,29 @@ server.resources_read_handler do |params|
     text: "Hello from example resource! URI: #{params[:uri]}"
   }]
 end
-
 ```
 
 otherwise `resources/read` requests will be a no-op.
 
+### Resource Templates
+
+The `MCP::ResourceTemplate` class provides a way to register resource templates with the server.
+
+```ruby
+resource_template = MCP::ResourceTemplate.new(
+  uri_template: "https://example.com/my_resource_template",
+  name: "my-resource-template",
+  title: "My Resource Template", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
+  description: "Lorem ipsum dolor sit amet",
+  mime_type: "text/html",
+)
+
+server = MCP::Server.new(
+  name: "my_server",
+  resource_templates: [resource_template],
+)
+```
+
 ## Building an MCP Client
 
 The `MCP::Client` class provides an interface for interacting with MCP servers.

lib/mcp/server.rb

@@ -31,10 +31,11 @@ def initialize(method_name)
 
     include Instrumentation
 
-    attr_accessor :name, :version, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport
+    attr_accessor :name, :title, :version, :instructions, :tools, :prompts, :resources, :server_context, :configuration, :capabilities, :transport
 
     def initialize(
       name: "model_context_protocol",
+      title: nil,
       version: DEFAULT_VERSION,
       instructions: nil,
       tools: [],
@@ -47,6 +48,7 @@ def initialize(
       transport: nil
     )
       @name = name
+      @title = title
       @version = version
       @instructions = instructions
       @tools = tools.to_h { |t| [t.name_value, t] }
@@ -218,6 +220,7 @@ def default_capabilities
     def server_info
       @server_info ||= {
         name:,
+        title:,
         version:,
       }
     end

lib/mcp/tool/annotations.rb

@@ -3,9 +3,9 @@
 module MCP
   class Tool
     class Annotations
-      attr_reader :title, :read_only_hint, :destructive_hint, :idempotent_hint, :open_world_hint
+      attr_reader :destructive_hint, :idempotent_hint, :open_world_hint, :read_only_hint, :title
 
-      def initialize(title: nil, read_only_hint: nil, destructive_hint: nil, idempotent_hint: nil, open_world_hint: nil)
+      def initialize(destructive_hint: true, idempotent_hint: false, open_world_hint: true, read_only_hint: false, title: nil)
         @title = title
         @read_only_hint = read_only_hint
         @destructive_hint = destructive_hint
@@ -15,11 +15,11 @@ def initialize(title: nil, read_only_hint: nil, destructive_hint: nil, idempoten
 
       def to_h
         {
-          title:,
-          readOnlyHint: read_only_hint,
           destructiveHint: destructive_hint,
           idempotentHint: idempotent_hint,
           openWorldHint: open_world_hint,
+          readOnlyHint: read_only_hint,
+          title:,
         }.compact
       end
     end

test/mcp/server_test.rb

@@ -69,6 +69,7 @@ class ServerTest < ActiveSupport::TestCase
 
       @server = Server.new(
         name: @server_name,
+        title: "Example Server Display Name",
         version: "1.2.3",
         instructions: "Optional instructions for the client",
         tools: [@tool, @tool_that_raises],
@@ -140,6 +141,7 @@ class ServerTest < ActiveSupport::TestCase
           },
           serverInfo: {
             name: @server_name,
+            title: "Example Server Display Name",
             version: "1.2.3",
           },
           instructions: "Optional instructions for the client",
@@ -769,6 +771,18 @@ def call(message:, server_context: nil)
       assert_equal Configuration::DEFAULT_PROTOCOL_VERSION, response[:result][:protocolVersion]
     end
 
+    test "server uses default title when not configured" do
+      server = Server.new(name: "test_server")
+      request = {
+        jsonrpc: "2.0",
+        method: "initialize",
+        id: 1,
+      }
+
+      response = server.handle(request)
+      assert_nil response[:result][:serverInfo][:title]
+    end
+
     test "server uses default version when not configured" do
       server = Server.new(name: "test_server")
       request = {

test/mcp/tool/annotations_test.rb

@@ -7,31 +7,31 @@ class Tool
     class AnnotationsTest < ActiveSupport::TestCase
       test "Tool::Annotations initializes with all properties" do
         annotations = Tool::Annotations.new(
-          title: "Test Tool",
-          read_only_hint: true,
           destructive_hint: false,
           idempotent_hint: true,
           open_world_hint: false,
+          read_only_hint: true,
+          title: "Test Tool",
         )
 
-        assert_equal "Test Tool", annotations.title
-        assert annotations.read_only_hint
         refute annotations.destructive_hint
         assert annotations.idempotent_hint
         refute annotations.open_world_hint
+        assert annotations.read_only_hint
+        assert_equal "Test Tool", annotations.title
       end
 
       test "Tool::Annotations initializes with partial properties" do
         annotations = Tool::Annotations.new(
-          title: "Test Tool",
           read_only_hint: true,
+          title: "Test Tool",
         )
 
-        assert_equal "Test Tool", annotations.title
+        assert annotations.destructive_hint
+        refute annotations.idempotent_hint
+        assert annotations.open_world_hint
         assert annotations.read_only_hint
-        assert_nil annotations.destructive_hint
-        assert_nil annotations.idempotent_hint
-        assert_nil annotations.open_world_hint
+        assert_equal "Test Tool", annotations.title
       end
 
       test "Tool::Annotations#to_h omits nil values" do
@@ -41,34 +41,37 @@ class AnnotationsTest < ActiveSupport::TestCase
         )
 
         expected = {
-          title: "Test Tool",
+          destructiveHint: true,
+          idempotentHint: false,
+          openWorldHint: true,
           readOnlyHint: true,
+          title: "Test Tool",
         }
         assert_equal expected, annotations.to_h
       end
 
       test "Tool::Annotations#to_h handles all properties" do
         annotations = Tool::Annotations.new(
-          title: "Test Tool",
-          read_only_hint: true,
           destructive_hint: false,
           idempotent_hint: true,
           open_world_hint: false,
+          read_only_hint: true,
+          title: "Test Tool",
         )
 
         expected = {
-          title: "Test Tool",
-          readOnlyHint: true,
           destructiveHint: false,
           idempotentHint: true,
           openWorldHint: false,
+          readOnlyHint: true,
+          title: "Test Tool",
         }
         assert_equal expected, annotations.to_h
       end
 
-      test "Tool::Annotations#to_h returns empty hash when all values are nil" do
+      test "Tool::Annotations#to_h returns hash with default hint values" do
         annotations = Tool::Annotations.new
-        assert_empty annotations.to_h
+        assert_equal({ destructiveHint: true, idempotentHint: false, openWorldHint: true, readOnlyHint: false }, annotations.to_h)
       end
     end
   end

test/mcp/tool_test.rb

@@ -10,11 +10,11 @@ class TestTool < Tool
       description "a test tool for testing"
       input_schema({ properties: { message: { type: "string" } }, required: ["message"] })
       annotations(
-        title: "Test Tool",
-        read_only_hint: true,
         destructive_hint: false,
         idempotent_hint: true,
         open_world_hint: false,
+        read_only_hint: true,
+        title: "Test Tool",
       )
 
       class << self
@@ -36,11 +36,11 @@ def call(message:, server_context: nil)
     test "#to_h includes annotations when present" do
       tool = TestTool
       expected_annotations = {
-        title: "Test Tool",
-        readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
+        readOnlyHint: true,
+        title: "Test Tool",
       }
       assert_equal expected_annotations, tool.to_h[:annotations]
     end
@@ -142,15 +142,15 @@ class InputSchemaTool < Tool
       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({ readOnlyHint: true, title: "Mock Tool" }, tool.annotations_value.to_h)
+      assert_equal({ destructiveHint: true, idempotentHint: false, openWorldHint: true, readOnlyHint: true, title: "Mock Tool" }, tool.annotations_value.to_h)
     end
 
     test "Tool class method annotations can be set and retrieved" do
       class AnnotationsTestTool < Tool
         tool_name "annotations_test"
         annotations(
-          title: "Annotations Test",
           read_only_hint: true,
+          title: "Annotations Test",
         )
       end