Skip to content

Commit 5d0c5b7

Browse files
julianojuliojulianojulio
committed
Merge remote-tracking branch 'upstream/main' into make_server_context_optional_and_sorbet_friendly
2 parents c10c0dd + af686a3 commit 5d0c5b7

25 files changed

+2885
-22
lines changed

‎README.md

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ It implements the Model Context Protocol specification, handling model context r
3333
- Manages tool registration and invocation
3434
- Supports prompt registration and execution
3535
- Supports resource registration and retrieval
36+
- Supports stdio & Streamable HTTP (including SSE) transports
37+
- Supports notifications for list changes (tools, prompts, resources)
3638

3739
### Supported Methods
3840
- `initialize` - Initializes the protocol and returns server capabilities
@@ -45,20 +47,53 @@ It implements the Model Context Protocol specification, handling model context r
4547
- `resources/read` - Retrieves a specific resource by name
4648
- `resources/templates/list` - Lists all registered resource templates and their schemas
4749

50+
### Notifications
51+
52+
The server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling.
53+
54+
#### Notification Methods
55+
56+
The server provides three notification methods:
57+
- `notify_tools_list_changed()` - Send a notification when the tools list changes
58+
- `notify_prompts_list_changed()` - Send a notification when the prompts list changes
59+
- `notify_resources_list_changed()` - Send a notification when the resources list changes
60+
61+
#### Notification Format
62+
63+
Notifications follow the JSON-RPC 2.0 specification and use these method names:
64+
- `notifications/tools/list_changed`
65+
- `notifications/prompts/list_changed`
66+
- `notifications/resources/list_changed`
67+
68+
#### Transport Support
69+
70+
- **HTTP Transport**: Notifications are sent as Server-Sent Events (SSE) to all connected sessions
71+
- **Stdio Transport**: Notifications are sent as JSON-RPC 2.0 messages to stdout
72+
73+
#### Usage Example
74+
75+
```ruby
76+
server = MCP::Server.new(name: "my_server")
77+
transport = MCP::Transports::HTTP.new(server)
78+
server.transport = transport
79+
80+
# When tools change, notify clients
81+
server.define_tool(name: "new_tool") { |**args| { result: "ok" } }
82+
server.notify_tools_list_changed()
83+
```
84+
4885
### Unsupported Features ( to be implemented in future versions )
4986

50-
- Notifications
5187
- Log Level
5288
- Resource subscriptions
5389
- Completions
54-
- Complete StreamableHTTP implementation with streaming responses
5590

5691
### Usage
5792

5893
#### Rails Controller
5994

