mcp 0.3.0 → 0.5.0

data/RELEASE.md

@@ -0,0 +1,12 @@
+## Releases
+
+This gem is published to [RubyGems.org](https://rubygems.org/gems/mcp)
+
+Releases are triggered by PRs to the `main` branch updating the version number in `lib/mcp/version.rb`.
+
+1. **Update the version number** in `lib/mcp/version.rb`, following [semver](https://semver.org/)
+2. **Update CHANGELOG.md**, backfilling the changes since the last release if necessary, and adding a new section for the new version, clearing out the Unreleased section
+3. **Create a PR and get approval from a maintainer**
+4. **Merge your PR to the main branch** - This will automatically trigger the release workflow via GitHub Actions
+
+When changes are merged to the `main` branch, the GitHub Actions workflow (`.github/workflows/release.yml`) is triggered and the gem is published to RubyGems.

data/bin/generate-gh-pages.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+set -e
+
+# Generates versioned documentation links and commits to gh-pages branch
+#
+# PURPOSE:
+#   This script generates a landing page with links to API documentation on
+#   RubyDoc.info for a specific version tag. This script is invoked by the
+#   publish-gh-pages job in the GitHub Actions workflow
+#   (.github/workflows/release.yml) when a release is published.
+#
+# HOW IT WORKS:
+#   - Creates isolated git worktrees for the specified tag and gh-pages branch
+#   - Copies static Jekyll template files from docs/
+#   - Generates _data/versions.yml with list of versions
+#   - Commits changes to gh-pages (does not push automatically)
+#
+# WORKFLOW:
+#   1. Run this script with a tag name: `generate-gh-pages.sh v1.2.3`
+#   2. Script generates docs and commits to local gh-pages branch
+#   3. Push gh-pages branch to deploy: `git push origin gh-pages`
+
+# Parse semantic version from tag name (ignoring arbitrary prefixes)
+if [[ "${1}" =~ ([0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?)$ ]]; then
+  VERSION="v${BASH_REMATCH[1]}"
+else
+  echo "Error: Must specify a tag name that contains a valid semantic version"
+  echo "Usage: ${0} <tag-name>"
+  echo "Examples:"
+  echo "  ${0} 1.2.3"
+  echo "  ${0} v2.0.0-rc.1"
+  exit 1
+fi
+
+TAG_NAME="${1}"
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+
+echo "Generating documentation for tag: ${TAG_NAME}"
+
+# Create temporary directories for both worktrees
+WORKTREE_DIR=$(mktemp -d)
+GHPAGES_WORKTREE_DIR=$(mktemp -d)
+
+# Set up trap to clean up both worktrees on exit
+trap 'git worktree remove --force "${WORKTREE_DIR}" 2>/dev/null || true; \
+      git worktree remove --force "${GHPAGES_WORKTREE_DIR}" 2>/dev/null || true' EXIT
+
+echo "Creating worktree for ${TAG_NAME}..."
+git worktree add --quiet "${WORKTREE_DIR}" "${TAG_NAME}"
+
+# Check if gh-pages branch exists
+if git show-ref --verify --quiet refs/heads/gh-pages; then
+  echo "Creating worktree for existing gh-pages branch..."
+  git worktree add --quiet "${GHPAGES_WORKTREE_DIR}" gh-pages
+elif git ls-remote --exit-code --heads origin gh-pages > /dev/null 2>&1; then
+  echo "Creating worktree for gh-pages branch from remote..."
+  git worktree add --quiet "${GHPAGES_WORKTREE_DIR}" -b gh-pages origin/gh-pages
+else
+  echo "Creating worktree for new orphan gh-pages branch..."
+  git worktree add --quiet --detach "${GHPAGES_WORKTREE_DIR}"
+  git -C "${GHPAGES_WORKTREE_DIR}" checkout --orphan gh-pages
+  git -C "${GHPAGES_WORKTREE_DIR}" rm -rf . > /dev/null 2>&1 || true
+fi
+
+# Change to gh-pages worktree
+cd "${GHPAGES_WORKTREE_DIR}"
+
+# Determine if this tag is the latest version
+echo "Determining if ${VERSION} is the latest version..."
+
+# Get all existing version tags from the repository (reverse sorted, newest first)
+ALL_VERSIONS=$(
+  git -C "${REPO_ROOT}" tag --list | \
+  sed -nE 's/^[^0-9]*([0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?)$/v\1/p' | \
+  sort -Vr
+)
+
+# Get the latest version from all version tags
+LATEST_VERSION=$(echo "${ALL_VERSIONS}" | head -n 1)
+
+if [ "${VERSION}" = "${LATEST_VERSION}" ]; then
+  echo "${VERSION} is the latest version"
+else
+  echo "${VERSION} is not the latest version (latest is ${LATEST_VERSION})"
+fi
+
+# Update custom documentation for latest version
+if [ "${VERSION}" = "${LATEST_VERSION}" ]; then
+  echo "Updating custom documentation..."
+
+  # Clean up old custom docs from gh-pages root
+  echo "Cleaning gh-pages root..."
+  git ls-tree --name-only HEAD | xargs -r git rm -rf
+
+  # Copy custom docs from docs/ directory
+  echo "Copying custom docs from ${WORKTREE_DIR}/docs/..."
+  cp -r "${WORKTREE_DIR}/docs/." "${GHPAGES_WORKTREE_DIR}/"
+fi
+
+# Generate version data for Jekyll
+echo "Generating _data/versions.yml..."
+mkdir -p _data
+echo "${ALL_VERSIONS}" | sed 's/^v/- /' > _data/versions.yml
+
+# Stage all changes
+git add .
+
+# Commit if there are changes
+if git diff --staged --quiet; then
+  echo "No changes to commit"
+else
+  echo "Committing documentation for ${VERSION}..."
+  git commit -m "Add ${VERSION} docs"
+
+  echo "Documentation committed to gh-pages branch!"
+  echo "Push to remote to deploy to GitHub Pages"
+fi
+
+echo "Done!"

data/dev.yml

@@ -27,5 +27,4 @@ commands:
   style:
     desc: Run rubocop
     aliases: [rubocop, lint]
-    run: bin/rubocop
-
+    run: bin/rake rubocop

data/docs/_config.yml

@@ -0,0 +1,6 @@
+# Use package name as site title
+title: "MCP Ruby SDK"
+
+# Include generated files and directories which may start with underscores
+include:
+  - "_*"

data/docs/index.md

@@ -0,0 +1,7 @@
+---
+# Empty Jekyll front matter to enable Liquid templating (see {{ ... }} below)
+---
+
+{% for version in site.data.versions -%}
+- [v{{ version }}](https://rubydoc.info/gems/mcp/{{ version }})
+{% endfor %}

data/docs/latest/index.html

@@ -0,0 +1,19 @@
+---
+# Empty Jekyll front matter to enable Liquid templating (see {{ ... }} below)
+---
+
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Redirecting to latest documentation...</title>
+  <meta http-equiv="refresh" content="0; url=https://rubydoc.info/gems/mcp">
+  <link rel="canonical" href="https://rubydoc.info/gems/mcp">
+</head>
+<body>
+  <p>Redirecting to <a href="https://rubydoc.info/gems/mcp">latest documentation</a>...</p>
+  <script>
+    window.location.href = "https://rubydoc.info/gems/mcp";
+  </script>
+</body>
+</html>

data/examples/http_server.rb

@@ -2,8 +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"
 require "logger"

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,8 +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"
 require "logger"

data/lib/json_rpc_handler.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JsonRpcHandler
+  class Version
+    V1_0 = "1.0"
+    V2_0 = "2.0"
+  end
+
+  class ErrorCode
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+    PARSE_ERROR = -32700
+  end
+
+  DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+
+  extend self
+
+  def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+    if request.is_a?(Array)
+      return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::INVALID_REQUEST,
+        message: "Invalid Request",
+        data: "Request is an empty array",
+      }) if request.empty?
+
+      # Handle batch requests
+      responses = request.map { |req| process_request(req, id_validation_pattern: id_validation_pattern, &method_finder) }.compact
+
+      # A single item is hoisted out of the array
+      return responses.first if responses.one?
+
+      # An empty array yields nil
+      responses if responses.any?
+    elsif request.is_a?(Hash)
+      # Handle single request
+      process_request(request, id_validation_pattern: id_validation_pattern, &method_finder)
+    else
+      error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::INVALID_REQUEST,
+        message: "Invalid Request",
+        data: "Request must be an array or a hash",
+      })
+    end
+  end
+
+  def handle_json(request_json, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+    begin
+      request = JSON.parse(request_json, symbolize_names: true)
+      response = handle(request, id_validation_pattern: id_validation_pattern, &method_finder)
+    rescue JSON::ParserError
+      response = error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::PARSE_ERROR,
+        message: "Parse error",
+        data: "Invalid JSON",
+      })
+    end
+
+    response&.to_json
+  end
+
+  def process_request(request, id_validation_pattern:, &method_finder)
+    id = request[:id]
+
+    error = if !valid_version?(request[:jsonrpc])
+      "JSON-RPC version must be 2.0"
+    elsif !valid_id?(request[:id], id_validation_pattern)
+      "Request ID must match validation pattern, or be an integer or null"
+    elsif !valid_method_name?(request[:method])
+      'Method name must be a string and not start with "rpc."'
+    end
+
+    return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+      code: ErrorCode::INVALID_REQUEST,
+      message: "Invalid Request",
+      data: error,
+    }) if error
+
+    method_name = request[:method]
+    params = request[:params]
+
+    unless valid_params?(params)
+      return error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::INVALID_PARAMS,
+        message: "Invalid params",
+        data: "Method parameters must be an array or an object or null",
+      })
+    end
+
+    begin
+      method = method_finder.call(method_name)
+
+      if method.nil?
+        return error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
+          code: ErrorCode::METHOD_NOT_FOUND,
+          message: "Method not found",
+          data: method_name,
+        })
+      end
+
+      result = method.call(params)
+
+      success_response(id: id, result: result)
+    rescue StandardError => e
+      error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
+        code: ErrorCode::INTERNAL_ERROR,
+        message: "Internal error",
+        data: e.message,
+      })
+    end
+  end
+
+  def valid_version?(version)
+    version == Version::V2_0
+  end
+
+  def valid_id?(id, pattern = nil)
+    return true if id.nil? || id.is_a?(Integer)
+    return false unless id.is_a?(String)
+
+    pattern ? id.match?(pattern) : true
+  end
+
+  def valid_method_name?(method)
+    method.is_a?(String) && !method.start_with?("rpc.")
+  end
+
+  def valid_params?(params)
+    params.nil? || params.is_a?(Array) || params.is_a?(Hash)
+  end
+
+  def success_response(id:, result:)
+    {
+      jsonrpc: Version::V2_0,
+      id: id,
+      result: result,
+    } unless id.nil?
+  end
+
+  def error_response(id:, id_validation_pattern:, error:)
+    {
+      jsonrpc: Version::V2_0,
+      id: valid_id?(id, id_validation_pattern) ? id : nil,
+      error: error.compact,
+    } unless id.nil?
+  end
+end

