Test example code

This adds sanity tests to ensure that example code in the `examples/`
directory and `README.md` isn't outright wrong. These are not intended
to serve as unit tests for the example functionality, just as smoke
tests to catch things like API changes that require updating examples.

Including a sanity test ensures that the example code isn't outright
wrong. This is not intended to serve as unit tests for the example
functionality.

Some minor changes are included which facilitate this work:

- Use `console` instead of `bash` codeblock language

    `console` highlights `$ ` prefixed lines differently from the
    following lines, which clearly distinguishes between commands and
    input/output.

- Set `file_fixture_path`

    This allows us to use `ActiveSupport::TestCase#file_fixture`.

- Add `ReadmeTestHelper`

    This helper provides utilities for extracting code snippets from
    `README.md`.

Some of these tests revealed that either the examples were busted, or
even bugs in the implementation.

- Test README per-server configuration example

    This test revealed that the `define_` helper methods were failing to
    ensure the server supports the type of capability they were
    defining.

- Test README protocol version examples

    This revealed that the `protocol_version` accessors weren't
    available on the `Server` at all, and the examples were incorrect.

- Test README tool definition examples

    This revealed that the `define` example doesn't work, and the fix is unclear.

Author: sambostock

.rubocop.yml

@@ -4,3 +4,7 @@ inherit_gem:
 plugins:
   - rubocop-minitest
   - rubocop-rake
+
+Security/Eval:
+  Exclude:
+    - test/fixtures/files/code_snippet_wrappers/**/*.rb # We must often resort to eval to access local variable

README.md

@@ -12,13 +12,13 @@ gem 'mcp'
 
 And then execute:
 
-```bash
+```console
 $ bundle install
 ```
 
 Or install it yourself as:
 
-```bash
+```console
 $ gem install mcp
 ```
 
@@ -98,6 +98,7 @@ requests.
 
 You can use the `Server#handle_json` method to handle requests.
 
+<!-- SNIPPET ID: rails_controller -->
 ```ruby
 class ApplicationController < ActionController::Base
 
@@ -118,6 +119,7 @@ end
 
 If you want to build a local command-line application, you can use the stdio transport:
 
+<!-- SNIPPET ID: stdio_transport -->
 ```ruby
 #!/usr/bin/env ruby
 require "mcp"
@@ -156,7 +158,8 @@ transport.open
 
 You can run this script and then type in requests to the server at the command line.
 
-```bash
+<!-- SNIPPET ID: running_stdio_server -->
+```console
 $ ./examples/stdio_server.rb
 {"jsonrpc":"2.0","id":"1","method":"ping"}
 {"jsonrpc":"2.0","id":"2","method":"tools/list"}
@@ -166,6 +169,7 @@ $ ./examples/stdio_server.rb
 
 The gem can be configured using the `MCP.configure` block:
 
