Skip to content

Commit 9603b2f

Browse files
koickoic
committed
Support running MCP client conformance tests against the Ruby SDK
## Motivation and Context PR modelcontextprotocol#248 introduced server conformance testing using `@modelcontextprotocol/conformance`. This extends coverage to the client side so that `MCP::Client` behavior can also be validated against the MCP specification. ### Scope Client conformance is driven by the conformance runner, which spawns test servers for each scenario and invokes `conformance/client.rb` against them. The client script delegates the MCP initialize handshake to `MCP::Client#connect` and executes scenario-specific operations (for example listing tools or calling a tool). ### Usage Run all conformance tests (server + client): ```console bundle exec rake conformance ``` Run a single client scenario: ```console bundle exec rake conformance SCENARIO=initialize ``` List available scenarios: ```console bundle exec rake conformance_list ``` ## How Has This Been Tested? Ran `bundle exec rake conformance` locally. - Server conformance: 40 passed, 0 failed. - Client conformance: 3 passed, 54 failed (all 54 listed in `expected_failures.yml`). ## Breaking Change No. This change only adds test infrastructure under `conformance/` and does not modify SDK behavior.
1 parent d186988 commit 9603b2f

6 files changed

Lines changed: 131 additions & 17 deletions

File tree

‎Rakefile‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,22 +20,25 @@ desc "Run MCP conformance tests (PORT, SCENARIO, SPEC_VERSION, VERBOSE)"
2020
task :conformance do |t|
2121
next unless npx_available?(t.name)
2222

23-
require_relative "conformance/runner"
23+
require_relative "conformance/server_runner"
24+
require_relative "conformance/client_runner"
2425

2526
options = {}
2627
options[:port] = Integer(ENV["PORT"]) if ENV["PORT"]
2728
options[:scenario] = ENV["SCENARIO"] if ENV["SCENARIO"]
2829
options[:spec_version] = ENV["SPEC_VERSION"] if ENV["SPEC_VERSION"]
2930
options[:verbose] = true if ENV["VERBOSE"]
3031

31-
Conformance::Runner.new(**options).run
32+
Conformance::ServerRunner.new(**options).run
33+
Conformance::ClientRunner.new(**options.except(:port)).run
3234
end
3335

3436
desc "List available conformance scenarios"
3537
task :conformance_list do |t|
3638
next unless npx_available?(t.name)
3739

3840
system("npx", "--yes", "@modelcontextprotocol/conformance", "list", "--server")
41+
system("npx", "--yes", "@modelcontextprotocol/conformance", "list", "--client")
3942
end
4043

4144
desc "Start the conformance server (PORT)"

‎conformance/README.md‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -15,22 +15,22 @@ Validates the Ruby SDK's conformance to the MCP specification using [`@modelcont
1515
bundle exec rake conformance
1616
```
1717

18-
Starts the conformance server, runs all active scenarios against it, prints a pass/fail
19-
summary for each scenario, and exits with a non-zero status code if any unexpected failures
20-
are detected. Scenarios listed in `expected_failures.yml` are allowed to fail without
21-
affecting the exit code.
18+
Runs both server and client conformance tests in sequence. Server conformance starts the
19+
conformance server and tests it. Client conformance spawns test servers for each scenario
20+
and invokes `conformance/client.rb` against them. Scenarios listed in `expected_failures.yml`
21+
are allowed to fail without affecting the exit code.
2222

2323
### Environment variables
2424

25-
| Variable | Description | Default |
26-
|----------------|--------------------------------------|---------|
27-
| `PORT` | Server port | `9292` |
28-
| `SCENARIO` | Run a single scenario by name | (all) |
29-
| `SPEC_VERSION` | Filter scenarios by spec version | (all) |
30-
| `VERBOSE` | Show raw JSON output when set | (off) |
25+
| Variable | Description | Default |
26+
|----------------|---------------------------------------|---------|
27+
| `PORT` | Server port (server conformance only) | `9292` |
28+
| `SCENARIO` | Run a single scenario by name | (all) |
29+
| `SPEC_VERSION` | Filter scenarios by spec version | (all) |
30+
| `VERBOSE` | Show raw JSON output when set | (off) |
3131

3232
```bash
33-
# Run a single scenario
33+
# Run a single server scenario
3434
bundle exec rake conformance SCENARIO=ping
3535

3636
# Use a different port with verbose output
@@ -91,8 +91,10 @@ submissions.
9191
```
9292
conformance/
9393
server.rb # Conformance server (Rack + Puma, default port 9292)
94-
runner.rb # Starts the server, runs npx conformance, exits with result code
95-
expected_failures.yml # Baseline of known-failing scenarios
94+
server_runner.rb # Starts the server, runs npx conformance server, exits with result code
95+
client.rb # Conformance client (invoked by npx conformance client)
96+
client_runner.rb # Runs npx conformance client, exits with result code
97+
expected_failures.yml # Baseline of known-failing scenarios (server and client)
9698
README.md # This file
9799
```
98100