data/lib/mcp/client/http.rb

@@ -3,6 +3,8 @@
 module MCP
   class Client
     class HTTP
+      ACCEPT_HEADER = "application/json, text/event-stream"
+
       attr_reader :url
 
       def initialize(url:, headers: {})
@@ -14,46 +16,48 @@ module MCP
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
 
-        client.post("", request).body
+        response = client.post("", request)
+        validate_response_content_type!(response, method, params)
+        response.body
       rescue Faraday::BadRequestError => e
         raise RequestHandlerError.new(
           "The #{method} request is invalid",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :bad_request,
           original_error: e,
         )
       rescue Faraday::UnauthorizedError => e
         raise RequestHandlerError.new(
           "You are unauthorized to make #{method} requests",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :unauthorized,
           original_error: e,
         )
       rescue Faraday::ForbiddenError => e
         raise RequestHandlerError.new(
           "You are forbidden to make #{method} requests",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :forbidden,
           original_error: e,
         )
       rescue Faraday::ResourceNotFound => e
         raise RequestHandlerError.new(
           "The #{method} request is not found",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :not_found,
           original_error: e,
         )
       rescue Faraday::UnprocessableEntityError => e
         raise RequestHandlerError.new(
           "The #{method} request is unprocessable",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :unprocessable_entity,
           original_error: e,
         )
       rescue Faraday::Error => e # Catch-all
         raise RequestHandlerError.new(
           "Internal error handling #{method} request",
-          { method:, params: },
+          { method: method, params: params },
           error_type: :internal_error,
           original_error: e,
         )
