model-context-protocol-rb 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa9e49b895a1502fe4887f7e2089c24b69b980d9ac7c27754f97c52ad1541c7b
-  data.tar.gz: 92e343e66c69cd1e5ae9f9d8adb83567303a2aa5e48021b1dc964c172128426d
+  metadata.gz: 5cce144594a63393d124f7edc41428730824f2e5df282b21458b506d1ac59376
+  data.tar.gz: f7a1de949d083fbcf9df57f500cad32869aa2c42b7dda17726509bab58ffc0b2
 SHA512:
-  metadata.gz: bcbfcb95e17f7e0deaa368f7e2b3dc7915be124b4c98b2b86b8e94c446fe18bd7d9e8c7dbfb6e4301edf6b1ad28e491701fec85bbd31dcd2d79d8b91a3f0c8c1
-  data.tar.gz: 284e545287ecacb83d42c7a5f72dbe9b0f5ab359d50c9d0cfcde1eb2e00d9c330e9cce3b6bcb15e68fb48963e8778888ca3dbdf1fab5ac0a0d27d36f1ca4e6bd
+  metadata.gz: f374a5e4cf00d1f905f86c51be35c812b6074c188dca28e2724a9e478afdba641337b4f17404ed44cdb22a86baf88dbcaf03df4896e5b039f1717eb3c8afbb71
+  data.tar.gz: 8bb5dd4e584f9df32265d1a88d9469e73b2c70225a88da510240bb5b7f80ef4f94b13738ed66a1f1bcec39012832efc0032d72d7ff93ede737ec31d737589243

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [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.
+- Added completion support for prompts and resources.
+- Improved metadata definition for prompts, resources, and tools using simple DSL.
+
 ## [0.3.1] - 2025-04-04
 
 - Added support for environment variables to MCP servers (thanks @hmk):
@@ -31,7 +47,9 @@
 
 - Initial release
 
-[Unreleased]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/dickdavis/model-context-protocol-rb/compare/v0.3.3...HEAD
+[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

@@ -8,13 +8,10 @@ You are welcome to contribute.
 
 TODO's:
 
-* [Completion](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/utilities/completion/)
-* [Logging](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/utilities/logging/)
 * [Pagination](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/utilities/pagination/)
 * [Prompt list changed notifications](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/#list-changed-notification)
 * [Resource list changed notifications](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/#list-changed-notification)
 * [Resource subscriptions](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/#subscriptions)
-* [Resource templates](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/#resource-templates)
 * [Tool list changed notifications](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/#list-changed-notification)
 
 ## Usage
@@ -27,13 +24,13 @@ require 'model_context_protocol'
 
 ### Building an MCP Server
 
-Build a simple MCP server by registering your prompts, resources, and tools. Then, configure and run the server.
+Build a simple MCP server by registering your prompts, resources, resource templates, and tools. Then, configure and run the server.
 
 ```ruby
 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
@@ -42,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
@@ -51,6 +54,10 @@ server = ModelContextProtocol::Server.new do |config|
       register TestResource
     end
 
+    resource_templates do
+      register TestResourceTemplate
+    end
+
     tools list_changed: true do
       register TestTool
     end
@@ -60,44 +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.
 
-#### ModelContextProtocol::Server::Prompt
+### 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.
 
-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.
+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.
+
+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",
-      arguments: [
-        {
-          name: "message",
-          description: "The thing to do",
-          required: true
-        },
-        {
-          name: "other",
-          description: "Another thing to do",
-          required: false
-        }
-      ]
-    }
+    name "brainstorm_excuses"
+    description "A prompt for brainstorming excuses to get out of something"
+  end
+
+  with_argument do
+    name "undesirable_activity"
+    description "The thing to get out of"
+    required true
+  end
+
+  with_argument 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." : "")
         }
       }
     ]
@@ -107,27 +229,39 @@ class TestPrompt < ModelContextProtocol::Server::Prompt
 end
 ```
 
-#### ModelContextProtocol::Server::Resource
+#### Resources
 
 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",
-      mime_type: "text/plain",
-      uri: "resource://test-resource"
-    }
+    name "top-secret-plans.txt"
+    description "Top secret plans to do top secret things"
+    mime_type "text/plain"
+    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,52 +271,84 @@ This is an example resource that returns binary data:
 ```ruby
 class TestBinaryResource < ModelContextProtocol::Server::Resource
   with_metadata do
-    {
-      name: "Project Logo",
-      description: "The logo for the project",
-      mime_type: "image/jpeg",
-      uri: "resource://project-logo"
-    }
+    name "project-logo.png"
+    description "The logo for the project"
+    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
 end
 ```
 
-#### ModelContextProtocol::Server::Tool
+#### Resource Templates
+
+The `ModelContextProtocol::Server::ResourceTemplate` base class allows subclasses to define a resource template that the MCP client can use. Define the [appropriate metadata](https://modelcontextprotocol.io/specification/2024-11-05/server/resources#resource-templates) in the `with_metadata` block.
+
+This is an example resource template that provides a completion for a parameter of the URI template:
+
+```ruby
+class TestResourceTemplate < ModelContextProtocol::Server::ResourceTemplate
+  Completion = ModelContextProtocol::Server::Completion.define do
+    hints = {
+      "name" => ["top-secret-plans.txt"]
+    }
+    values = hints[argument_name].grep(/#{argument_value}/)
+
+    respond_with values:
+  end
+
+  with_metadata do
+    name "project-document-resource-template"
+    description "A resource template for retrieving project documents"
+    mime_type "text/plain"
+    uri_template "file:///{name}" do
+      completion :name, Completion
+    end
+  end
+end
+```
+
+#### Tools
 
 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:
 
 ```ruby
 class TestToolWithTextResponse < ModelContextProtocol::Server::Tool
   with_metadata do
-    {
-      name: "double",
-      description: "Doubles the provided number",
-      inputSchema: {
+    name "double"
+    description "Doubles the provided number"
+    input_schema do
+      {
         type: "object",
         properties: {
           number: {
-            type: "string",
+            type: "string"
           }
         },
         required: ["number"]
       }
-    }
+    end
   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
 ```
@@ -192,10 +358,10 @@ This is an example of a tool that returns an image:
 ```ruby
 class TestToolWithImageResponse < ModelContextProtocol::Server::Tool
   with_metadata do
-    {
-      name: "custom-chart-generator",
-      description: "Generates a chart in various formats",
-      inputSchema: {
+    name "custom-chart-generator"
+    description "Generates a chart in various formats"
+    input_schema do
+      {
         type: "object",
         properties: {
           chart_type: {
@@ -209,12 +375,12 @@ class TestToolWithImageResponse < ModelContextProtocol::Server::Tool
         },
         required: ["chart_type", "format"]
       }
-    }
+    end
   end
 
   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"
@@ -236,10 +402,10 @@ If you don't provide a mime type, it will default to `image/png`.
 ```ruby
 class TestToolWithImageResponseDefaultMimeType < ModelContextProtocol::Server::Tool
   with_metadata do
-    {
-      name: "other-custom-chart-generator",
-      description: "Generates a chart",
-      inputSchema: {
+    name "other-custom-chart-generator"
+    description "Generates a chart"
+    input_schema do
+      {
         type: "object",
         properties: {
           chart_type: {
@@ -249,7 +415,7 @@ class TestToolWithImageResponseDefaultMimeType < ModelContextProtocol::Server::T
         },
         required: ["chart_type"]
       }
-    }
+    end
   end
 
   def call
@@ -266,10 +432,10 @@ This is an example of a tool that returns a resource response:
 ```ruby
 class TestToolWithResourceResponse < ModelContextProtocol::Server::Tool
   with_metadata do
-    {
-      name: "document-finder",
-      description: "Finds a the document with the given title",
-      inputSchema: {
+    name "document-finder"
+    description "Finds a the document with the given title"
+    input_schema do
+      {
         type: "object",
         properties: {
           title: {
@@ -279,11 +445,11 @@ class TestToolWithResourceResponse < ModelContextProtocol::Server::Tool
         },
         required: ["title"]
       }
-    }
+    end
   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"
@@ -291,6 +457,27 @@ class TestToolWithResourceResponse < ModelContextProtocol::Server::Tool
 end
 ```
 
+### Completions
+
+The `ModelContextProtocol::Server::Completion` base class allows subclasses to define a completion that the MCP client can use to obtain hints or suggestions for arguments to prompts and resources.
+
+implement the `call` method to build your completion. Use the `respond_with` instance method to ensure your completion responds with appropriately formatted response data.
+
+This is an example completion that returns an array of values in the response:
+
+```ruby
+class TestCompletion < ModelContextProtocol::Server::Completion
+  def call
+    hints = {
+      "message" => ["hello", "world", "foo", "bar"]
+    }
+    values = hints[argument_name].grep(/#{argument_value}/)
+
+    respond_with values:
+  end
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/model_context_protocol/server/completion.rb

@@ -0,0 +1,51 @@
+module ModelContextProtocol
+  class Server::Completion
+    attr_reader :argument_name, :argument_value
+
+    def initialize(argument_name, argument_value)
+      @argument_name = argument_name
+      @argument_value = argument_value
+    end
+
+    def call
+      raise NotImplementedError, "Subclasses must implement the call method"
+    end
+
+    def self.call(...)
+      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
+      def serialized
+        {completion: {values:, total:, hasMore:}}
+      end
+    end
+
+    def respond_with(values:)
+      values_to_return = values.take(100)
+      total = values.size
+      has_more = values_to_return.size != total
+      Response[values:, total:, hasMore: has_more]
+    end
+  end
+
+  class Server::NullCompletion
+    Response = Data.define(:values, :total, :hasMore) do
+      def serialized
+        {completion: {values:, total:, hasMore:}}
+      end
+    end
+
+    def self.call(_argument_name, _argument_value)
+      Response[values: [], total: 0, hasMore: false]
+    end
+  end
+end