‎conformance/client.rb‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# frozen_string_literal: true
2+
3+
# Conformance test client for the MCP Ruby SDK.
4+
# Invoked by the conformance runner:
5+
# MCP_CONFORMANCE_SCENARIO=<scenario> bundle exec ruby conformance/client.rb <server-url>
6+
#
7+
# The server URL is passed as the last positional argument.
8+
# The scenario name is read from the MCP_CONFORMANCE_SCENARIO environment variable,
9+
# which is set automatically by the conformance test runner.
10+
11+
require_relative "../lib/mcp"
12+
13+
scenario = ENV["MCP_CONFORMANCE_SCENARIO"]
14+
server_url = ARGV.last
15+
16+
unless scenario && server_url
17+
abort("Usage: MCP_CONFORMANCE_SCENARIO=<scenario> ruby conformance/client.rb <server-url>")
18+
end
19+
20+
transport = MCP::Client::HTTP.new(url: server_url)
21+
client = MCP::Client.new(transport: transport)
22+
client.connect(client_info: { name: "ruby-sdk-conformance-client", version: MCP::VERSION })
23+
24+
case scenario
25+
when "initialize"
26+
client.tools
27+
when "tools_call"
28+
tools = client.tools
29+
add_numbers = tools.find { |t| t.name == "add_numbers" }
30+
abort("Tool add_numbers not found") unless add_numbers
31+
client.call_tool(tool: add_numbers, arguments: { a: 1, b: 2 })
32+
else
33+
abort("Unknown or unsupported scenario: #{scenario}")
34+
end

‎conformance/client_runner.rb‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# frozen_string_literal: true
2+
3+
# Runs `npx @modelcontextprotocol/conformance client` against the conformance client script.
4+
require "English"
5+
6+
module Conformance
7+
class ClientRunner
8+
def initialize(scenario: nil, spec_version: nil, verbose: false)
9+
@scenario = scenario
10+
@spec_version = spec_version
11+
@verbose = verbose
12+
end
13+
14+
def run
15+
command = build_command
16+
puts "Command: #{command.join(" ")}\n\n"
17+
18+
system(*command)
19+
conformance_exit_code = $CHILD_STATUS.exitstatus
20+
exit(conformance_exit_code || 1) unless conformance_exit_code == 0
21+
end
22+
23+
private
24+
25+
def build_command
26+
expected_failures_yml = File.expand_path("expected_failures.yml", __dir__)
27+
client_script = File.expand_path("client.rb", __dir__)
28+
29+
npx_command = [
30+
"npx",
31+
"--yes",
32+
"@modelcontextprotocol/conformance",
33+
"client",
34+
"--command",
35+
"bundle exec ruby #{client_script}",
36+
]
37+
npx_command += if @scenario
38+
["--scenario", @scenario]
39+
else
40+
["--suite", "all"]
41+
end
42+
npx_command += ["--spec-version", @spec_version] if @spec_version
43+
npx_command += ["--verbose"] if @verbose
44+
npx_command += ["--expected-failures", expected_failures_yml]
45+
npx_command
46+
end
47+
end
48+
end

‎conformance/expected_failures.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,28 @@
11
server: []
2+
client:
3+
# TODO: SSE reconnection not implemented in Ruby client.
4+
- sse-retry
5+
# TODO: Elicitation not implemented in Ruby client.
6+
- elicitation-sep1034-client-defaults
7+
# TODO: OAuth/auth not implemented in Ruby client.
8+
- auth/metadata-default
9+
- auth/metadata-var1
10+
- auth/metadata-var2
11+
- auth/metadata-var3
12+
- auth/basic-cimd
13+
- auth/scope-from-www-authenticate
14+
- auth/scope-from-scopes-supported
15+
- auth/scope-omitted-when-undefined
16+
- auth/scope-step-up
17+
- auth/scope-retry-limit
18+
- auth/token-endpoint-auth-basic
19+
- auth/token-endpoint-auth-post
20+
- auth/token-endpoint-auth-none
21+
- auth/pre-registration
22+
- auth/2025-03-26-oauth-metadata-backcompat
23+
- auth/2025-03-26-oauth-endpoint-fallback
24+
- auth/client-credentials-jwt
25+
- auth/client-credentials-basic
26+
- auth/cross-app-access-complete-flow
27+
- auth/offline-access-scope
28+
- auth/offline-access-not-supported

conformance/runner.rb renamed to conformance/server_runner.rb

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
require_relative "server"
77

88
module Conformance
9-
class Runner
9+
class ServerRunner
1010
# Timeout for waiting for the Puma server to start.
1111
SERVER_START_TIMEOUT = 20
1212
SERVER_POLL_INTERVAL = 0.5
@@ -83,7 +83,7 @@ def run_conformance(command, server_pid:)
8383
terminate_server(server_pid)
8484
end
8585

86-
exit(conformance_exit_code || 1)
86+
exit(conformance_exit_code || 1) unless conformance_exit_code == 0
8787
end
8888

8989
def terminate_server(pid)

0 commit comments

Comments
 (0)