@@ -70,6 +74,7 @@ module MCP
           faraday.response(:json)
           faraday.response(:raise_error)
 
+          faraday.headers["Accept"] = ACCEPT_HEADER
           headers.each do |key, value|
             faraday.headers[key] = value
           end
@@ -83,6 +88,17 @@ module MCP
           "Add it to your Gemfile: gem 'faraday', '>= 2.0'" \
           "See https://rubygems.org/gems/faraday for more details."
       end
+
+      def validate_response_content_type!(response, method, params)
+        content_type = response.headers["Content-Type"]
+        return if content_type&.include?("application/json")
+
+        raise RequestHandlerError.new(
+          "Unsupported Content-Type: #{content_type.inspect}. This client only supports JSON responses.",
+          { method: method, params: params },
+          error_type: :unsupported_media_type,
+        )
+      end
     end
   end
 end

data/lib/mcp/client.rb

@@ -44,28 +44,85 @@ 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
+
+    # Returns the list of prompts available from the server.
+    # Each call will make a new request – the result is not cached.
+    #
+    # @return [Array<Hash>] An array of available prompts.
+    def prompts
+      response = transport.send_request(request: {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: "prompts/list",
+      })
+
+      response.dig("result", "prompts") || []
+    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", "contents") || []
+    end
+
+    # Gets a prompt from the server by name and returns its details.
+    #
+    # @param name [String] The name of the prompt to get.
+    # @return [Hash] A hash containing the prompt details.
+    def get_prompt(name:)
+      response = transport.send_request(request: {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: "prompts/get",
+        params: { name: name },
+      })
 
