mcp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dc4aa079d5850a58ca03b8cd6c8ef980bbc7ea2a4d7f8980b424b96a76e34f6
-  data.tar.gz: b6ae9619b56ddde201d94c3ca2353da03f6acef7895e0af947c97c8e89b85355
+  metadata.gz: b72cdaffe97298a6d6d8b88973b4ea2236909dfb9bf46cc6694ae9331a102a5a
+  data.tar.gz: dbab122901fa44329aa03d355fcf35df70087ab88a3f919100740d46261b1319
 SHA512:
-  metadata.gz: 7978c2e9c45fd62fcf5e3030897ded84ba372862519819990fd4a8deda8c98adb03f06449dbcd30d017692ba01ef11c02099c07c8b92b9569a6e9e359b8f6bcc
-  data.tar.gz: 026a813c62da210e928b0d6cc7c55abbd84d447b2edb9f2ac034ef5f8d1d5ed6d5b2c2091cf568e7f11e40eed5b5adf55458ea2b649b5f0d2417e2fc28fbed63
+  metadata.gz: 4f3200c4d2520fa6b1c720b7e1547be5cbaea15d2ba76f8491dedd5ef840f8fae59017cd3ea965796c7cda0ab353e78579291e3f3559250412ae9f1f901eb0b7
+  data.tar.gz: 91c4dff59524cd390a2cfc92921862cb1dc9446b483b699d7ac722a40438716c56c494b34d84d211aeafd4fc152fcfaf9ae10c354c1c3c104c27ca0a0f4f83a1

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

@@ -1,30 +1,17 @@
 ---
-description: writing changelog markdown when cutting a new release of the gem
-globs:
+description: Updating CHANGELOG.md before cutting a new release of the gem
+globs: CHANGELOG.md
 alwaysApply: false
 ---
-- output the changelog as markdown when asked.
+
+- 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 whether a PR should be listed in
-  - ## Added; adds new functionality
-  - ## Changed; alters functionality; especially backward compatible changes
-  - ## Fixed; bugfixes that are forward compatible
-
-use the following format for changelogs:
-
-```
-## Added
-- New functionality added that was not present before
-
-## Changed
-- Alterations to functionality that may indicate breaking changes
-
-## Fixed
-- Bug fixes
-
-#### Full change list:
-- [Name of the PR #123](https:/github.com/modelcontextprotocol/ruby-sdk/pull/123) @github-author-username
-- [Name of the PR #456](https:/github.com/modelcontextprotocol/ruby-sdk/pull/456) @another-github-author
-```
+- 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

data/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release new version
+on:
+  push:
+    branches: [main]
+    paths:
+      - "lib/mcp/version.rb"
+jobs:
+  publish_gem:
+    if: github.repository_owner == 'modelcontextprotocol'
+    name: Release Gem Version to RubyGems.org
+    runs-on: ubuntu-latest
+
+    environment: release
+
+    permissions:
+      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
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: 3.4
+      - uses: rubygems/release-gem@v1

data/.rubocop.yml

@@ -5,6 +5,5 @@ plugins:
   - rubocop-minitest
   - rubocop-rake
 
