modelcontextprotocol/ruby-sdk
Watch
1
0
Fork
You've already forked ruby-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ruby-sdk/AGENTS.md
Koichi ITO 88831b46f6 Move the Documentation From README.md to the Documentation Site 
Move the documentation that had grown to 3000+ lines in README.md onto https://ruby.sdk.modelcontextprotocol.io
and slim the README down to a quick start and feature overview, following the Python SDK layout:

- Add 21 server pages as the docs/_server/ collection (overview plus transports, discovery, tools, prompts, resources,
  roots, sampling, elicitation, multi round-trip results, notifications, notification subscriptions, cancellation, progress,
  ping, completions, logging, pagination, server context, configuration, and custom methods), 8 client pages as
  the docs/_client/ collection (overview, transports, lifecycle, multi round-trip results, cancellation, ping, pagination,
  and authorization), and 3 extension pages as the docs/_extensions/ collection (overview, capability extensions, and MCP Apps,
  following the Extensions Overview recommendation that SDK documentation list the supported extensions) -
  one page per topic, ordered to match the sidebar of the 2026-07-28 specification, with the client-side APIs
  (pinging, cancelling, and paginating from MCP::Client) documented under Building Clients
- Add top-level Examples and Protocol Versions pages after Installation, linking the runnable examples in examples/
  and summarizing the supported protocol versions, the era model, and client negotiation
- Render the three sections as just-the-docs collections, which list every page beneath a plain category heading in
  the sidebar with no folding, and serve every page at an extensionless URL under /server/, /client/, and /extensions/,
  matching the sibling SDK documentation sites
- Replace docs/building-servers.md and docs/building-clients.md with redirects to the new section overview pages via
  jekyll-redirect-from, redirect the previously published /installation.html to its extensionless URL, fold their content
  that was missing from README.md into the new pages, and update the Tool argument keys reference comment in lib/mcp/server.rb to
  the relocated Tools page
- Reduce README.md to the badges, a compact feature overview in the Python SDK style, installation instructions, a stdio
  server and client quick start, and a License section, using absolute URLs for the remaining repository links
  so they resolve on rubygems.org
- Adapt formatting where GitHub rendering habits break on the site: convert the numbered "three ways to define" lists into headings,
  since kramdown restarts numbering at 1 when code blocks split list items, convert GitHub-style alerts into just-the-docs callouts
  with the SEP-2260 server-to-client association note raised to a red warning, merge the duplicated Exception Reporting
  and Configuration Block Data sections into the Configuration page, and relocate the Streamable HTTP settings that were nested under
  the Logging section into the Transports page
- Refresh the migrated content against the current implementation: correct stale claims and broken samples the README carried,
  note on each session-era feature how it relates to the modern lifecycle of MCP 2026-07-28, and point spec links at the latest revision,
  keeping deliberate 2025-11-25 pins for pages the modern revision removed
- Style the site after the Rails API documentation palette (red links and accents on neutral surfaces) with matching
  light and dark color schemes, center the sidebar and content as one block, add a Previous/Next footer pager following
  the sidebar order, open external links in a new tab, and serve the MCP logo as the favicon

Every code block and heading from the previous README was verified to have a home in the new docs pages or the slimmed README before
the reduction; a few samples were corrected rather than copied, as noted above.
2026-08-21 13:24:04 +09:00

5.7 KiB
Raw Blame History

AGENTS.md

Project overview

This is the official Ruby SDK for the Model Context Protocol (MCP), implementing both server and client functionality for JSON-RPC 2.0 based communication between LLM applications and context providers.

Dev environment setup

  • Ruby 3.2.0+ required to run the full test suite, including all Sorbet-related features
  • Run bundle install to install dependencies
  • Dependencies: json-schema >= 4.1 - Schema validation

Build and test commands

  • bundle install - Install dependencies
  • rake test - Run all tests
  • rake rubocop - Run linter
  • rake - Run tests and linting (default task)
  • bundle exec rake conformance - Run the MCP conformance suite (see conformance/README.md)
  • ruby -I lib -I test test/path/to/specific_test.rb - Run single test file
  • gem build mcp.gemspec - Build the gem

Testing instructions

  • Test files are in test/ directory with _test.rb suffix
  • Run full test suite with rake test
  • Run individual tests with ruby -I lib -I test test/path/to/file_test.rb
  • Tests should pass before submitting PRs