-      response.dig("result", "content")
+      response.fetch("result", {})
     end
 
     private

data/lib/mcp/configuration.rb

@@ -2,29 +2,40 @@
 
 module MCP
   class Configuration
-    DEFAULT_PROTOCOL_VERSION = "2025-06-18"
-    SUPPORTED_PROTOCOL_VERSIONS = [DEFAULT_PROTOCOL_VERSION, "2025-03-26", "2024-11-05"]
+    LATEST_STABLE_PROTOCOL_VERSION = "2025-11-25"
+    SUPPORTED_STABLE_PROTOCOL_VERSIONS = [
+      LATEST_STABLE_PROTOCOL_VERSION, "2025-06-18", "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
 
     def protocol_version
-      @protocol_version || DEFAULT_PROTOCOL_VERSION
+      @protocol_version || LATEST_STABLE_PROTOCOL_VERSION
     end
 
     def protocol_version?
@@ -74,15 +85,28 @@ module MCP
       validate_tool_call_arguments = other.validate_tool_call_arguments
 
       Configuration.new(
-        exception_reporter:,
-        instrumentation_callback:,
-        protocol_version:,
-        validate_tool_call_arguments:,
+        exception_reporter: exception_reporter,
+        instrumentation_callback: instrumentation_callback,
+        protocol_version: protocol_version,
+        validate_tool_call_arguments: validate_tool_call_arguments,
       )
     end
 
     private
 
+    def validate_protocol_version!(protocol_version)
+      unless SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(protocol_version)
+        message = "protocol_version must be #{SUPPORTED_STABLE_PROTOCOL_VERSIONS[0...-1].join(", ")}, or #{SUPPORTED_STABLE_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
@@ -12,7 +11,7 @@ module MCP
       end
 
       def to_h
-        { text:, annotations:, type: "text" }.compact
+        { text: text, annotations: annotations, type: "text" }.compact
       end
     end
 
@@ -26,7 +25,7 @@ module MCP
       end
 
       def to_h
-        { data:, mime_type:, annotations:, type: "image" }.compact
+        { data: data, mime_type: mime_type, annotations: annotations, type: "image" }.compact
       end
     end
   end

data/lib/mcp/icon.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module MCP
+  class Icon
+    SUPPORTED_THEMES = ["light", "dark"]
+
+    attr_reader :mime_type, :sizes, :src, :theme
+
+    def initialize(mime_type: nil, sizes: nil, src: nil, theme: nil)
+      raise ArgumentError, 'The value of theme must specify "light" or "dark".' if theme && !SUPPORTED_THEMES.include?(theme)
+
+      @mime_type = mime_type
+      @sizes = sizes
+      @src = src
+      @theme = theme
+    end
+
+    def to_h
+      { mimeType: mime_type, sizes: sizes, src: src, theme: theme }.compact
+    end
+  end
+end

data/lib/mcp/instrumentation.rb

@@ -6,7 +6,7 @@ module MCP
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       begin
         @instrumentation_data = {}
-        add_instrumentation_data(method:)
+        add_instrumentation_data(method: method)
 
         result = yield block