model-context-protocol-rb 0.3.2 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99ee11ebae0c9c984a15954b386e89489f6715a1d371b288ece0438d066436d7
-  data.tar.gz: cdf41e8742941e9a0a41c714127d02f5a189d901a95a35e6f61a16f1f7b8a704
+  metadata.gz: e004a2e471748b63aa9f5742300fd2b648aabb84d02e75949f9741f1c78aa963
+  data.tar.gz: ecf369882f10f2cb19099d47d991ba70e6d33e0841ebda48e6917fb98780f2fb
 SHA512:
-  metadata.gz: aad64bd6e42b2ecea2b742bb23b902ea1bfae3e77cffc5009b0a83712df7efac417b680bb460649bb73fff31d2d554d33a17d6fe96adb35f3cc9d0addbbcf9be
-  data.tar.gz: 6fa834a1c2bf4494748474dc26a29bede650b1a1913c7c543a7c195fd24fe99eda5f1610c40a63067f454b50f669b1fb47030e106fa6ba80cbde522bccfb9518
+  metadata.gz: 9fa10a6fe78390f0d8c6303efcc6135751b50a2c4dd3cc2b0ed0d07e0647e9555a3317a7b68b2794d52f9d6ac3e8e38a569bda96e20bc2e0193dadefab346dd6
+  data.tar.gz: fda6f707e7814911a4e9175cd40fbab41f45dc775db644185e4bc2008fe71bddd83c89ed321cfeee67f93cbf7c29bc6e69b46596893e3ae2242fa757fd9f4f75

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.3.4] - 2025-09-02
+
+- (Fix) Fixes broken arguments usage in prompts and tools.
+
+## [0.3.3] - 2025-09-02
+
+- (Breaking) Added logging support.
+  - Requires updating the `enable_log` configuration option to `logging_enabled`.
+- Added experimental Streamable HTTP transport.
+- (Breaking) Renamed params to arguments in prompts, resources, and tools.
+  - Requires updating all references to `params` in prompts, resources, and tools to `arguments` with symbolized keys.
+- Improved ergonomics of completions and resource templates.
+- Added support for providing context to prompts, resources, and tools.
+
 ## [0.3.2] - 2025-05-10
 
 - Added resource template support.
@@ -37,8 +51,10 @@
 
 - Initial release
 
-[Unreleased]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.2...HEAD
-[0.3.1]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.1...v0.3.2
+[Unreleased]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.4...HEAD
+[0.3.4]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.3...v0.3.4
+[0.3.3]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.1.0...v0.2.0

data/README.md

@@ -30,7 +30,7 @@ Build a simple MCP server by registering your prompts, resources, resource templ
 server = ModelContextProtocol::Server.new do |config|
   config.name = "MCP Development Server"
   config.version = "1.0.0"
-  config.enable_log = true
+  config.logging_enabled = true
 
   # Environment Variables - https://modelcontextprotocol.io/docs/tools/debugging#environment-variables
   # Require specific environment variables to be set
@@ -39,6 +39,12 @@ server = ModelContextProtocol::Server.new do |config|
   # Set environment variables programmatically
   config.set_environment_variable("DEBUG_MODE", "true")
 
+  # Provide prompts, resources, and tools with contextual variables
+  config.context = {
+    user_id: "123456",
+    request_id: SecureRandom.uuid
+  }
+
   config.registry = ModelContextProtocol::Server::Registry.new do
     prompts list_changed: true do
       register TestPrompt