-Naming/FileName:
-  Exclude:
-    - 'lib/mcp-ruby.rb'
+Gemspec/DevelopmentDependencies:
+  Enabled: true

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2025-07-15
+
+### Added
+
+- Custom methods support via `define_custom_method` (#75)
+- Streamable HTTP transport implementation (#33)
+- Tool argument validation against schemas (#43)
+
+### Changed
+
+- Server context is now optional for Tools and Prompts (#54)
+- Improved capability handling and removed automatic capability determination (#61, #63)
+- Refactored architecture in preparation for client support (#27)
+
+### Fixed
+
+- Input schema validation for schemas without required fields (#73)
+- Error handling when sending notifications (#70)
+
+## [0.1.0] - 2025-05-30
+
+Initial release

data/Gemfile

@@ -7,11 +7,18 @@ gemspec
 
 # Specify development dependencies below
 gem "minitest", "~> 5.1", require: false
-gem "rake", "~> 13.0"
-gem "rubocop-minitest"
-gem "rubocop-rake"
-gem "rubocop-shopify", require: false
-
 gem "minitest-reporters"
 gem "mocha"
+
+gem "rubocop-minitest", require: false
+gem "rubocop-rake", require: false
+gem "rubocop-shopify", require: false
+
+gem "puma", ">= 5.0.0"
+gem "rack", ">= 2.0.0"
+gem "rackup", ">= 2.1.0"
+
+gem "activesupport"
 gem "debug"
+gem "rake", "~> 13.0"
+gem "sorbet-static-and-runtime"

data/README.md

@@ -1,6 +1,6 @@
-# Model Context Protocol
+# MCP Ruby SDK [![Gem Version](https://img.shields.io/gem/v/mcp)](https://rubygems.org/gems/mcp) [![MIT licensed](https://img.shields.io/badge/license-MIT-green)](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/LICENSE.txt) [![CI](https://github.com/modelcontextprotocol/ruby-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/modelcontextprotocol/ruby-sdk/actions/workflows/ci.yml)
 
-A Ruby gem for implementing Model Context Protocol servers
+The official Ruby SDK for Model Context Protocol servers and clients.
 
 ## Installation
 
@@ -12,13 +12,13 @@ gem 'mcp'
 
 And then execute:
 
-```bash
+```console
 $ bundle install
 ```
 
 Or install it yourself as:
 
-```bash
+```console
 $ gem install mcp
 ```
 
@@ -28,13 +28,17 @@ The `MCP::Server` class is the core component that handles JSON-RPC requests and
 It implements the Model Context Protocol specification, handling model context requests and responses.
 
 ### Key Features
+
 - Implements JSON-RPC 2.0 message handling
 - Supports protocol initialization and capability negotiation
 - Manages tool registration and invocation
 - Supports prompt registration and execution
 - Supports resource registration and retrieval
+- Supports stdio & Streamable HTTP (including SSE) transports
+- Supports notifications for list changes (tools, prompts, resources)
 
 ### Supported Methods
+
 - `initialize` - Initializes the protocol and returns server capabilities
 - `ping` - Simple health check
 - `tools/list` - Lists all registered tools and their schemas
@@ -45,20 +49,106 @@ It implements the Model Context Protocol specification, handling model context r
 - `resources/read` - Retrieves a specific resource by name
 - `resources/templates/list` - Lists all registered resource templates and their schemas
 
+### Custom Methods
+
+The server allows you to define custom JSON-RPC methods beyond the standard MCP protocol methods using the `define_custom_method` method:
+
+```ruby
+server = MCP::Server.new(name: "my_server")
+
+# Define a custom method that returns a result
+server.define_custom_method(method_name: "add") do |params|
+  params[:a] + params[:b]
+end
+
+# Define a custom notification method (returns nil)
+server.define_custom_method(method_name: "notify") do |params|
+  # Process notification
+  nil
+end
+```
+
+**Key Features:**
+
+- Accepts any method name as a string
+- Block receives the request parameters as a hash
+- Can handle both regular methods (with responses) and notifications
+- Prevents overriding existing MCP protocol methods
+- Supports instrumentation callbacks for monitoring
+
+**Usage Example:**
+
+```ruby
+# Client request
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "add",
+  "params": { "a": 5, "b": 3 }
+}
+
+# Server response
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": 8
+}
+```
+
+**Error Handling:**
+
+- Raises `MCP::Server::MethodAlreadyDefinedError` if trying to override an existing method
+- Supports the same exception reporting and instrumentation as standard methods
+
+### Notifications
+
+The server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling.
+
+#### Notification Methods
+
+The server provides three notification methods:
+
+- `notify_tools_list_changed()` - Send a notification when the tools list changes
+- `notify_prompts_list_changed()` - Send a notification when the prompts list changes
+- `notify_resources_list_changed()` - Send a notification when the resources list changes
+
+#### Notification Format
+
+Notifications follow the JSON-RPC 2.0 specification and use these method names:
+
+- `notifications/tools/list_changed`
+- `notifications/prompts/list_changed`
+- `notifications/resources/list_changed`
+
+#### Transport Support
+
+- **HTTP Transport**: Notifications are sent as Server-Sent Events (SSE) to all connected sessions
+- **Stdio Transport**: Notifications are sent as JSON-RPC 2.0 messages to stdout
+
+#### Usage Example
+
+```ruby
+server = MCP::Server.new(name: "my_server")
+transport = MCP::Transports::HTTP.new(server)
+server.transport = transport
+
+# When tools change, notify clients
+server.define_tool(name: "new_tool") { |**args| { result: "ok" } }
+server.notify_tools_list_changed()
+```
+
 ### Unsupported Features ( to be implemented in future versions )
 
-- Notifications
 - Log Level
 - Resource subscriptions
 - Completions
-- Complete StreamableHTTP implementation with streaming responses
 
 ### Usage
 
 #### Rails Controller
 
 When added to a Rails controller on a route that handles POST requests, your server will be compliant with non-streaming
-[StreamableHTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport
+[Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport
 requests.
 
 You can use the `Server#handle_json` method to handle requests.
@@ -84,9 +174,8 @@ end
 If you want to build a local command-line application, you can use the stdio transport:
 
 ```ruby
-#!/usr/bin/env ruby
 require "mcp"
-require "mcp/transports/stdio"
+require "mcp/server/transports/stdio_transport"
 
 # Create a simple tool
 class ExampleTool < MCP::Tool
@@ -115,17 +204,16 @@ server = MCP::Server.new(
 )
 
 # Create and start the transport
-transport = MCP::Transports::StdioTransport.new(server)
+transport = MCP::Server::Transports::StdioTransport.new(server)
 transport.open
 ```
 
 You can run this script and then type in requests to the server at the command line.
 
-```
-$ ./stdio_server.rb
-{"jsonrpc":"2.0","id":"1","result":"pong"}
-{"jsonrpc":"2.0","id":"2","result":["ExampleTool"]}
-{"jsonrpc":"2.0","id":"3","result":["ExampleTool"]}
+```console
+$ ruby examples/stdio_server.rb
+{"jsonrpc":"2.0","id":"1","method":"ping"}
+{"jsonrpc":"2.0","id":"2","method":"tools/list"}
 ```
 
 ## Configuration
@@ -179,11 +267,13 @@ server = MCP::Server.new(
 The `server_context` is a user-defined hash that is passed into the server instance and made available to tools, prompts, and exception/instrumentation callbacks. It can be used to provide contextual information such as authentication state, user IDs, or request-specific data.
 
 **Type:**
+
 ```ruby
 server_context: { [String, Symbol] => Any }
 ```
 
 **Example:**
+
 ```ruby
 server = MCP::Server.new(
   name: "my_server",
@@ -203,6 +293,7 @@ The exception reporter receives:
 - `server_context`: The context hash provided to the server
 
 **Signature:**
+
 ```ruby
 exception_reporter = ->(exception, server_context) { ... }
 ```
@@ -219,12 +310,14 @@ The instrumentation callback receives a hash with the following possible keys:
 - `duration`: (Float) Duration of the call in seconds
 
 **Type:**
+
 ```ruby
 instrumentation_callback = ->(data) { ... }
 # where data is a Hash with keys as described above
 ```
 
 **Example:**
+
 ```ruby
 config.instrumentation_callback = ->(data) {
   puts "Instrumentation: #{data.inspect}"
@@ -245,7 +338,7 @@ This will make all new server instances use the specified protocol version inste
 MCP::Server.protocol_version = nil
 ```
 
-Be sure to check the [MCP spec](https://spec.modelcontextprotocol.io/specification/2024-11-05/) for the protocol version to understand the supported features for the version being set.
+Be sure to check the [MCP spec](https://modelcontextprotocol.io/specification/2025-03-26) for the protocol version to understand the supported features for the version being set.
 
 ### Exception Reporting
 
@@ -438,8 +531,8 @@ To register a handler pass a proc/lambda to as `instrumentation_callback` into t
 MCP.configure do |config|
   config.instrumentation_callback = ->(data) {
     puts "Got instrumentation data #{data.inspect}"
-  end
-}
+  }
+end
 ```
 
 The data contains the following keys:
@@ -461,9 +554,10 @@ The `MCP::Resource` class provides a way to register resources with the server.
 
 ```ruby
 resource = MCP::Resource.new(
-  uri: "example.com/my_resource",
-  mime_type: "text/plain",
-  text: "Lorem ipsum dolor sit amet"
+  uri: "https://example.com/my_resource",
+  name: "My Resource",
+  description: "Lorem ipsum dolor sit amet",
+  mime_type: "text/html",
 )
 
 server = MCP::Server.new(
@@ -479,13 +573,13 @@ server.resources_read_handler do |params|
   [{
     uri: params[:uri],
     mimeType: "text/plain",
-    text: "Hello, world!",
+    text: params[:uri],
   }]
 end
 
 ```
 
-otherwise 'resources/read' requests will be a no-op.
+otherwise `resources/read` requests will be a no-op.
 
 ## Releases
 
@@ -494,7 +588,8 @@ 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. **Create A PR and get approval from a maintainer**
-3. **Merge your PR to the main branch** - This will automatically trigger the release workflow via GitHub Actions
+1. **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
+1. **Create a PR and get approval from a maintainer**
+1. **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/examples/README.md

@@ -0,0 +1,197 @@
+# MCP Ruby Examples
+
+This directory contains examples of how to use the Model Context Protocol (MCP) Ruby library.
+
+## Available Examples
+
+### 1. STDIO Server (`stdio_server.rb`)
+
+A simple server that communicates over standard input/output. This is useful for desktop applications and command-line tools.
+
+**Usage:**
+
+```console
+$ ruby examples/stdio_server.rb
+{"jsonrpc":"2.0","id":0,"method":"tools/list"}
+```
+
+### 2. HTTP Server (`http_server.rb`)
+
+A standalone HTTP server built with Rack that implements the MCP Streamable HTTP transport protocol. This demonstrates how to create a web-based MCP server with session management and Server-Sent Events (SSE) support.
+
+**Features:**
+
+- HTTP transport with Server-Sent Events (SSE) for streaming
+- Session management with unique session IDs
+- Example tools, prompts, and resources
+- JSON-RPC 2.0 protocol implementation
+- Full MCP protocol compliance
+
+**Usage:**
+
+```console
+$ ruby examples/http_server.rb
+```
+
+The server will start on `http://localhost:9292` and provide:
+
+- **Tools**:
+  - `ExampleTool` - adds two numbers
+  - `echo` - echoes back messages
+- **Prompts**: `ExamplePrompt` - echoes back arguments as a prompt
+- **Resources**: `test_resource` - returns example content
+
+### 3. HTTP Client Example (`http_client.rb`)
+
+A client that demonstrates how to interact with the HTTP server using all MCP protocol methods.
+
+**Usage:**
+
+1. Start the HTTP server in one terminal:
+
+   ```console
+   $ ruby examples/http_server.rb
+   ```
+
+2. Run the client example in another terminal:
+   ```console
+   $ ruby examples/http_client.rb
+   ```
+
+The client will demonstrate:
+
+- Session initialization
+- Ping requests
+- Listing and calling tools
+- Listing and getting prompts
+- Listing and reading resources
+- Session cleanup
+
+### 4. Streamable HTTP Server (`streamable_http_server.rb`)
+
+A specialized HTTP server designed to test and demonstrate Server-Sent Events (SSE) functionality in the MCP protocol.
+
+**Features:**
+
+- Tools specifically designed to trigger SSE notifications
+- Real-time progress updates and notifications
+- Detailed SSE-specific logging
+
+**Available Tools:**
+
+- `NotificationTool` - Send custom SSE notifications with optional delays
+- `echo` - Simple echo tool for basic testing
+
+**Usage:**
+
+```console
+$ ruby examples/streamable_http_server.rb
+```
+
+The server will start on `http://localhost:9393` and provide detailed instructions for testing SSE functionality.
+
+### 5. Streamable HTTP Client (`streamable_http_client.rb`)
+
+An interactive client that connects to the SSE stream and provides a menu-driven interface for testing SSE functionality.
+
+**Features:**
+
+- Automatic SSE stream connection
+- Interactive menu for triggering various SSE events
+- Real-time display of received SSE notifications
+- Session management
+
+**Usage:**
+
+1. Start the SSE test server in one terminal:
+
+   ```console
+   $ ruby examples/streamable_http_server.rb
+   ```
+
+2. Run the SSE test client in another terminal:
+   ```console
+   $ ruby examples/streamable_http_client.rb
+   ```
+
+The client will:
+
+- Initialize a session automatically
+- Connect to the SSE stream
+- Provide an interactive menu to trigger notifications
+- Display all received SSE events in real-time
+
+### Testing SSE with cURL
+
+You can also test SSE functionality manually using cURL:
+
+1. Initialize a session:
+
+```console
+SESSION_ID=$(curl -D - -s -o /dev/null http://localhost:9393 \
+  --json '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl-test","version":"1.0"}}}' | grep -i "Mcp-Session-Id:" | cut -d' ' -f2- | tr -d '\r')
+```
+
+2. Connect to SSE stream (in one terminal):
+
+```console
+curl -i -N -H "Mcp-Session-Id: $SESSION_ID" http://localhost:9393
+```
+
+3. Trigger notifications (in another terminal):
+
+```console
+# Send immediate notification
+curl -i http://localhost:9393 \
+  -H "Mcp-Session-Id: $SESSION_ID" \
+  --json '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"notification_tool","arguments":{"message":"Hello from cURL!"}}}'
+```
+
+## Streamable HTTP Transport Details
+
+### Protocol Flow
+
+The HTTP server implements the MCP Streamable HTTP transport protocol:
+
+1. **Initialize Session**:
+
+   - Client sends POST request with `initialize` method
+   - Server responds with session ID in `Mcp-Session-Id` header
+
+2. **Establish SSE Connection** (optional):
+
+   - Client sends GET request with `Mcp-Session-Id` header
+   - Server establishes Server-Sent Events stream for notifications
+
+3. **Send Requests**:
+
+   - Client sends POST requests with JSON-RPC 2.0 format
+   - Server processes and responds with results
+
+4. **Close Session**:
+   - Client sends DELETE request with `Mcp-Session-Id` header
+
+### Example cURL Commands
+
+Initialize a session:
+
+```console
+curl -i http://localhost:9292 \
+  --json '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
+```
+
+List tools (using the session ID from initialization):
+
+```console
+curl -i http://localhost:9292 \
+  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
+  --json '{"jsonrpc":"2.0","method":"tools/list","id":2}'
+```
+
+Call a tool:
+
+```console
+curl -i http://localhost:9292 \
+  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
+  --json '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"ExampleTool","arguments":{"a":5,"b":3}}}'
+```