+<!-- SNIPPET ID: configuration -->
 ```ruby
 MCP.configure do |config|
   config.exception_reporter = ->(exception, server_context) {
@@ -186,6 +190,7 @@ or by creating an explicit configuration and passing it into the server.
 This is useful for systems where an application hosts more than one MCP server but
 they might require different instrumentation callbacks.
 
+<!-- SNIPPET ID: per_server_configuration -->
 ```ruby
 configuration = MCP::Configuration.new
 configuration.exception_reporter = ->(exception, server_context) {
@@ -218,6 +223,8 @@ server_context: { [String, Symbol] => Any }
 ```
 
 **Example:**
+
+<!-- SNIPPET ID: server_context -->
 ```ruby
 server = MCP::Server.new(
   name: "my_server",
@@ -259,6 +266,7 @@ instrumentation_callback = ->(data) { ... }
 ```
 
 **Example:**
+<!-- SNIPPET ID: instrumentation_callback -->
 ```ruby
 config.instrumentation_callback = ->(data) {
   puts "Instrumentation: #{data.inspect}"
@@ -267,16 +275,22 @@ config.instrumentation_callback = ->(data) {
 
 ### Server Protocol Version
 
-The server's protocol version can be overridden using the `protocol_version` class method:
+The server's protocol version can be overridden via the `Configuration#protocol_version` method:
 
+<!-- SNIPPET ID: set_server_protocol_version -->
 ```ruby
-MCP::Server.protocol_version = "2024-11-05"
+MCP.configure do |config|
+  config.protocol_version = "2024-11-05"
+end
 ```
 
 This will make all new server instances use the specified protocol version instead of the default version. The protocol version can be reset to the default by setting it to `nil`:
 
+<!-- SNIPPET ID: unset_server_protocol_version -->
 ```ruby
-MCP::Server.protocol_version = nil
+MCP.configure do |config|
+  config.protocol_version = nil
+end
 ```
 
 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.
@@ -309,6 +323,7 @@ This gem provides a `MCP::Tool` class that can be used to create tools in two wa
 
 1. As a class definition:
 
+<!-- SNIPPET ID: tool_class_definition -->
 ```ruby
 class MyTool < MCP::Tool
   description "This tool performs specific functionality..."
@@ -336,6 +351,7 @@ tool = MyTool
 
 2. By using the `MCP::Tool.define` method with a block:
 
+<!-- SNIPPET ID: tool_definition_with_block -->
 ```ruby
 tool = MCP::Tool.define(
   name: "my_tool",
@@ -372,12 +388,13 @@ The `MCP::Prompt` class provides two ways to create prompts:
 
 1. As a class definition with metadata:
 
+<!-- SNIPPET ID: prompt_class_definition -->
 ```ruby
 class MyPrompt < MCP::Prompt
   prompt_name "my_prompt"  # Optional - defaults to underscored class name
   description "This prompt performs specific functionality..."
   arguments [
-    Prompt::Argument.new(
+    MCP::Prompt::Argument.new(
       name: "message",
       description: "Input message",
       required: true
@@ -386,16 +403,16 @@ class MyPrompt < MCP::Prompt
 
   class << self
     def template(args, server_context:)
-      Prompt::Result.new(
+      MCP::Prompt::Result.new(
         description: "Response description",
         messages: [
-          Prompt::Message.new(
+          MCP::Prompt::Message.new(
             role: "user",
-            content: Content::Text.new("User message")
+            content: MCP::Content::Text.new("User message")
           ),
-          Prompt::Message.new(
+          MCP::Prompt::Message.new(
             role: "assistant",
-            content: Content::Text.new(args["message"])
+            content: MCP::Content::Text.new(args[:message])
           )
         ]
       )
@@ -408,28 +425,29 @@ prompt = MyPrompt
 
 2. Using the `MCP::Prompt.define` method:
 
+<!-- SNIPPET ID: prompt_definition_with_block -->
 ```ruby
 prompt = MCP::Prompt.define(
   name: "my_prompt",
   description: "This prompt performs specific functionality...",
   arguments: [
-    Prompt::Argument.new(
+    MCP::Prompt::Argument.new(
       name: "message",
       description: "Input message",
       required: true
     )
   ]
 ) do |args, server_context:|
-  Prompt::Result.new(
+  MCP::Prompt::Result.new(
     description: "Response description",
     messages: [
-      Prompt::Message.new(
+      MCP::Prompt::Message.new(
         role: "user",
-        content: Content::Text.new("User message")
+        content: MCP::Content::Text.new("User message")
       ),
-      Prompt::Message.new(
+      MCP::Prompt::Message.new(
         role: "assistant",
-        content: Content::Text.new(args["message"])
+        content: MCP::Content::Text.new(args[:message])
       )
     ]
   )
@@ -450,6 +468,7 @@ e.g. around authentication state or user preferences.
 
 Register prompts with the MCP server:
 
+<!-- SNIPPET ID: prompts_usage -->
 ```ruby
 server = MCP::Server.new(
   name: "my_server",
@@ -468,6 +487,7 @@ The server will handle prompt listing and execution through the MCP protocol met
 The server allows registering a callback to receive information about instrumentation.
 To register a handler pass a proc/lambda to as `instrumentation_callback` into the server constructor.
 
+<!-- SNIPPET ID: prompts_instrumentation_callback -->
 ```ruby
 MCP.configure do |config|
   config.instrumentation_callback = ->(data) {
@@ -493,6 +513,7 @@ MCP spec includes [Resources](https://modelcontextprotocol.io/docs/concepts/reso
 
 The `MCP::Resource` class provides a way to register resources with the server.
 
+<!-- SNIPPET ID: resources -->
 ```ruby
 resource = MCP::Resource.new(
   uri: "https://example.com/my_resource",
@@ -509,6 +530,7 @@ server = MCP::Server.new(
 
 The server must register a handler for the `resources/read` method to retrieve a resource dynamically.
 
+<!-- SNIPPET ID: resources_read_handler -->
 ```ruby
 server.resources_read_handler do |params|
   [{

lib/mcp/server.rb

@@ -89,11 +89,13 @@ def handle_json(request)
     end
 
     def define_tool(name: nil, description: nil, input_schema: nil, annotations: nil, &block)
+      @capabilities.support_tools
       tool = Tool.define(name:, description:, input_schema:, annotations:, &block)
       @tools[tool.name_value] = tool
     end
 
     def define_prompt(name: nil, description: nil, arguments: [], &block)
+      @capabilities.support_prompts
       prompt = Prompt.define(name:, description:, arguments:, &block)
       @prompts[prompt.name_value] = prompt
     end
@@ -128,6 +130,7 @@ def resources_list_handler(&block)
     end
 
     def resources_read_handler(&block)
+      @capabilities.support_resources
       @handlers[Methods::RESOURCES_READ] = block
     end
 
@@ -142,6 +145,7 @@ def tools_list_handler(&block)
     end
 
     def tools_call_handler(&block)
+      @capabilities.support_tools
       @handlers[Methods::TOOLS_CALL] = block
     end
 
@@ -151,6 +155,7 @@ def prompts_list_handler(&block)
     end
 
     def prompts_get_handler(&block)
+      @capabilities.support_prompts
       @handlers[Methods::PROMPTS_GET] = block
     end
 

test/fixtures/files/code_snippet_wrappers/readme/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+# Stub Bugsnag
+class Bugsnag
+  class Report
+    attr_reader :metadata
+
+    def initialize
+      @metadata = {}
+    end
+
+    def add_metadata(key, value)
+      @metadata[key] = value
+    end
+  end
+
+  class << self
+    def notify(exception)
+      report = Report.new
+      yield report
+      puts "Bugsnag notified of #{exception.inspect} with metadata #{report.metadata.inspect}"
+    end
+  end
+end
+
+require_relative "code_snippet"
+
+puts MCP::Server.new(
+  tools: [
+    MCP::Tool.define(name: "error_tool") { raise "boom" },
+  ],
+).handle_json(
+  {
+    jsonrpc: "2.0",
+    id: "1",
+    method: "tools/call",
+    params: { name: "error_tool", arguments: {} },
+  }.to_json,
+)

test/fixtures/files/code_snippet_wrappers/readme/instrumentation_callback.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+MCP.configure do |config|
+  eval(File.read("code_snippet.rb"), binding)
+
+  config.instrumentation_callback.call({ example: "data" })
+end

test/fixtures/files/code_snippet_wrappers/readme/per_server_configuration.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+# Minimally mock Bugsnag for the test
+module Bugsnag
+  class Report
+    attr_reader :metadata
+
+    def initialize
+      @metadata = {}
+    end
+
+    def add_metadata(key, value)
+      @metadata[key] = value
+    end
+  end
+
+  class << self
+    def notify(exception)
+      report = Report.new
+      yield report
+      puts "Bugsnag notified of #{exception.inspect} with metadata #{report.metadata.inspect}"
+    end
+  end
+end
+
+b = binding
+eval(File.read("code_snippet.rb"), b)
+server = b.local_variable_get(:server)
+
+server.define_tool(name: "error_tool") { raise "boom" }
+
+puts server.handle_json({
+  jsonrpc: "2.0",
+  id: "1",
+  method: "tools/call",
+  params: { name: "error_tool", arguments: {} },
+}.to_json)

test/fixtures/files/code_snippet_wrappers/readme/prompt_class_definition.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+require_relative "code_snippet"
+
+b = binding
+eval(File.read("code_snippet.rb"), b)
+prompt = b.local_variable_get(:prompt)
+
+server = MCP::Server.new(prompts: [prompt])
+
+[
+  { jsonrpc: "2.0", id: "1", method: "prompts/list" },
+  { jsonrpc: "2.0", id: "2", method: "prompts/get", params: { name: "my_prompt", arguments: { message: "Test message" } } },
+].each { |request| puts server.handle_json(request.to_json) }

test/fixtures/files/code_snippet_wrappers/readme/prompt_definition_with_block.rb

@@ -0,0 +1 @@
+prompt_class_definition.rb

test/fixtures/files/code_snippet_wrappers/readme/prompts_instrumentation_callback.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "code_snippet"
+
+puts MCP::Server.new.handle_json({ jsonrpc: "2.0", id: "1", method: "ping" }.to_json)