From cc16639cc82ba693f1126034fdc1be9e2539f02d Mon Sep 17 00:00:00 2001 From: Koichi ITO Date: Thu, 4 Sep 2025 10:40:41 +0900 Subject: [PATCH 1/2] [Docs] Tweak the doc of Transport Support in the README.md Follow-up to #33. The order of appearance of Stdio and Streamable HTTP follows the specification: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 834280d..53f1498 100644 --- a/README.md +++ b/README.md @@ -122,8 +122,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 From 08048283e483df30b94c183217fdb3e2bbcb9e58 Mon Sep 17 00:00:00 2001 From: Koichi ITO Date: Mon, 1 Sep 2025 01:10:15 +0900 Subject: [PATCH 2/2] Validate tool annotations value Tool annotations were introduced in the "2025-03-26" specification: > Added comprehensive tool annotations for better describing tool behavior, > like whether it is read-only or destructive (PR modelcontextprotocol/modelcontextprotocol#185) https://modelcontextprotocol.io/specification/2025-03-26/changelog#major-changes This means they are not supported in the "2024-11-05" specification, so validation errors will be raised for `protocol_version: "2024-11-05"`. --- README.md | 3 +++ lib/mcp/server.rb | 26 ++++++++++++++++++++++---- test/mcp/server_test.rb | 22 ++++++++++++++++++++++ 3 files changed, 47 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 729c7c0..737198c 100644 --- a/README.md +++ b/README.md @@ -448,6 +448,9 @@ 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'`. + ### 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. diff --git a/lib/mcp/server.rb b/lib/mcp/server.rb index 42aa440..f16b3c6 100644 --- a/lib/mcp/server.rb +++ b/lib/mcp/server.rb @@ -59,10 +59,7 @@ module MCP @server_context = server_context @configuration = MCP.configuration.merge(configuration) - if @configuration.protocol_version == "2024-11-05" && @instructions - message = "`instructions` supported by protocol version 2025-03-26 or higher" - raise ArgumentError, message - end + validate! @capabilities = capabilities || default_capabilities @@ -102,6 +99,8 @@ module MCP 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) @tools[tool.name_value] = tool + + validate! end def define_prompt(name: nil, title: nil, description: nil, arguments: [], &block) @@ -171,6 +170,25 @@ module MCP private + def validate! + if @configuration.protocol_version == "2024-11-05" + if @instructions + message = "`instructions` supported by protocol version 2025-03-26 or higher" + raise ArgumentError, message + end + + error_tool_names = @tools.each_with_object([]) do |(tool_name, tool), error_tool_names| + if tool.annotations + error_tool_names << tool_name + end + end + unless error_tool_names.empty? + message = "Error occurred in #{error_tool_names.join(", ")}. `annotations` are supported by protocol version 2025-03-26 or higher" + raise ArgumentError, message + end + end + end + def handle_request(request, method) handler = @handlers[method] unless handler diff --git a/test/mcp/server_test.rb b/test/mcp/server_test.rb index a8527bc..ce6230a 100644 --- a/test/mcp/server_test.rb +++ b/test/mcp/server_test.rb @@ -822,6 +822,28 @@ module MCP assert_equal("`instructions` supported by protocol version 2025-03-26 or higher", exception.message) end + test "server uses annotations when configured with protocol version 2025-03-26" do + configuration = Configuration.new(protocol_version: "2025-03-26") + server = Server.new(name: "test_server", configuration: configuration) + server.define_tool( + name: "defined_tool", + annotations: { title: "test server" }, + ) + assert_equal({ destructiveHint: true, idempotentHint: false, openWorldHint: true, readOnlyHint: false, title: "test server" }, server.tools.first[1].annotations.to_h) + end + + test "raises error if annotations are used with protocol version 2024-11-05" do + configuration = Configuration.new(protocol_version: "2024-11-05") + exception = assert_raises(ArgumentError) do + server = Server.new(name: "test_server", configuration: configuration) + server.define_tool( + name: "defined_tool", + annotations: { title: "test server" }, + ) + end + assert_equal("Error occurred in defined_tool. `annotations` are supported by protocol version 2025-03-26 or higher", exception.message) + end + test "#define_tool adds a tool to the server" do @server.define_tool( name: "defined_tool",