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

Author: jcat4

.rubocop.yml

@@ -7,3 +7,6 @@ plugins:
 
 Gemspec/DevelopmentDependencies:
   Enabled: true
+
+Minitest/LiteralAsActualArgument:
+  Enabled: true

Gemfile

@@ -22,7 +22,6 @@ gem "sorbet-static-and-runtime"
 group :test do
   gem "faraday", ">= 2.0"
   gem "minitest", "~> 5.1", require: false
-  gem "minitest-reporters"
   gem "mocha"
   gem "webmock"
 end

README.md

@@ -110,9 +110,9 @@ The server supports sending notifications to clients when lists of tools, prompt
 
 The server provides three notification methods:
 
-- `notify_tools_list_changed()` - Send a notification when the tools list changes
-- `notify_prompts_list_changed()` - Send a notification when the prompts list changes
-- `notify_resources_list_changed()` - Send a notification when the resources list changes
+- `notify_tools_list_changed` - Send a notification when the tools list changes
+- `notify_prompts_list_changed` - Send a notification when the prompts list changes
+- `notify_resources_list_changed` - Send a notification when the resources list changes
 
 #### Notification Format
 
@@ -136,7 +136,7 @@ server.transport = transport
 
 # When tools change, notify clients
 server.define_tool(name: "new_tool") { |**args| { result: "ok" } }
-server.notify_tools_list_changed()
+server.notify_tools_list_changed
 ```
 
 ### Unsupported Features ( to be implemented in future versions )
@@ -157,11 +157,11 @@ You can use the `Server#handle_json` method to handle requests.
 
 ```ruby
 class ApplicationController < ActionController::Base
-
   def index
     server = MCP::Server.new(
       name: "my_server",
       version: "1.0.0",
+      instructions: "Use the tools of this server as a last resort",
       tools: [SomeTool, AnotherTool],
       prompts: [MyPrompt],
       server_context: { user_id: current_user.id },
@@ -328,21 +328,22 @@ config.instrumentation_callback = ->(data) {
 
 ### Server Protocol Version
 
-The server's protocol version can be overridden using the `protocol_version` class method:
+The server's protocol version can be overridden using the `protocol_version` keyword argument:
 
 ```ruby
-MCP::Server.protocol_version = "2024-11-05"
+configuration = MCP::Configuration.new(protocol_version: "2024-11-05")
+MCP::Server.new(name: "test_server", configuration: configuration)
 ```
 
 This will make all new server instances use the specified protocol version instead of the default version. The protocol version can be reset to the default by setting it to `nil`:
 
 ```ruby
-MCP::Server.protocol_version = nil
+MCP::Configuration.new(protocol_version: nil)
 ```
 
 If an invalid `protocol_version` value is set, an `ArgumentError` is raised.
 
-Be sure to check the [MCP spec](https://modelcontextprotocol.io/specification) for the protocol version to understand the supported features for the version being set.
+Be sure to check the [MCP spec](https://modelcontextprotocol.io/specification/versioning) for the protocol version to understand the supported features for the version being set.
 
 ### Exception Reporting
 
@@ -366,14 +367,15 @@ If no exception reporter is configured, a default no-op reporter is used that si
 
 ### Tools
 
-MCP spec includes [Tools](https://modelcontextprotocol.io/docs/concepts/tools) which provide functionality to LLM apps.
+MCP spec includes [Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) which provide functionality to LLM apps.
 
 This gem provides a `MCP::Tool` class that can be used to create tools in two ways:
 
 1. As a class definition:
 
 ```ruby
 class MyTool < MCP::Tool