@@ -61,45 +67,159 @@ end
 server.start
 ```
 
+### Transport Configuration
+
+The MCP server supports different transport mechanisms for communication with clients. By default, it uses stdio (standard input/output), but you can also configure it to use streamable HTTP transport for distributed deployments.
+
+#### Stdio Transport (Default)
+
+When no transport is specified, the server uses stdio transport, which is suitable for single-process communication:
+
+```ruby
+server = ModelContextProtocol::Server.new do |config|
+  config.name = "MCP Development Server"
+  config.version = "1.0.0"
+  # No transport specified - uses stdio by default
+  config.registry = ModelContextProtocol::Server::Registry.new
+end
+
+server.start
+```
+
+#### Streamable HTTP Transport
+
+For distributed deployments with load balancers and multiple server instances, use the streamable HTTP transport with Redis-backed session management:
+
+```ruby
+require 'redis'
+
+server = ModelContextProtocol::Server.new do |config|
+  config.name = "MCP Development Server"
+  config.version = "1.0.0"
+
+  # Configure streamable HTTP transport
+  config.transport = {
+    type: :streamable_http,
+    redis_client: Redis.new(url: ENV['REDIS_URL']),
+    session_ttl: 3600 # Optional: session timeout in seconds (default: 3600)
+  }
+
+  config.registry = ModelContextProtocol::Server::Registry.new
+end
+
+# For HTTP frameworks, handle the request and return the response
+result = server.start
+# result will be a hash like: {json: {...}, status: 200, headers: {...}}
+```
+
+**Key Features:**
+- **Distributed Sessions**: Redis-backed session storage enables multiple server instances
+- **Load Balancer Support**: Sessions persist across different server instances  
+- **HTTP Methods**: Supports POST (requests), GET (Server-Sent Events), DELETE (cleanup)
+- **Cross-Server Routing**: Messages are routed between servers via Redis pub/sub
+
+**Integration Example (Rails):**
+
+```ruby
+class McpController < ApplicationController
+  def handle
+    server = ModelContextProtocol::Server.new do |config|
+      config.name = "Rails MCP Server"
+      config.version = "1.0.0"
+      config.transport = {
+        type: :streamable_http,
+        redis_client: Redis.new(url: ENV['REDIS_URL']),
+        request: request,
+        response: response
+      }
+      config.registry = build_registry
+    end
+
+    result = server.start
+    render json: result[:json], status: result[:status], headers: result[:headers]
+  end
+end
+```
+
 Messages from the MCP client will be routed to the appropriate custom handler. This SDK provides several classes that should be used to build your handlers.
 
+### Server features
+
 #### Prompts
 
 The `ModelContextProtocol::Server::Prompt` base class allows subclasses to define a prompt that the MCP client can use. Define the [appropriate metadata](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/) in the `with_metadata` block.
 
-Define any arguments using the `with_argument` block. You can mark an argument as required, and you can optionally provide the class name of a service object that provides completions. See [Completions](#completions) for more information.
+Define any arguments using the `with_argument` block. You can mark an argument as required, and you can optionally provide a completion class. See [Completions](#completions) for more information.
+
+Then implement the `call` method to build your prompt. Any arguments passed to the tool from the MCP client will be available in the `arguments` hash with symbol keys (e.g., `arguments[:argument_name]`), and any context values provided in the server configuration will be available in the `context` hash. Use the `respond_with` instance method to ensure your prompt responds with appropriately formatted response data.
 
-Then implement the `call` method to build your prompt. Use the `respond_with` instance method to ensure your prompt responds with appropriately formatted response data.
+You can also log from within your prompt by calling a valid logger level method on the `logger` and passing a string message.
 
 This is an example prompt that returns a properly formatted response:
 
 ```ruby
 class TestPrompt < ModelContextProtocol::Server::Prompt
