mcp 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 984645dda3d0d04a93b2831354691c475b42d2826462156167a3f1e1104b85d0
-  data.tar.gz: 20f96310129418791e0f5ae7f11b8a67605ff82e7ad29dfdfc414fd24157cf97
+  metadata.gz: 451bdb587fa89621924916d7cc137cf44a3a2293cf7803c3c6af1d97fb57332a
+  data.tar.gz: 3175f6a5d60426d5441b99b2bbf6d50b90d31daa9b713796029547f5efc6ab6a
 SHA512:
-  metadata.gz: e9c323d818625f25999d1a2bb7ed1f16783cc295f8676c47bb58a96c284da133a2a5cc5c17086bc72216783325317543031288f1f8f804165503286ec0b1d2e8
-  data.tar.gz: f0b2c995f44682257a642316c6df3aa20bde04db6de92842e35b323460238860890d3e197cc916ec68f96a57f8c24f12877805fc14b8fd27e46999bf4b3d2aa4
+  metadata.gz: 4b9e312c047ebc31d0826ec2520e14fef34fd0a23f42d9bf849f4a64b8cdb924341aa8a431aab497824849da476de5b8b2d55ad3b3996b9871e04b9022161aa3
+  data.tar.gz: 772762d9cf650278dd0756867a995e57e13366e1a4a2a5b306433d8d9246e8bed2aadb00e057d4f31a521603dab6f8fadcbcdfc9650806c79d9881e2e1913acb

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'

data/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
           - { ruby: head, allowed-failure: true }
     name: Test Ruby ${{ matrix.entry.ruby }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.entry.ruby }}
@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     name: RuboCop
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 3.2 # Specify the oldest supported Ruby version.

data/.github/workflows/release.yml

@@ -16,7 +16,7 @@ jobs:
       id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
       contents: write # IMPORTANT: this permission is required for `rake release` to push the release tag
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:

data/AGENTS.md

@@ -0,0 +1,119 @@
+# AGENTS.md
+
+## Project overview
+
+This is the official Ruby SDK for the Model Context Protocol (MCP), implementing both server and client functionality for JSON-RPC 2.0 based communication between LLM applications and context providers.
+
+## Dev environment setup
+
+- Ruby 3.2.0+ required
+- Run `bundle install` to install dependencies
+- Dependencies: `json_rpc_handler` ~> 0.1, `json-schema` >= 4.1
+
+## Build and test commands
+
+- `bundle install` - Install dependencies
+- `rake test` - Run all tests
+- `rake rubocop` - Run linter
+- `rake` - Run tests and linting (default task)
+- `ruby -I lib -I test test/path/to/specific_test.rb` - Run single test file
+- `gem build mcp.gemspec` - Build the gem
+
+## Testing instructions
+
+- Test files are in `test/` directory with `_test.rb` suffix
+- Run full test suite with `rake test`
+- Run individual tests with `ruby -I lib -I test test/path/to/file_test.rb`
+- Tests should pass before submitting PRs
+
+## Code style guidelines
+
+- Follow RuboCop rules (run `rake rubocop`)
+- Use frozen string literals
+- Follow Ruby community conventions
+- Keep dependencies minimal
+
+## Commit message conventions
+
+- Use conventional commit format when possible
+- Include clear, descriptive commit messages
+- Releases are triggered by updating version in `lib/mcp/version.rb` and merging to main
+
+## Release process
+
+- Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format in CHANGELOG.md
+- Update CHANGELOG.md before cutting releases
+- Use git history and PR merge commits to construct changelog entries
+- Format entries as: "Terse description of the change (#nnn)"
+- Keep entries in flat list format (no nesting)
+- Git tags mark commits that cut new releases
+- Exclude maintenance PRs that don't concern end users
+- Check upstream remote for PRs if available
+
+## Architecture overview
+
+### Core Components
+
+**MCP::Server** (`lib/mcp/server.rb`):
+
+- Main server class handling JSON-RPC requests
+- Implements MCP protocol methods: initialize, ping, tools/list, tools/call, prompts/list, prompts/get, resources/list, resources/read
+- Supports custom method registration via `define_custom_method`
+- Handles instrumentation, exception reporting, and notifications
+- Uses JsonRpcHandler for request processing
+
+**MCP::Client** (`lib/mcp/client.rb`):
+
+- Client interface for communicating with MCP servers
+- Transport-agnostic design with pluggable transport layers
+- Supports tool listing and invocation
+
+**Transport Layer**:
+
+- `MCP::Server::Transports::StdioTransport` - Command-line stdio transport
+- `MCP::Server::Transports::StreamableHttpTransport` - HTTP with streaming support
+- `MCP::Client::HTTP` - HTTP client transport (requires faraday gem)
+
+**Protocol Components**:
+
+- `MCP::Tool` - Tool definition with input/output schemas and annotations
+- `MCP::Prompt` - Prompt templates with argument validation
+- `MCP::Resource` - Resource registration and retrieval
+- `MCP::Configuration` - Global configuration with exception reporting and instrumentation
+
+### Key Patterns
+
+**Three Ways to Define Components**:
+
+1. Class inheritance (e.g., `class MyTool < MCP::Tool`)
+2. Define methods (e.g., `MCP::Tool.define(name: "my_tool") { ... }`)
+3. Server registration (e.g., `server.define_tool(name: "my_tool") { ... }`)
+
+**Schema Validation**:
+
+- Tools support input_schema and output_schema for JSON Schema validation
+- Protocol version 2025-03-26+ supports tool annotations (destructive_hint, idempotent_hint, etc.)
+- Validation is configurable via `configuration.validate_tool_call_arguments`
+
+**Context Passing**:
+
+- `server_context` hash passed through tool/prompt calls for request-specific data
+- Methods can accept `server_context:` keyword argument for accessing context
+
+### Dependencies
+
+- `json_rpc_handler` ~> 0.1 - JSON-RPC 2.0 message handling
+- `json-schema` >= 4.1 - Schema validation
+- Ruby 3.2.0+ required
+
+### Integration patterns
+
+- **Rails controllers**: Use `server.handle_json(request.body.read)` for HTTP endpoints
+- **Command-line tools**: Use `StdioTransport.new(server).open` for CLI applications
+- **HTTP services**: Use `StreamableHttpTransport` for web-based servers
+
+### Component definition patterns
+
+1. **Class inheritance**: `class MyTool < MCP::Tool`
+2. **Define methods**: `MCP::Tool.define(name: "my_tool") { ... }`
+3. **Server registration**: `server.define_tool(name: "my_tool") { ... }`