6095
When added to a Rails controller on a route that handles POST requests, your server will be compliant with non-streaming
61-
[StreamableHTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport
96+
[Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport
6297
requests.
6398

6499
You can use the `Server#handle_json` method to handle requests.
@@ -244,7 +279,7 @@ This will make all new server instances use the specified protocol version inste
244279
MCP::Server.protocol_version = nil
245280
```
246281

247-
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.
282+
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.
248283

249284
### Exception Reporting
250285

‎examples/README.md

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# MCP Ruby Examples
2+
3+
This directory contains examples of how to use the Model Context Protocol (MCP) Ruby library.
4+
5+
## Available Examples
6+
7+
### 1. STDIO Server (`stdio_server.rb`)
8+
A simple server that communicates over standard input/output. This is useful for desktop applications and command-line tools.
9+
10+
**Usage:**
11+
```bash
12+
ruby examples/stdio_server.rb
13+
{"jsonrpc":"2.0","id":0,"method":"tools/list"}
14+
```
15+
16+
### 2. HTTP Server (`http_server.rb`)
17+
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.
18+
19+
**Features:**
20+
- HTTP transport with Server-Sent Events (SSE) for streaming
21+
- Session management with unique session IDs
22+
- Example tools, prompts, and resources
23+
- JSON-RPC 2.0 protocol implementation
24+
- Full MCP protocol compliance
25+
26+
**Usage:**
27+
```bash
28+
ruby examples/http_server.rb
29+
```
30+
31+
The server will start on `http://localhost:9292` and provide:
32+
- **Tools**:
33+
- `ExampleTool` - adds two numbers
34+
- `echo` - echoes back messages
35+
- **Prompts**: `ExamplePrompt` - echoes back arguments as a prompt
36+
- **Resources**: `test_resource` - returns example content
37+
38+
### 3. HTTP Client Example (`http_client.rb`)
39+
A client that demonstrates how to interact with the HTTP server using all MCP protocol methods.
40+
41+
**Usage:**
42+
1. Start the HTTP server in one terminal:
43+
```bash
44+
ruby examples/http_server.rb
45+
```
46+
47+
2. Run the client example in another terminal:
48+
```bash
49+
ruby examples/http_client.rb
50+
```
51+
52+
The client will demonstrate:
53+
- Session initialization
54+
- Ping requests
55+
- Listing and calling tools
56+
- Listing and getting prompts
57+
- Listing and reading resources
58+
- Session cleanup
59+
60+
### 4. Streamable HTTP Server (`streamable_http_server.rb`)
61+
A specialized HTTP server designed to test and demonstrate Server-Sent Events (SSE) functionality in the MCP protocol.
62+
63+
**Features:**
64+
- Tools specifically designed to trigger SSE notifications
65+
- Real-time progress updates and notifications
66+
- Detailed SSE-specific logging
67+
68+
**Available Tools:**
69+
- `NotificationTool` - Send custom SSE notifications with optional delays
70+
- `echo` - Simple echo tool for basic testing
71+
72+
**Usage:**
73+
```bash
74+
ruby examples/streamable_http_server.rb
75+
```
76+
77+
The server will start on `http://localhost:9393` and provide detailed instructions for testing SSE functionality.
78+
79+
### 5. Streamable HTTP Client (`streamable_http_client.rb`)
80+
An interactive client that connects to the SSE stream and provides a menu-driven interface for testing SSE functionality.
81+
82+
**Features:**
83+
- Automatic SSE stream connection
84+
- Interactive menu for triggering various SSE events
85+
- Real-time display of received SSE notifications
86+
- Session management
87+
88+
**Usage:**
89+
1. Start the SSE test server in one terminal:
90+
```bash
91+
ruby examples/streamable_http_server.rb
92+
```
93+
94+
2. Run the SSE test client in another terminal:
95+
```bash
96+
ruby examples/streamable_http_client.rb
97+
```
98+
99+
The client will:
100+
- Initialize a session automatically
101+
- Connect to the SSE stream
102+
- Provide an interactive menu to trigger notifications
103+
- Display all received SSE events in real-time
104+
105+
### Testing SSE with cURL
106+
107+
You can also test SSE functionality manually using cURL:
108+
109+
1. Initialize a session:
110+
```bash
111+
SESSION_ID=$(curl -D - -s -o /dev/null -X POST http://localhost:9393 \
112+
-H "Content-Type: application/json" \
113+
-d '{"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')
114+
```
115+
116+
2. Connect to SSE stream (in one terminal):
117+
```bash
118+
curl -N -H "Mcp-Session-Id: $SESSION_ID" http://localhost:9393
119+
```
120+
121+
3. Trigger notifications (in another terminal):
122+
```bash
123+
# Send immediate notification
124+
curl -X POST http://localhost:9393 \
125+
-H "Content-Type: application/json" \
126+
-H "Mcp-Session-Id: $SESSION_ID" \
127+
-d '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"notification_tool","arguments":{"message":"Hello from cURL!"}}}'
128+
```
129+
130+
## Streamable HTTP Transport Details
131+
132+
### Protocol Flow
133+
134+
The HTTP server implements the MCP Streamable HTTP transport protocol:
135+
136+
1. **Initialize Session**:
137+
- Client sends POST request with `initialize` method
138+
- Server responds with session ID in `Mcp-Session-Id` header
139+
140+
2. **Establish SSE Connection** (optional):
141+
- Client sends GET request with `Mcp-Session-Id` header
142+
- Server establishes Server-Sent Events stream for notifications
143+
144+
3. **Send Requests**:
145+
- Client sends POST requests with JSON-RPC 2.0 format
146+
- Server processes and responds with results
147+
148+
4. **Close Session**:
149+
- Client sends DELETE request with `Mcp-Session-Id` header
150+
151+
### Example cURL Commands
152+
153+
Initialize a session:
154+
```bash
155+
curl -X POST http://localhost:9292 \
156+
-H "Content-Type: application/json" \
157+
-d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
158+
```
159+
160+
List tools (using the session ID from initialization):
161+
```bash
162+
curl -X POST http://localhost:9292 \
163+
-H "Content-Type: application/json" \
164+
-H "Mcp-Session-Id: YOUR_SESSION_ID" \
165+
-d '{"jsonrpc":"2.0","method":"tools/list","id":2}'
166+
```
167+
168+
Call a tool:
169+
```bash
170+
curl -X POST http://localhost:9292 \
171+
-H "Content-Type: application/json" \
172+
-H "Mcp-Session-Id: YOUR_SESSION_ID" \
173+
-d '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"ExampleTool","arguments":{"a":5,"b":3}}}'
174+
```

0 commit comments

Comments
 (0)