+  ToneCompletion = ModelContextProtocol::Server::Completion.define do
+    hints = ["whiny", "angry", "callous", "desperate", "nervous", "sneaky"]
+    values = hints.grep(/#{argument_value}/)
+
+    respond_with values:
+  end
+
   with_metadata do
-    name "test_prompt"
-    description "A test prompt"
+    name "brainstorm_excuses"
+    description "A prompt for brainstorming excuses to get out of something"
   end
 
   with_argument do
-    name "message"
-    description "The thing to do"
+    name "undesirable_activity"
+    description "The thing to get out of"
     required true
-    completion TestCompletion
   end
 
   with_argument do
-    name "other"
-    description "Another thing to do"
+    name "tone"
+    description "The general tone to be used in the generated excuses"
     required false
+    completion ToneCompletion
   end
 
   def call
+    logger.info("Brainstorming excuses...")
     messages = [
       {
         role: "user",
         content: {
           type: "text",
-          text: "Do this: #{params["message"]}"
+          text: "My wife wants me to: #{arguments[:undesirable_activity]}... Can you believe it?"
+        }
+      },
+      {
+        role: "assistant",
+        content: {
+          type: "text",
+          text: "Oh, that's just downright awful. What are you going to do?"
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "Well, I'd like to get out of it, but I'm going to need your help."
+        }
+      },
+      {
+        role: "assistant",
+        content: {
+          type: "text",
+          text: "Anything for you."
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "Can you generate some excuses for me?" + (arguments[:tone] ? "Make them as #{arguments[:tone]} as possible." : "")
         }
       }
     ]
@@ -113,21 +233,35 @@ end
 
 The `ModelContextProtocol::Server::Resource` base class allows subclasses to define a resource that the MCP client can use. Define the [appropriate metadata](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/) in the `with_metadata` block.
 
-Then, implement the `call` method to build your resource. Use the `respond_with` instance method to ensure your resource responds with appropriately formatted response data.
+Then, implement the `call` method to build your resource. Any context values provided in the server configuration will be available in the `context` hash. Use the `respond_with` instance method to ensure your resource responds with appropriately formatted response data.
+
+You can also log from within your resource by calling a valid logger level method on the `logger` and passing a string message.
 
 This is an example resource that returns a text response:
 
 ```ruby
 class TestResource < ModelContextProtocol::Server::Resource
   with_metadata do
-    name "Test Resource"
-    description "A test resource"
+    name "top-secret-plans.txt"
+    description "Top secret plans to do top secret things"
     mime_type "text/plain"
-    uri "resource://test-resource"
+    uri "file:///top-secret-plans.txt"
   end
 
   def call
-    respond_with :text, text: "Here's the data"
+    unless authorized?(context[:user_id])
+      logger.info("This fool thinks he can get my top secret plans...")
+      return respond_with :text, text: "Nothing to see here, move along."
+    end
+
+    respond_with :text, text: "I'm finna eat all my wife's leftovers."
+  end
+
+  private
+
+  def authorized?(user_id)
+    authorized_users = ["42", "123456"]
+    authorized_users.any?(user_id)
   end
 end
 ```
@@ -137,14 +271,15 @@ This is an example resource that returns binary data:
 ```ruby
 class TestBinaryResource < ModelContextProtocol::Server::Resource
   with_metadata do
-    name "Project Logo"
+    name "project-logo.png"
     description "The logo for the project"
-    mime_type "image/jpeg"
-    uri "resource://project-logo"
+    mime_type "image/png"
+    uri "file:///project-logo.png"
   end
 
   def call
     # In a real implementation, we would retrieve the binary resource
+    # This is a small valid base64 encoded string (represents "test")
     data = "dGVzdA=="
     respond_with :binary, blob: data
   end
@@ -158,24 +293,22 @@ The `ModelContextProtocol::Server::ResourceTemplate` base class allows subclasse
 This is an example resource template that provides a completion for a parameter of the URI template:
 
 ```ruby
-class TestResourceTemplateCompletion < ModelContextProtocol::Server::Completion
-  def call
+class TestResourceTemplate < ModelContextProtocol::Server::ResourceTemplate
+  Completion = ModelContextProtocol::Server::Completion.define do
     hints = {
-      "name" => ["test-resource", "project-logo"]
+      "name" => ["top-secret-plans.txt"]
     }
     values = hints[argument_name].grep(/#{argument_value}/)
 
     respond_with values:
   end
-end
 
-class TestResourceTemplate < ModelContextProtocol::Server::ResourceTemplate
   with_metadata do
-    name "Test Resource Template"
-    description "A test resource template"
+    name "project-document-resource-template"
+    description "A resource template for retrieving project documents"
     mime_type "text/plain"
-    uri_template "resource://{name}" do
-      completion :name, TestResourceTemplateCompletion
+    uri_template "file:///{name}" do
+      completion :name, Completion
     end
   end
 end
@@ -185,7 +318,9 @@ end
 
 The `ModelContextProtocol::Server::Tool` base class allows subclasses to define a tool that the MCP client can use. Define the [appropriate metadata](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/) in the `with_metadata` block.
 
-Then implement the `call` method to build your tool. Use the `respond_with` instance method to ensure your tool responds with appropriately formatted response data.
+Then, implement the `call` method to build your tool. Any arguments passed to the tool from the MCP client will be available in the `arguments` hash with symbol keys (e.g., `arguments[:argument_name]`), and any context values provided in the server configuration will be available in the `context` hash. Use the `respond_with` instance method to ensure your tool responds with appropriately formatted response data.
+
+You can also log from within your tool by calling a valid logger level method on the `logger` and passing a string message.
 
 This is an example tool that returns a text response:
 
@@ -208,9 +343,12 @@ class TestToolWithTextResponse < ModelContextProtocol::Server::Tool
   end
 
   def call
-    number = params["number"].to_i
-    result = number * 2
-    respond_with :text, text: "#{number} doubled is #{result}"
+    user_id = context[:user_id]
+    number = arguments[:number].to_i
+    logger.info("Silly user doesn't know how to double a number")
+    calculation = number * 2
+    salutation = user_id ? "User #{user_id}, " : ""
+    respond_with :text, text: salutation << "#{number} doubled is #{calculation}"
   end
 end
 ```
@@ -242,7 +380,7 @@ class TestToolWithImageResponse < ModelContextProtocol::Server::Tool
 
   def call
     # Map format to mime type
-    mime_type = case params["format"].downcase
+    mime_type = case arguments[:format].downcase
     when "svg"
       "image/svg+xml"
     when "jpg", "jpeg"
@@ -311,7 +449,7 @@ class TestToolWithResourceResponse < ModelContextProtocol::Server::Tool
   end
 
   def call
-    title = params["title"].downcase
+    title = arguments[:title].downcase
     # In a real implementation, we would do a lookup to get the document data
     document = "richtextdata"
     respond_with :resource, uri: "resource://document/#{title}", text: document, mime_type: "application/rtf"

data/lib/model_context_protocol/server/completion.rb

@@ -15,6 +15,12 @@ module ModelContextProtocol
       new(...).call
     end
 
+    def self.define(&block)
+      Class.new(self) do
+        define_method(:call, &block)
+      end
+    end
+
     private
 
     Response = Data.define(:values, :total, :hasMore) do

data/lib/model_context_protocol/server/configuration.rb

@@ -1,3 +1,5 @@
+require_relative "mcp_logger"
+
 module ModelContextProtocol
   class Server::Configuration
     # Raised when configured with invalid name.
@@ -12,16 +14,74 @@ module ModelContextProtocol
     # Raised when a required environment variable is not set
     class MissingRequiredEnvironmentVariable < StandardError; end
 
-    attr_accessor :enable_log, :name, :registry, :version
+    # Raised when transport configuration is invalid
+    class InvalidTransportError < StandardError; end
+
+    # Raised when an invalid log level is provided
+    class InvalidLogLevelError < StandardError; end
+
+    # Valid MCP log levels per the specification
+    VALID_LOG_LEVELS = %w[debug info notice warning error critical alert emergency].freeze
+
+    attr_accessor :name, :registry, :version, :transport
+    attr_reader :logger
+
+    def initialize
+      # Always create a logger - enabled by default
+      @logging_enabled = true
+      @default_log_level = "info"
+      @logger = ModelContextProtocol::Server::MCPLogger.new(
+        logger_name: "server",
+        level: @default_log_level,
+        enabled: @logging_enabled
+      )
+    end
 
     def logging_enabled?
-      enable_log || false
+      @logging_enabled
+    end
+
+    def logging_enabled=(value)
+      @logging_enabled = value
+      @logger = ModelContextProtocol::Server::MCPLogger.new(
+        logger_name: "server",
+        level: @default_log_level,
+        enabled: value
+      )
+    end
+
+    def default_log_level=(level)
+      unless VALID_LOG_LEVELS.include?(level.to_s)
+        raise InvalidLogLevelError, "Invalid log level: #{level}. Valid levels are: #{VALID_LOG_LEVELS.join(", ")}"
+      end
+
+      @default_log_level = level.to_s
+      @logger.set_mcp_level(@default_log_level)
+    end
+
+    def transport_type
+      case transport
+      when Hash
+        transport[:type] || transport["type"]
+      when Symbol, String
+        transport.to_sym
+      end
+    end
+
+    def transport_options
+      case transport
+      when Hash
+        transport.except(:type, "type").transform_keys(&:to_sym)
+      else
+        {}
+      end
     end
 
     def validate!
       raise InvalidServerNameError unless valid_name?
       raise InvalidRegistryError unless valid_registry?
       raise InvalidServerVersionError unless valid_version?
+      validate_transport!
 
       validate_environment_variables!
     end
@@ -51,6 +111,14 @@ module ModelContextProtocol
       environment_variables[key.to_s.upcase] = value
     end
 
+    def context
+      @context ||= {}
+    end
+
+    def context=(context_hash = {})
+      @context = context_hash
+    end
+
     private
 
     def required_environment_variables
@@ -74,5 +142,29 @@ module ModelContextProtocol
     def valid_version?
       version&.is_a?(String)
     end
+
+    def validate_transport!
+      case transport_type
+      when :streamable_http
+        validate_streamable_http_transport!
+      when :stdio, nil
+        # stdio transport has no required options
+      else
+        raise InvalidTransportError, "Unknown transport type: #{transport_type}" if transport_type
+      end
+    end
+
+    def validate_streamable_http_transport!
+      options = transport_options
+
+      unless options[:redis_client]
+        raise InvalidTransportError, "streamable_http transport requires redis_client option"
+      end
+
+      redis_client = options[:redis_client]
+      unless redis_client.respond_to?(:hset) && redis_client.respond_to?(:expire)
+        raise InvalidTransportError, "redis_client must be a Redis-compatible client"
+      end
+    end
   end
 end

data/lib/model_context_protocol/server/mcp_logger.rb

@@ -0,0 +1,109 @@
+require "logger"
+require "forwardable"
+require "json"
+
+module ModelContextProtocol
+  class Server::MCPLogger
+    extend Forwardable
+
+    def_delegators :@internal_logger, :datetime_format=, :formatter=, :progname, :progname=
+
+    LEVEL_MAP = {
+      "debug" => Logger::DEBUG,
+      "info" => Logger::INFO,
+      "notice" => Logger::INFO,
+      "warning" => Logger::WARN,
+      "error" => Logger::ERROR,
+      "critical" => Logger::FATAL,
+      "alert" => Logger::FATAL,
+      "emergency" => Logger::UNKNOWN
+    }.freeze
+
+    REVERSE_LEVEL_MAP = {
+      Logger::DEBUG => "debug",
+      Logger::INFO => "info",
+      Logger::WARN => "warning",
+      Logger::ERROR => "error",
+      Logger::FATAL => "critical",
+      Logger::UNKNOWN => "emergency"
+    }.freeze
+
+    attr_accessor :transport
+    attr_reader :logger_name, :enabled
+
+    def initialize(logger_name: "server", level: "info", enabled: true)
+      @logger_name = logger_name
+      @enabled = enabled
+      @internal_logger = Logger.new(nil)
+      @internal_logger.level = LEVEL_MAP[level] || Logger::INFO
+      @transport = nil
+      @queued_messages = []
+    end
+
+    %i[debug info warn error fatal unknown].each do |severity|
+      define_method(severity) do |message = nil, **data, &block|
+        return true unless @enabled
+        add(Logger.const_get(severity.to_s.upcase), message, data, &block)
+      end
+    end
+
+    def add(severity, message = nil, data = {}, &block)
+      return true unless @enabled
+      return true if severity < @internal_logger.level
+
+      message = block.call if message.nil? && block_given?
+      send_notification(severity, message, data)
+      true
+    end
+
+    def level=(value)
+      @internal_logger.level = value
+    end
+
+    def level
+      @internal_logger.level
+    end
+
+    def set_mcp_level(mcp_level)
+      self.level = LEVEL_MAP[mcp_level] || Logger::INFO
+    end
+
+    def connect_transport(transport)
+      @transport = transport
+      flush_queued_messages if @enabled
+    end
+
+    private
+
+    def send_notification(severity, message, data)
+      return unless @enabled
+
+      notification_params = {
+        level: REVERSE_LEVEL_MAP[severity] || "info",
+        logger: @logger_name,
+        data: format_data(message, data)
+      }
+
+      if @transport
+        @transport.send_notification("notifications/message", notification_params)
+      else
+        @queued_messages << notification_params
+      end
+    end
+
+    def format_data(message, additional_data)
+      data = {}
+      data[:message] = message.to_s if message
+      data.merge!(additional_data) unless additional_data.empty?
+      data
+    end
+
+    def flush_queued_messages
+      return unless @transport && @enabled
+      @queued_messages.each do |params|
+        @transport.send_notification("notifications/message", params)
+      end
+      @queued_messages.clear
+    end
+  end
+end