Code style guidelines

  • Follow RuboCop rules (run rake rubocop)
  • Use frozen string literals
  • Follow Ruby community conventions
  • Keep dependencies minimal
  • Use lowercase HTTP response header names (e.g. mcp-session-id); the Rack 3 SPEC requires this, and the MCP spec's Mcp-Session-Id casing is prose convention only

Documentation

  • User-facing documentation lives in docs/, one page per topic, published at https://ruby.sdk.modelcontextprotocol.io (deploys only when a release is published)
  • Pages live in the docs/_server/, docs/_client/, and docs/_extensions/ collections
  • Keep README.md slim: quick start and pointers only; document features on the relevant docs page
  • Internal links are absolute and extensionless (e.g. /server/tools/); front matter is followed by a blank line before the h1
  • Callout tiers: .note (supplementary), .important (spec constraints), .warning (deprecated features)

Commit message conventions

  • Use conventional commit format when possible
  • Include clear, descriptive commit messages
  • Releases are triggered by updating version in lib/mcp/version.rb and merging to main

Release process

  • Follow Keep a Changelog format in CHANGELOG.md
  • Update CHANGELOG.md before cutting releases
  • Use git history and PR merge commits to construct changelog entries
  • Format entries as: "Terse description of the change (#nnn)"
  • Keep entries in flat list format (no nesting)
  • Git tags mark commits that cut new releases
  • Exclude maintenance PRs that don't concern end users
  • Check upstream remote for PRs if available

Architecture overview

Core Components

MCP::Server (lib/mcp/server.rb):

  • Main server class handling JSON-RPC requests and holding shared configuration (tools, prompts, resources, handlers, capabilities)
  • Implements MCP protocol methods: initialize, ping, tools/list, tools/call, prompts/list, prompts/get, resources/list, resources/read
  • Supports custom method registration via define_custom_method
  • Handles instrumentation, exception reporting, and notifications
  • Uses JsonRpcHandler for request processing

MCP::ServerSession (lib/mcp/server_session.rb):

  • Per-connection state: client info, logging level
  • Created by the transport layer for each client connection
  • Delegates request handling to the shared Server

MCP::Client (lib/mcp/client.rb):

  • Client interface for communicating with MCP servers
  • Transport-agnostic design with pluggable transport layers
  • Supports tool listing and invocation

Transport Layer:

  • MCP::Server::Transports::StdioTransport - Command-line stdio transport
  • MCP::Server::Transports::StreamableHttpTransport - HTTP with streaming support
  • MCP::Client::HTTP - HTTP client transport (requires faraday gem)

Protocol Components:

  • MCP::Tool - Tool definition with input/output schemas and annotations
  • MCP::Prompt - Prompt templates with argument validation
  • MCP::Resource - Resource registration and retrieval
  • MCP::Configuration - Global configuration with exception reporting and instrumentation

Key Patterns

Three Ways to Define Components:

  1. Class inheritance (e.g., class MyTool < MCP::Tool)
  2. Define methods (e.g., MCP::Tool.define(name: "my_tool") { ... })
  3. Server registration (e.g., server.define_tool(name: "my_tool") { ... })

Schema Validation:

  • Tools support input_schema and output_schema for JSON Schema validation
  • Protocol version 2025-03-26+ supports tool annotations (destructive_hint, idempotent_hint, etc.)
  • Validation is configurable via configuration.validate_tool_call_arguments

Session Architecture:

  • Server holds shared configuration (tools, prompts, resources, handlers)
  • ServerSession holds per-connection state (client info, logging level)
  • Both StdioTransport and StreamableHTTPTransport create a ServerSession per connection, making the session model transparent across transports
  • Session-scoped notifications (notify_progress, notify_log_message) are sent only to the originating client via ServerSession
  • Server-wide notifications (notify_tools_list_changed, etc.) broadcast to all sessions via Server

Context Passing:

  • server_context hash passed through tool/prompt calls for request-specific data
  • Methods can accept server_context: keyword argument for accessing context

Integration patterns

  • Rails/Rack apps: Mount StreamableHTTPTransport as a Rack app (e.g., mount transport => "/mcp")
  • Command-line tools: Use StdioTransport.new(server).open for CLI applications
  • HTTP services: Use StreamableHTTPTransport for web-based servers