+  title "My Tool" # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description "This tool performs specific functionality..."
   input_schema(
     properties: {
@@ -382,11 +384,11 @@ class MyTool < MCP::Tool
     required: ["message"]
   )
   annotations(
-    title: "My Tool",
     read_only_hint: true,
     destructive_hint: false,
     idempotent_hint: true,
-    open_world_hint: false
+    open_world_hint: false,
+    title: "My Tool"
   )
 
   def self.call(message:, server_context:)
@@ -402,10 +404,11 @@ tool = MyTool
 ```ruby
 tool = MCP::Tool.define(
   name: "my_tool",
+  title: "My Tool", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description: "This tool performs specific functionality...",
   annotations: {
-    title: "My Tool",
-    read_only_hint: true
+    read_only_hint: true,
+    title: "My Tool"
   }
 ) do |args, server_context|
   MCP::Tool::Response.new([{ type: "text", text: "OK" }])
@@ -419,17 +422,17 @@ e.g. around authentication state.
 
 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
+- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state)
+- `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.
 
 ### 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.
+MCP spec includes [Prompts](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts), which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.
 
 The `MCP::Prompt` class provides two ways to create prompts:
 
@@ -438,6 +441,7 @@ The `MCP::Prompt` class provides two ways to create prompts:
 ```ruby
 class MyPrompt < MCP::Prompt
   prompt_name "my_prompt"  # Optional - defaults to underscored class name
+  title "My Prompt" # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description "This prompt performs specific functionality..."
   arguments [
     MCP::Prompt::Argument.new(
@@ -474,6 +478,7 @@ prompt = MyPrompt
 ```ruby
 prompt = MCP::Prompt.define(
   name: "my_prompt",
+  title: "My Prompt", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description: "This prompt performs specific functionality...",
   arguments: [
     MCP::Prompt::Argument.new(
@@ -540,26 +545,28 @@ end
 ```
 
 The data contains the following keys:
-`method`: the method 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
+
+- `method`: the method 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
 
 ### Resources
 
-MCP spec includes [Resources](https://modelcontextprotocol.io/docs/concepts/resources)
+MCP spec includes [Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources).
 
 The `MCP::Resource` class provides a way to register resources with the server.
 
 ```ruby
 resource = MCP::Resource.new(
   uri: "https://example.com/my_resource",
-  name: "My Resource",
+  name: "my-resource",
+  title: "My Resource", # 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",
 )
@@ -577,7 +584,7 @@ server.resources_read_handler do |params|
   [{
     uri: params[:uri],
     mimeType: "text/plain",
-    text: params[:uri],
+    text: "Hello from example resource! URI: #{params[:uri]}"
   }]
 end
 

examples/http_server.rb

@@ -62,7 +62,8 @@ def template(args, server_context:)
   resources: [
     MCP::Resource.new(
       uri: "https://test_resource.invalid",
-      name: "Test resource",
+      name: "test-resource",
+      title: "Test Resource",
       description: "Test resource that echoes back the uri as its content",
       mime_type: "text/plain",
     ),

examples/stdio_server.rb

@@ -59,7 +59,8 @@ def template(args, server_context:)
   resources: [
     MCP::Resource.new(
       uri: "https://test_resource.invalid",
-      name: "Test resource",
+      name: "test-resource",
+      title: "Test Resource",
       description: "Test resource that echoes back the uri as its content",
       mime_type: "text/plain",
     ),

lib/mcp/prompt.rb

@@ -6,6 +6,7 @@ class Prompt
     class << self
       NOT_SET = Object.new
 
+      attr_reader :title_value
       attr_reader :description_value
       attr_reader :arguments_value
 
@@ -14,12 +15,13 @@ def template(args, server_context: nil)
       end
 
       def to_h
-        { name: name_value, description: description_value, arguments: arguments_value.map(&:to_h) }.compact
+        { name: name_value, title: title_value, description: description_value, arguments: arguments_value.map(&:to_h) }.compact
       end
 
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@name_value, nil)
+        subclass.instance_variable_set(:@title_value, nil)
         subclass.instance_variable_set(:@description_value, nil)
         subclass.instance_variable_set(:@arguments_value, nil)
       end
@@ -36,6 +38,14 @@ def name_value
         @name_value || StringUtils.handle_from_class_name(name)
       end
 
+      def title(value = NOT_SET)
+        if value == NOT_SET
+          @title_value
+        else
+          @title_value = value
+        end
+      end
+
       def description(value = NOT_SET)
         if value == NOT_SET
           @description_value
@@ -52,9 +62,10 @@ def arguments(value = NOT_SET)
         end
       end
 
-      def define(name: nil, description: nil, arguments: [], &block)
+      def define(name: nil, title: nil, description: nil, arguments: [], &block)
         Class.new(self) do
           prompt_name name
+          title title
           description description
           arguments arguments
           define_singleton_method(:template) do |args, server_context: nil|

lib/mcp/resource.rb

@@ -3,21 +3,23 @@
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :description, :mime_type
+    attr_reader :uri, :name, :title, :description, :mime_type
 
-    def initialize(uri:, name:, description: nil, mime_type: nil)
+    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil)
       @uri = uri
       @name = name
+      @title = title
       @description = description
       @mime_type = mime_type
     end
 
     def to_h
       {
-        uri: @uri,
-        name: @name,
-        description: @description,
-        mimeType: @mime_type,
+        uri: uri,
+        name: name,
+        title: title,
+        description: description,
+        mimeType: mime_type,
       }.compact
     end
   end

lib/mcp/resource_template.rb

@@ -3,21 +3,23 @@
 
 module MCP
   class ResourceTemplate
-    attr_reader :uri_template, :name, :description, :mime_type
+    attr_reader :uri_template, :name, :title, :description, :mime_type
 
-    def initialize(uri_template:, name:, description: nil, mime_type: nil)
+    def initialize(uri_template:, name:, title: nil, description: nil, mime_type: nil)
       @uri_template = uri_template
       @name = name
+      @title = title
       @description = description
       @mime_type = mime_type
     end
 
     def to_h
       {
-        uriTemplate: @uri_template,
-        name: @name,
-        description: @description,
-        mimeType: @mime_type,
+        uriTemplate: uri_template,
+        name: name,
+        title: title,
+        description: description,
+        mimeType: mime_type,
       }.compact
     end
   end