mcp 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b72cdaffe97298a6d6d8b88973b4ea2236909dfb9bf46cc6694ae9331a102a5a
-  data.tar.gz: dbab122901fa44329aa03d355fcf35df70087ab88a3f919100740d46261b1319
+  metadata.gz: 984645dda3d0d04a93b2831354691c475b42d2826462156167a3f1e1104b85d0
+  data.tar.gz: 20f96310129418791e0f5ae7f11b8a67605ff82e7ad29dfdfc414fd24157cf97
 SHA512:
-  metadata.gz: 4f3200c4d2520fa6b1c720b7e1547be5cbaea15d2ba76f8491dedd5ef840f8fae59017cd3ea965796c7cda0ab353e78579291e3f3559250412ae9f1f901eb0b7
-  data.tar.gz: 91c4dff59524cd390a2cfc92921862cb1dc9446b483b699d7ac722a40438716c56c494b34d84d211aeafd4fc152fcfaf9ae10c354c1c3c104c27ca0a0f4f83a1
+  metadata.gz: e9c323d818625f25999d1a2bb7ed1f16783cc295f8676c47bb58a96c284da133a2a5cc5c17086bc72216783325317543031288f1f8f804165503286ec0b1d2e8
+  data.tar.gz: f0b2c995f44682257a642316c6df3aa20bde04db6de92842e35b323460238860890d3e197cc916ec68f96a57f8c24f12877805fc14b8fd27e46999bf4b3d2aa4

data/.rubocop.yml

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

data/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

data/Gemfile

@@ -6,10 +6,6 @@ source "https://rubygems.org"
 gemspec
 
 # Specify development dependencies below
-gem "minitest", "~> 5.1", require: false
-gem "minitest-reporters"
-gem "mocha"
-
 gem "rubocop-minitest", require: false
 gem "rubocop-rake", require: false
 gem "rubocop-shopify", require: false
@@ -22,3 +18,10 @@ gem "activesupport"
 gem "debug"
 gem "rake", "~> 13.0"
 gem "sorbet-static-and-runtime"
+
+group :test do
+  gem "faraday", ">= 2.0"
+  gem "minitest", "~> 5.1", require: false
+  gem "mocha"
+  gem "webmock"
+end

data/README.md

@@ -22,7 +22,9 @@ Or install it yourself as:
 $ gem install mcp
 ```
 
-## MCP Server
+You may need to add additional dependencies depending on which features you wish to access.
+
+## Building an MCP Server
 
 The `MCP::Server` class is the core component that handles JSON-RPC requests and responses.
 It implements the Model Context Protocol specification, handling model context requests and responses.
@@ -108,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
 
@@ -122,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
 
@@ -134,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 )
@@ -148,18 +150,19 @@ server.notify_tools_list_changed()
 #### Rails Controller
 
 When added to a Rails controller on a route that handles POST requests, your server will be compliant with non-streaming
-[Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport
+[Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport
 requests.
 
 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",
+      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],
       prompts: [MyPrompt],
       server_context: { user_id: current_user.id },
@@ -214,9 +217,10 @@ 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
+### Configuration
 
 The gem can be configured using the `MCP.configure` block:
 
@@ -326,19 +330,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)
 ```
 
