Merge branch 'modelcontextprotocol:main' into patch-1

Author: dr03ramos

CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2025-09-14
+
+### Added
+
+- Tool output schema support with comprehensive validation (#122)
+- HTTP client transport layer for MCP clients (#28)
+- Tool annotations validation for protocol compatibility (#122)
+- Server instructions support (#87)
+- Title support in server info (#119)
+- Default values for tool annotation hints (#118)
+- Notifications/initialized method implementation (#84)
+
+### Changed
+
+- Make default protocol version the latest specification version (#83)
+- Protocol version validation to ensure valid values (#80)
+- Improved tool handling for tools with no arguments (#85, #86)
+- Better error handling and response API (#109)
+
+### Fixed
+
+- JSON-RPC notification format in Streamable HTTP transport (#91)
+- Errors when title is not specified (#126)
+- Tools with missing arguments handling (#86)
+- Namespacing issues in README examples (#89)
+
 ## [0.2.0] - 2025-07-15
 
 ### Added

README.md

@@ -124,8 +124,8 @@ Notifications follow the JSON-RPC 2.0 specification and use these method names:
 
 #### Transport Support
 
-- **HTTP Transport**: Notifications are sent as Server-Sent Events (SSE) to all connected sessions
-- **Stdio Transport**: Notifications are sent as JSON-RPC 2.0 messages to stdout
+- **stdio**: Notifications are sent as JSON-RPC 2.0 messages to stdout
+- **Streamable HTTP**: Notifications are sent as JSON-RPC 2.0 messages over HTTP with streaming (chunked transfer or SSE)
 
 #### Usage Example
 
@@ -385,6 +385,14 @@ class MyTool < MCP::Tool
     },
     required: ["message"]
   )
+  output_schema(
+    properties: {
+      result: { type: "string" },
+      success: { type: "boolean" },
+      timestamp: { type: "string", format: "date-time" }
+    },
+    required: ["result", "success", "timestamp"]
+  )
   annotations(
     read_only_hint: true,
     destructive_hint: false,
@@ -448,6 +456,105 @@ Tools can include annotations that provide additional metadata about their behav
 
 Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
 
+> [!NOTE]
+> This **Tool Annotations** feature is supported starting from `protocol_version: '2025-03-26'`.
+
+### Tool Output Schemas
+
+Tools can optionally define an `output_schema` to specify the expected structure of their results. This works similarly to how `input_schema` is defined and can be used in three ways:
+
+1. **Class definition with output_schema:**
+
+```ruby
+class WeatherTool < MCP::Tool
+  tool_name "get_weather"
+  description "Get current weather for a location"
+
+  input_schema(
+    properties: {
+      location: { type: "string" },
+      units: { type: "string", enum: ["celsius", "fahrenheit"] }
+    },
+    required: ["location"]
+  )
+
+  output_schema(
+    properties: {
+      temperature: { type: "number" },
+      condition: { type: "string" },
+      humidity: { type: "integer" }
+    },
+    required: ["temperature", "condition", "humidity"]
+  )
+
+  def self.call(location:, units: "celsius", server_context:)
+    # Call weather API and structure the response
+    api_response = WeatherAPI.fetch(location, units)
+    weather_data = {
+      temperature: api_response.temp,
+      condition: api_response.description,
+      humidity: api_response.humidity_percent
+    }
+
+    output_schema.validate_result(weather_data)
+
+    MCP::Tool::Response.new([{
+      type: "text",
+      text: weather_data.to_json
+    }])
+  end
+end
+```
+
+2. **Using Tool.define with output_schema:**
+
+```ruby
+tool = MCP::Tool.define(
+  name: "calculate_stats",
+  description: "Calculate statistics for a dataset",
+  input_schema: {
+    properties: {
+      numbers: { type: "array", items: { type: "number" } }
+    },
+    required: ["numbers"]
+  },
+  output_schema: {
+    properties: {
+      mean: { type: "number" },
+      median: { type: "number" },
+      count: { type: "integer" }
+    },
+    required: ["mean", "median", "count"]
+  }
+) do |args, server_context|
+  # Calculate statistics and validate against schema
+  MCP::Tool::Response.new([{ type: "text", text: "Statistics calculated" }])
+end
+```
+
+3. **Using OutputSchema objects:**
+
+```ruby
+class DataTool < MCP::Tool
+  output_schema MCP::Tool::OutputSchema.new(
+    properties: {
+      success: { type: "boolean" },
+      data: { type: "object" }
+    },
+    required: ["success"]
+  )
+end
+```
+
+MCP spec for the [Output Schema](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema) specifies that:
+
+- **Server Validation**: Servers MUST provide structured results that conform to the output schema
+- **Client Validation**: Clients SHOULD validate structured results against the output schema
+- **Better Integration**: Enables strict schema validation, type information, and improved developer experience
+- **Backward Compatibility**: Tools returning structured content SHOULD also include serialized JSON in a TextContent block
+
+The output schema follows standard JSON Schema format and helps ensure consistent data exchange between MCP servers and clients.
+
 ### Prompts
 
 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.
@@ -755,7 +862,7 @@ The client provides a wrapper class for tools returned by the server:
 
 - `MCP::Client::Tool` - Represents a single tool with its metadata
 
-This class provide easy access to tool properties like name, description, and input schema.
+This class provides easy access to tool properties like name, description, input schema, and output schema.
 
 ## Releases
 

examples/http_client.rb

@@ -50,23 +50,23 @@ def initialize_session
       },
     })
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
   def ping
     puts "=== Sending ping ==="
     result = send_request("ping")
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
   def list_tools
     puts "=== Listing tools ==="
     result = send_request("tools/list")
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -77,15 +77,15 @@ def call_tool(name, arguments)
       arguments: arguments,
     })
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
   def list_prompts
     puts "=== Listing prompts ==="
     result = send_request("prompts/list")
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -96,15 +96,15 @@ def get_prompt(name, arguments)
       arguments: arguments,
     })
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
   def list_resources
     puts "=== Listing resources ==="
     result = send_request("resources/list")
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -114,7 +114,7 @@ def read_resource(uri)
       uri: uri,
     })
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
+
     result
   end
 
@@ -131,7 +131,6 @@ def close_session
     response = http.request(request)
     result = JSON.parse(response.body)
     puts "Response: #{JSON.pretty_generate(result)}"
-    puts
 
     @session_id = nil
     result
@@ -140,10 +139,11 @@ def close_session
 
 # Main script
 if __FILE__ == $PROGRAM_NAME
-  puts "MCP HTTP Client Example"
-  puts "Make sure the HTTP server is running (ruby examples/http_server.rb)"
-  puts "=" * 50
-  puts
+  puts <<~MESSAGE
+    MCP HTTP Client Example
+    Make sure the HTTP server is running (ruby examples/http_server.rb)
+    #{"=" * 50}
+  MESSAGE
 
   client = MCPHTTPClient.new
 

examples/http_server.rb

@@ -154,15 +154,17 @@ def template(args, server_context:)
 end
 
 # Start the server
-puts "Starting MCP HTTP server on http://localhost:9292"
-puts "Use POST requests to initialize and send JSON-RPC commands"
-puts "Example initialization:"
-puts '  curl -i http://localhost:9292 --json \'{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\''
-puts ""
-puts "The server will return a session ID in the Mcp-Session-Id header."
-puts "Use this session ID for subsequent requests."
-puts ""
-puts "Press Ctrl+C to stop the server"
+puts <<~MESSAGE
+  Starting MCP HTTP server on http://localhost:9292
+  Use POST requests to initialize and send JSON-RPC commands
+  Example initialization:
+    curl -i http://localhost:9292 --json '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
+
+  The server will return a session ID in the Mcp-Session-Id header.
+  Use this session ID for subsequent requests.
+
+  Press Ctrl+C to stop the server
+MESSAGE
 
 # Run the server
 # Use Rackup to run the server

examples/streamable_http_client.rb

@@ -92,7 +92,6 @@ def main
   end
 
   puts "=== MCP SSE Test Client ==="
-  puts ""
 
   # Step 1: Initialize session
   logger.info("Initializing session...")
@@ -134,13 +133,16 @@ def main
 
   # Step 3: Interactive menu
   loop do
-    puts "\n=== Available Actions ==="
-    puts "1. Send custom notification"
-    puts "2. Test echo"
-    puts "3. List tools"
-    puts "0. Exit"
-    puts ""
-    print("Choose an action: ")
+    puts <<~MESSAGE.chomp
+
+      === Available Actions ===
+      1. Send custom notification
+      2. Test echo
+      3. List tools
+      0. Exit
+
+      Choose an action:#{" "}
+    MESSAGE
 
     choice = gets.chomp
 
@@ -167,19 +169,15 @@ def main
       else
         logger.error("Error: #{response[:body]["error"]}")
       end
-
     when "2"
       print("Enter message to echo: ")
       message = gets.chomp
       make_request(session_id, "tools/call", { name: "echo", arguments: { message: message } })
-
     when "3"
       make_request(session_id, "tools/list")
-
     when "0"
       logger.info("Exiting...")
       break
-
     else
       puts "Invalid choice"
     end