data/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2025-10-15
+
+### Added
+
+- Client resources support with `resources/list` and `resources/read` methods (#160)
+- `_meta` field support for Tool schema (#124)
+- `_meta` field support for Prompt
+- `title` field support for prompt arguments
+- `call_tool_raw` method to client for accessing full tool responses (#149)
+- Structured content support in tool responses (#147)
+- AGENTS.md development guidance documentation (#134)
+- Dependabot configuration for automated dependency updates (#138)
+
+### Changed
+
+- Set default `content` to empty array instead of `nil` (#150)
+- Improved prompt spec compliance (#153)
+- Allow output schema to be array of objects (#144)
+- Return 202 response code for accepted JSON-RPC notifications (#114)
+- Added validation to `MCP::Configuration` setters (#145)
+- Updated metaschema URI format for cross-OS compatibility
+
+### Fixed
+
+- Client tools functionality and test coverage (#166)
+- Client resources test for empty responses (#162)
+- Documentation typos and incorrect examples (#157, #146)
+- Removed redundant transport requires (#154)
+- Cleaned up unused block parameters and magic comments
+
 ## [0.3.0] - 2025-09-14
 
 ### Added

data/README.md

@@ -131,7 +131,7 @@ Notifications follow the JSON-RPC 2.0 specification and use these method names:
 
 ```ruby
 server = MCP::Server.new(name: "my_server")
-transport = MCP::Transports::HTTP.new(server)
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
 server.transport = transport
 
 # When tools change, notify clients
@@ -178,7 +178,6 @@ If you want to build a local command-line application, you can use the stdio tra
 
 ```ruby
 require "mcp"
-require "mcp/server/transports/stdio_transport"
 
 # Create a simple tool
 class ExampleTool < MCP::Tool
@@ -425,10 +424,10 @@ tool = MCP::Tool.define(
 end
 ```
 
-3. By using the `ModelContextProtocol::Server#define_tool` method with a block:
+3. By using the `MCP::Server#define_tool` method with a block:
 
 ```ruby
-server = ModelContextProtocol::Server.new
+server = MCP::Server.new
 server.define_tool(
   name: "my_tool",
   description: "This tool performs specific functionality...",
@@ -546,6 +545,27 @@ class DataTool < MCP::Tool
 end
 ```
 
+Output schema may also describe an array of objects:
+
+```ruby
+class WeatherTool < MCP::Tool
+  output_schema(
+    type: "array",
+    item: {
+      properties: {
+        temperature: { type: "number" },
+        condition: { type: "string" },
+        humidity: { type: "integer" }
+      },
+      required: ["temperature", "condition", "humidity"]
+    }
+  )
+end
+```
+
+Please note: in this case, you must provide `type: "array"`. The default type
+for output schemas is `object`.
+
 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
@@ -555,6 +575,38 @@ MCP spec for the [Output Schema](https://modelcontextprotocol.io/specification/2
 
 The output schema follows standard JSON Schema format and helps ensure consistent data exchange between MCP servers and clients.
 
+### Tool Responses with Structured Content
+
+Tools can return structured data alongside text content using the `structured_content` parameter.
+
+The structured content will be included in the JSON-RPC response as the `structuredContent` field.
+
+```ruby
+class APITool < MCP::Tool
+  description "Get current weather and return structured data"
+
+  def self.call(endpoint:, 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
+      }],
+      structured_content: weather_data
+    )
+  end
+end
+```
+
 ### 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.
@@ -571,10 +623,12 @@ class MyPrompt < MCP::Prompt
   arguments [
     MCP::Prompt::Argument.new(
       name: "message",
+      title: "Message Title",
       description: "Input message",
       required: true
     )
   ]
+  meta({ version: "1.0", category: "example" })
 
   class << self
     def template(args, server_context:)
@@ -608,10 +662,12 @@ prompt = MCP::Prompt.define(
   arguments: [
     MCP::Prompt::Argument.new(
       name: "message",
+      title: "Message Title",
       description: "Input message",
       required: true
     )
-  ]
+  ],
+  meta: { version: "1.0", category: "example" }
 ) do |args, server_context:|
   MCP::Prompt::Result.new(
     description: "Response description",
@@ -629,20 +685,22 @@ prompt = MCP::Prompt.define(
 end
 ```
 
-3. Using the `ModelContextProtocol::Server#define_protocol` method:
+3. Using the `MCP::Server#define_prompt` method:
 
 ```ruby
-server = ModelContextProtocol::Server.new
-server.define_protocol(
+server = MCP::Server.new
+server.define_prompt(
   name: "my_prompt",
   description: "This prompt performs specific functionality...",
   arguments: [
     Prompt::Argument.new(
       name: "message",
+      title: "Message Title",
       description: "Input message",
       required: true
     )
-  ]
+  ],
+  meta: { version: "1.0", category: "example" }
 ) do |args, server_context:|
   Prompt::Result.new(
     description: "Response description",
@@ -665,7 +723,7 @@ e.g. around authentication state or user preferences.
 
 ### Key Components
 
-- `MCP::Prompt::Argument` - Defines input parameters for the prompt template
+- `MCP::Prompt::Argument` - Defines input parameters for the prompt template with name, title, description, and required flag
 - `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
@@ -774,8 +832,10 @@ 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
+- Tool listing via the `tools/list` method (`MCP::Client#tools`)
+- Tool invocation via the `tools/call` method (`MCP::Client#call_tools`)
+- Resource listing via the `resources/list` method (`MCP::Client#resources`)
+- Resource reading via the `resources/read` method (`MCP::Client#read_resources`)
 - Automatic JSON-RPC 2.0 message formatting
 - UUID request ID generation
 

data/examples/http_server.rb

@@ -2,7 +2,6 @@
 
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "mcp"
-require "mcp/server/transports/streamable_http_transport"
 require "rack"
 require "rackup"
 require "json"

data/examples/stdio_server.rb

@@ -2,7 +2,6 @@
 
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "mcp"
-require "mcp/server/transports/stdio_transport"
 
 # Create a simple tool
 class ExampleTool < MCP::Tool

data/examples/streamable_http_server.rb

@@ -2,7 +2,6 @@
 
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "mcp"
-require "mcp/server/transports/streamable_http_transport"
 require "rack"
 require "rackup"
 require "json"

data/lib/mcp/client.rb

@@ -44,28 +44,56 @@ module MCP
       end || []
     end
 
-    # Calls a tool via the transport layer.
+    # Returns the list of resources available from the server.
+    # Each call will make a new request – the result is not cached.
+    #
+    # @return [Array<Hash>] An array of available resources.
+    def resources
+      response = transport.send_request(request: {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: "resources/list",
+      })
+
+      response.dig("result", "resources") || []
+    end
+
+    # Calls a tool via the transport layer and returns the full response from the server.
     #
     # @param tool [MCP::Client::Tool] The tool to be called.
     # @param arguments [Object, nil] The arguments to pass to the tool.
-    # @return [Object] The result of the tool call, as returned by the transport.
+    # @return [Hash] The full JSON-RPC response from the transport.
     #
     # @example
     #   tool = client.tools.first
-    #   result = client.call_tool(tool: tool, arguments: { foo: "bar" })
+    #   response = client.call_tool(tool: tool, arguments: { foo: "bar" })
+    #   structured_content = response.dig("result", "structuredContent")
     #
     # @note
     #   The exact requirements for `arguments` are determined by the transport layer in use.
     #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
     def call_tool(tool:, arguments: nil)
-      response = transport.send_request(request: {
+      transport.send_request(request: {
         jsonrpc: JsonRpcHandler::Version::V2_0,
         id: request_id,
         method: "tools/call",
         params: { name: tool.name, arguments: arguments },
       })
+    end
+
+    # Reads a resource from the server by URI and returns the contents.
+    #
+    # @param uri [String] The URI of the resource to read.
+    # @return [Array<Hash>] An array of resource contents (text or blob).
+    def read_resource(uri:)
+      response = transport.send_request(request: {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: "resources/read",
+        params: { uri: uri },
+      })
 
-      response.dig("result", "content")
+      response.dig("result", "contents") || []
     end
 
     private

data/lib/mcp/configuration.rb

@@ -5,20 +5,29 @@ module MCP
     DEFAULT_PROTOCOL_VERSION = "2025-06-18"
     SUPPORTED_PROTOCOL_VERSIONS = [DEFAULT_PROTOCOL_VERSION, "2025-03-26", "2024-11-05"]
 
-    attr_writer :exception_reporter, :instrumentation_callback, :protocol_version, :validate_tool_call_arguments
+    attr_writer :exception_reporter, :instrumentation_callback
 
     def initialize(exception_reporter: nil, instrumentation_callback: nil, protocol_version: nil,
       validate_tool_call_arguments: true)
       @exception_reporter = exception_reporter
       @instrumentation_callback = instrumentation_callback
       @protocol_version = protocol_version
-      if protocol_version && !SUPPORTED_PROTOCOL_VERSIONS.include?(protocol_version)
-        message = "protocol_version must be #{SUPPORTED_PROTOCOL_VERSIONS[0...-1].join(", ")}, or #{SUPPORTED_PROTOCOL_VERSIONS[-1]}"
-        raise ArgumentError, message
-      end
-      unless validate_tool_call_arguments.is_a?(TrueClass) || validate_tool_call_arguments.is_a?(FalseClass)
-        raise ArgumentError, "validate_tool_call_arguments must be a boolean"
+      if protocol_version
+        validate_protocol_version!(protocol_version)
       end
+      validate_value_of_validate_tool_call_arguments!(validate_tool_call_arguments)
+
+      @validate_tool_call_arguments = validate_tool_call_arguments
+    end
+
+    def protocol_version=(protocol_version)
+      validate_protocol_version!(protocol_version)
+
+      @protocol_version = protocol_version
+    end
+
+    def validate_tool_call_arguments=(validate_tool_call_arguments)
+      validate_value_of_validate_tool_call_arguments!(validate_tool_call_arguments)
 
       @validate_tool_call_arguments = validate_tool_call_arguments
     end
@@ -83,6 +92,19 @@ module MCP
 
     private
 
+    def validate_protocol_version!(protocol_version)
+      unless SUPPORTED_PROTOCOL_VERSIONS.include?(protocol_version)
+        message = "protocol_version must be #{SUPPORTED_PROTOCOL_VERSIONS[0...-1].join(", ")}, or #{SUPPORTED_PROTOCOL_VERSIONS[-1]}"
+        raise ArgumentError, message
+      end
+    end
+
+    def validate_value_of_validate_tool_call_arguments!(validate_tool_call_arguments)
+      unless validate_tool_call_arguments.is_a?(TrueClass) || validate_tool_call_arguments.is_a?(FalseClass)
+        raise ArgumentError, "validate_tool_call_arguments must be a boolean"
+      end
+    end
+
     def default_exception_reporter
       @default_exception_reporter ||= ->(exception, server_context) {}
     end

data/lib/mcp/content.rb

@@ -1,4 +1,3 @@
-# typed: true
 # frozen_string_literal: true
 
 module MCP

data/lib/mcp/prompt/argument.rb

@@ -1,20 +1,24 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP
   class Prompt
     class Argument
-      attr_reader :name, :description, :required, :arguments
+      attr_reader :name, :title, :description, :required
 
-      def initialize(name:, description: nil, required: false)
+      def initialize(name:, title: nil, description: nil, required: false)
         @name = name
+        @title = title
         @description = description
         @required = required
-        @arguments = arguments
       end
 
       def to_h
-        { name:, description:, required: }.compact
+        {
+          name: name,
+          title: title,
+          description: description,
+          required: required,
+        }.compact
       end
     end
   end

data/lib/mcp/prompt/message.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP

data/lib/mcp/prompt/result.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP

data/lib/mcp/prompt.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP
@@ -9,13 +8,20 @@ module MCP
       attr_reader :title_value
       attr_reader :description_value
       attr_reader :arguments_value
+      attr_reader :meta_value
 
       def template(args, server_context: nil)
         raise NotImplementedError, "Subclasses must implement template"
       end
 
       def to_h
-        { name: name_value, title: title_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),
+          _meta: meta_value,
+        }.compact
       end
 
       def inherited(subclass)
@@ -24,6 +30,7 @@ module MCP
         subclass.instance_variable_set(:@title_value, nil)
         subclass.instance_variable_set(:@description_value, nil)
         subclass.instance_variable_set(:@arguments_value, nil)
+        subclass.instance_variable_set(:@meta_value, nil)
       end
 
       def prompt_name(value = NOT_SET)
@@ -62,7 +69,15 @@ module MCP
         end
       end
 
-      def define(name: nil, title: nil, description: nil, arguments: [], &block)
+      def meta(value = NOT_SET)
+        if value == NOT_SET
+          @meta_value
+        else
+          @meta_value = value
+        end
+      end
+
+      def define(name: nil, title: nil, description: nil, arguments: [], meta: nil, &block)
         Class.new(self) do
           prompt_name name
           title title
@@ -71,6 +86,7 @@ module MCP
           define_singleton_method(:template) do |args, server_context: nil|
             instance_exec(args, server_context:, &block)
           end
+          meta meta
         end
       end
 

data/lib/mcp/resource/contents.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP

data/lib/mcp/resource/embedded.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP

data/lib/mcp/resource.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP

data/lib/mcp/resource_template.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP

data/lib/mcp/server/transports/streamable_http_transport.rb

@@ -108,8 +108,8 @@ module MCP
 
           if body["method"] == "initialize"
             handle_initialization(body_string, body)
-          elsif body["method"] == MCP::Methods::NOTIFICATIONS_INITIALIZED
-            handle_notification_initialized
+          elsif notification?(body) || response?(body)
+            handle_accepted
           else
             handle_regular_request(body_string, session_id)
           end
@@ -168,6 +168,14 @@ module MCP
           [400, { "Content-Type" => "application/json" }, [{ error: "Invalid JSON" }.to_json]]
         end
 
+        def notification?(body)
+          !body["id"] && !!body["method"]
+        end
+
+        def response?(body)
+          !!body["id"] && !body["method"]
+        end
+
         def handle_initialization(body_string, body)
           session_id = SecureRandom.uuid
 
@@ -187,7 +195,7 @@ module MCP
           [200, headers, [response]]
         end
 
-        def handle_notification_initialized
+        def handle_accepted
           [202, {}, []]
         end
 

data/lib/mcp/server.rb

@@ -96,8 +96,8 @@ module MCP
       end
     end
 
-    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)
+    def define_tool(name: nil, title: nil, description: nil, input_schema: nil, annotations: nil, meta: nil, &block)
+      tool = Tool.define(name:, title:, description:, input_schema:, annotations:, meta:, &block)
       @tools[tool.name_value] = tool
 
       validate!
@@ -253,7 +253,7 @@ module MCP
     end
 
     def list_tools(request)
-      @tools.map { |_, tool| tool.to_h }
+      @tools.values.map(&:to_h)
     end
 
     def call_tool(request)
@@ -293,7 +293,7 @@ module MCP
     end
 
     def list_prompts(request)
-      @prompts.map { |_, prompt| prompt.to_h }
+      @prompts.values.map(&:to_h)
     end
 
     def get_prompt(request)

data/lib/mcp/string_utils.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module MCP

data/lib/mcp/tool/input_schema.rb

@@ -50,7 +50,10 @@ module MCP
           accept_uri: false,
           accept_file: ->(path) { path.to_s.start_with?(Gem.loaded_specs["json-schema"].full_gem_path) },
         )
-        metaschema = JSON::Validator.validator_for_name("draft4").metaschema
+        metaschema_path = Pathname.new(JSON::Validator.validator_for_name("draft4").metaschema)
+        # Converts metaschema to a file URI for cross-platform compatibility
+        metaschema_uri = JSON::Util::URI.file_uri(metaschema_path.expand_path.cleanpath.to_s.tr("\\", "/"))
+        metaschema = metaschema_uri.to_s
         errors = JSON::Validator.fully_validate(metaschema, schema, schema_reader: schema_reader)
         if errors.any?
           raise ArgumentError, "Invalid JSON Schema: #{errors.join(", ")}"

data/lib/mcp/tool/output_schema.rb

@@ -7,23 +7,20 @@ module MCP
     class OutputSchema
       class ValidationError < StandardError; end
 
-      attr_reader :properties, :required
+      attr_reader :schema
 
-      def initialize(properties: {}, required: [])
-        @properties = properties
-        @required = required.map(&:to_sym)
+      def initialize(schema = {})
+        @schema = deep_transform_keys(JSON.parse(JSON.dump(schema)), &:to_sym)
+        @schema[:type] ||= "object"
         validate_schema!
       end
 
       def ==(other)
-        other.is_a?(OutputSchema) && properties == other.properties && required == other.required
+        other.is_a?(OutputSchema) && schema == other.schema
       end
 
       def to_h
-        { type: "object" }.tap do |hsh|
-          hsh[:properties] = properties if properties.any?
-          hsh[:required] = required if required.any?
-        end
+        @schema
       end
 
       def validate_result(result)
@@ -35,32 +32,38 @@ module MCP
 
       private
 
+      def deep_transform_keys(schema, &block)
+        case schema
+        when Hash
+          schema.each_with_object({}) do |(key, value), result|
+            if key.casecmp?("$ref")
+              raise ArgumentError, "Invalid JSON Schema: $ref is not allowed in tool output schemas"
+            end
+
+            result[yield(key)] = deep_transform_keys(value, &block)
+          end
+        when Array
+          schema.map { |e| deep_transform_keys(e, &block) }
+        else
+          schema
+        end
+      end
+
       def validate_schema!
-        check_for_refs!
         schema = to_h
         schema_reader = JSON::Schema::Reader.new(
           accept_uri: false,
           accept_file: ->(path) { path.to_s.start_with?(Gem.loaded_specs["json-schema"].full_gem_path) },
         )
-        metaschema = JSON::Validator.validator_for_name("draft4").metaschema
+        metaschema_path = Pathname.new(JSON::Validator.validator_for_name("draft4").metaschema)
+        # Converts metaschema to a file URI for cross-platform compatibility
+        metaschema_uri = JSON::Util::URI.file_uri(metaschema_path.expand_path.cleanpath.to_s.tr("\\", "/"))
+        metaschema = metaschema_uri.to_s
         errors = JSON::Validator.fully_validate(metaschema, schema, schema_reader: schema_reader)
         if errors.any?
           raise ArgumentError, "Invalid JSON Schema: #{errors.join(", ")}"
         end
       end
-
-      def check_for_refs!(obj = properties)
-        case obj
-        when Hash
-          if obj.key?("$ref") || obj.key?(:$ref)
-            raise ArgumentError, "Invalid JSON Schema: $ref is not allowed in tool output schemas"
-          end
-
-          obj.each_value { |value| check_for_refs!(value) }
-        when Array
-          obj.each { |item| check_for_refs!(item) }
-        end
-      end
     end
   end
 end

data/lib/mcp/tool/response.rb

@@ -5,16 +5,17 @@ module MCP
     class Response
       NOT_GIVEN = Object.new.freeze
 
-      attr_reader :content
+      attr_reader :content, :structured_content
 
-      def initialize(content, deprecated_error = NOT_GIVEN, error: false)
+      def initialize(content = nil, deprecated_error = NOT_GIVEN, error: false, structured_content: nil)
         if deprecated_error != NOT_GIVEN
           warn("Passing `error` with the 2nd argument of `Response.new` is deprecated. Use keyword argument like `Response.new(content, error: error)` instead.", uplevel: 1)
           error = deprecated_error
         end
 
-        @content = content
+        @content = content || []
         @error = error
+        @structured_content = structured_content
       end
 
       def error?
@@ -22,7 +23,7 @@ module MCP
       end
 
       def to_h
-        { content:, isError: error? }.compact
+        { content:, isError: error?, structuredContent: @structured_content }.compact
       end
     end
   end

data/lib/mcp/tool.rb

@@ -8,6 +8,7 @@ module MCP
       attr_reader :title_value
       attr_reader :description_value
       attr_reader :annotations_value
+      attr_reader :meta_value
 
       def call(*args, server_context: nil)
         raise NotImplementedError, "Subclasses must implement call"
@@ -21,6 +22,7 @@ module MCP
           inputSchema: input_schema_value.to_h,
           outputSchema: @output_schema_value&.to_h,
           annotations: annotations_value&.to_h,
+          _meta: meta_value,
         }.compact
       end
 
@@ -32,6 +34,7 @@ module MCP
         subclass.instance_variable_set(:@input_schema_value, nil)
         subclass.instance_variable_set(:@output_schema_value, nil)
         subclass.instance_variable_set(:@annotations_value, nil)
+        subclass.instance_variable_set(:@meta_value, nil)
       end
 
       def tool_name(value = NOT_SET)
@@ -84,14 +87,20 @@ module MCP
         if value == NOT_SET
           output_schema_value
         elsif value.is_a?(Hash)
-          properties = value[:properties] || value["properties"] || {}
-          required = value[:required] || value["required"] || []
-          @output_schema_value = OutputSchema.new(properties:, required:)
+          @output_schema_value = OutputSchema.new(value)
         elsif value.is_a?(OutputSchema)
           @output_schema_value = value
         end
       end
 
+      def meta(value = NOT_SET)
+        if value == NOT_SET
+          @meta_value
+        else
+          @meta_value = value
+        end
+      end
+
       def annotations(hash = NOT_SET)
         if hash == NOT_SET
           @annotations_value
@@ -100,12 +109,13 @@ module MCP
         end
       end
 
-      def define(name: nil, title: nil, description: nil, input_schema: nil, output_schema: nil, annotations: nil, &block)
+      def define(name: nil, title: nil, description: nil, input_schema: nil, output_schema: nil, meta: nil, annotations: nil, &block)
         Class.new(self) do
           tool_name name
           title title
           description description
           input_schema input_schema
+          meta meta
           output_schema output_schema
           self.annotations(annotations) if annotations
           define_singleton_method(:call, &block) if block

data/lib/mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MCP
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -44,12 +44,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".cursor/rules/release-changelogs.mdc"
 - ".gitattributes"
+- ".github/dependabot.yml"
 - ".github/workflows/ci.yml"
 - ".github/workflows/release.yml"
 - ".gitignore"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile

data/.cursor/rules/release-changelogs.mdc

@@ -1,17 +0,0 @@
----
-description: Updating CHANGELOG.md before cutting a new release of the gem
-globs: CHANGELOG.md
-alwaysApply: false
----
-
-- start by refreshing your knowledge on the Keep a Changelog convention by reading the format spec referenced at the top of CHANGELOG.md
-- stick to Keep a Changelog
-- entries should be terse and in a top-level flat list: do not nest
-- follow this format for entries:
-  - Terse description of the change (#nnn)
-- git tags are used to mark the commit that cut a new release of the gem
-- the gem version is located in [version.rb](mdc:lib/mcp/version.rb)
-- use the git history, especially merge commits from PRs to construct the changelog
-- when necessary, look at the diff of files changed to determine the true nature of the change
-- maintenance PRs that don't concern end users of the gem should not be listed in the changelog
-- when checking PRs, see if there's an upstream remote, and if so, fetch PRs from upstream instead of origin