-Be sure to check the [MCP spec](https://modelcontextprotocol.io/specification/2025-03-26) for the protocol version to understand the supported features for the version being set.
+If an invalid `protocol_version` value is set, an `ArgumentError` is raised.
+
+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
 
@@ -360,16 +367,17 @@ When an exception occurs:
 
 If no exception reporter is configured, a default no-op reporter is used that silently ignores exceptions.
 
-## Tools
+### 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:
+This gem provides a `MCP::Tool` class that can be used to create tools in three 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: {
@@ -377,12 +385,20 @@ 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(
-    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:)
@@ -397,6 +413,23 @@ 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: {
+    read_only_hint: true,
+    title: "My Tool"
+  }
+) do |args, server_context|
+  MCP::Tool::Response.new([{ type: "text", text: "OK" }])
+end
+```
+
+3. By using the `ModelContextProtocol::Server#define_tool` method with a block:
+
+```ruby
+server = ModelContextProtocol::Server.new
+server.define_tool(
   name: "my_tool",
   description: "This tool performs specific functionality...",
   annotations: {
@@ -415,28 +448,128 @@ 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. 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
-- `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
 
 Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
 
-## Prompts
+> [!NOTE]
+> This **Tool Annotations** feature is supported starting from `protocol_version: '2025-03-26'`.
 
-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.
+### 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
+```
 
-The `MCP::Prompt` class provides two ways to create prompts:
+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.
+
+The `MCP::Prompt` class provides three ways to create prompts:
 
 1. As a class definition with metadata:
 
 ```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 [
-    Prompt::Argument.new(
+    MCP::Prompt::Argument.new(
       name: "message",
       description: "Input message",
       required: true
@@ -445,16 +578,16 @@ class MyPrompt < MCP::Prompt
 
   class << self
     def template(args, server_context:)
-      Prompt::Result.new(
+      MCP::Prompt::Result.new(
         description: "Response description",
         messages: [
-          Prompt::Message.new(
+          MCP::Prompt::Message.new(
             role: "user",
-            content: Content::Text.new("User message")
+            content: MCP::Content::Text.new("User message")
           ),
-          Prompt::Message.new(
+          MCP::Prompt::Message.new(
             role: "assistant",
-            content: Content::Text.new(args["message"])
+            content: MCP::Content::Text.new(args["message"])
           )
         ]
       )
@@ -469,6 +602,38 @@ 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(
+      name: "message",
+      description: "Input message",
+      required: true
+    )
+  ]
+) do |args, server_context:|
+  MCP::Prompt::Result.new(
+    description: "Response description",
+    messages: [
+      MCP::Prompt::Message.new(
+        role: "user",
+        content: MCP::Content::Text.new("User message")
+      ),
+      MCP::Prompt::Message.new(
+        role: "assistant",
+        content: MCP::Content::Text.new(args["message"])
+      )
+    ]
+  )
+end
+```
+
+3. Using the `ModelContextProtocol::Server#define_protocol` method:
+
+```ruby
+server = ModelContextProtocol::Server.new
+server.define_protocol(
   name: "my_prompt",
   description: "This prompt performs specific functionality...",
   arguments: [
@@ -500,10 +665,10 @@ e.g. around authentication state or user preferences.
 
 ### Key Components
 
-- `Prompt::Argument` - Defines input parameters for the prompt template
-- `Prompt::Message` - Represents a message in the conversation with a role and content
-- `Prompt::Result` - The output of a prompt template containing description and messages
-- `Content::Text` - Text content for messages
+- `MCP::Prompt::Argument` - Defines input parameters for the prompt template
+- `MCP::Prompt::Message` - Represents a message in the conversation with a role and content
+- `MCP::Prompt::Result` - The output of a prompt template containing description and messages
+- `MCP::Content::Text` - Text content for messages
 
 ### Usage
 
@@ -536,26 +701,30 @@ end
 ```
 
 The data contains the following keys:
-`method`: the metod 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
+### Resources
 
-MCP spec includes [Resources](https://modelcontextprotocol.io/docs/concepts/resources)
+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
 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",
 )
@@ -573,14 +742,128 @@ server.resources_read_handler do |params|
   [{
     uri: params[:uri],
     mimeType: "text/plain",
-    text: params[:uri],
+    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.
+
+This class supports:
+
+- Tool listing via the `tools/list` method
+- Tool invocation via the `tools/call` method
+- Automatic JSON-RPC 2.0 message formatting
+- UUID request ID generation
+
+Clients are initialized with a transport layer instance that handles the low-level communication mechanics.
+Authorization is handled by the transport layer.
+
+## Transport Layer Interface
+
+If the transport layer you need is not included in the gem, you can build and pass your own instances so long as they conform to the following interface:
+
+```ruby
+class CustomTransport
+  # Sends a JSON-RPC request to the server and returns the raw response.
+  #
+  # @param request [Hash] A complete JSON-RPC request object.
+  #     https://www.jsonrpc.org/specification#request_object
+  # @return [Hash] A hash modeling a JSON-RPC response object.
+  #     https://www.jsonrpc.org/specification#response_object
+  def send_request(request:)
+    # Your transport-specific logic here
+    # - HTTP: POST to endpoint with JSON body
+    # - WebSocket: Send message over WebSocket
+    # - stdio: Write to stdout, read from stdin
+    # - etc.
+  end
+end
+```
+
+### HTTP Transport Layer
+
+Use the `MCP::Client::HTTP` transport to interact with MCP servers using simple HTTP requests.
+
+You'll need to add `faraday` as a dependency in order to use the HTTP transport layer:
+
+```ruby
+gem 'mcp'
+gem 'faraday', '>= 2.0'
+```
+
+Example usage:
+
+```ruby
+http_transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp")
+client = MCP::Client.new(transport: http_transport)
+
+# List available tools
+tools = client.tools
+tools.each do |tool|
+  puts <<~TOOL_INFORMATION
+    Tool: #{tool.name}
+    Description: #{tool.description}
+    Input Schema: #{tool.input_schema}
+  TOOL_INFORMATION
+end
+
+# Call a specific tool
+response = client.call_tool(
+  tool: tools.first,
+  arguments: { message: "Hello, world!" }
+)
+```
+
+#### HTTP Authorization
+
+By default, the HTTP transport layer provides no authentication to the server, but you can provide custom headers if you need authentication. For example, to use Bearer token authentication:
+
+```ruby
+http_transport = MCP::Client::HTTP.new(
+  url: "https://api.example.com/mcp",
+  headers: {
+    "Authorization" => "Bearer my_token"
+  }
+)
+
+client = MCP::Client.new(transport: http_transport)
+client.tools # will make the call using Bearer auth
+```
+
+You can add any custom headers needed for your authentication scheme, or for any other purpose. The client will include these headers on every request.
+
+### Tool Objects
+
+The client provides a wrapper class for tools returned by the server:
+
+- `MCP::Client::Tool` - Represents a single tool with its metadata
+
+This class provides easy access to tool properties like name, description, input schema, and output schema.
+
 ## Releases
 
 This gem is published to [RubyGems.org](https://rubygems.org/gems/mcp)