Skip to content
Prev Previous commit
Add blank lines after headings
Co-authored-by: Koichi ITO <koic.ito@gmail.com>
  • Loading branch information
atesgoral and koic committed Sep 14, 2025
commit 1249d63a9f828d67d7e2b82b64354275b2bc03c9
17 changes: 17 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,17 @@
# 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
- Run `bundle install` to install dependencies
- Dependencies: `json_rpc_handler` ~> 0.1, `json-schema` >= 4.1

## Build and test commands

- `bundle install` - Install dependencies
- `rake test` - Run all tests
- `rake rubocop` - Run linter
Expand All @@ -17,23 +20,27 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing
- `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

## 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](https://keepachangelog.com/en/1.1.0/) format in CHANGELOG.md
- Update CHANGELOG.md before cutting releases
- Use git history and PR merge commits to construct changelog entries
Expand All @@ -48,23 +55,27 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing
### Core Components

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

- Main server class handling JSON-RPC requests
- 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::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
Expand All @@ -73,30 +84,36 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing
### 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`

**Context Passing**:

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

### Dependencies

- `json_rpc_handler` ~> 0.1 - JSON-RPC 2.0 message handling
- `json-schema` >= 4.1 - Schema validation
- Ruby 3.2.0+ required

### Integration patterns

- **Rails controllers**: Use `server.handle_json(request.body.read)` for HTTP endpoints
- **Command-line tools**: Use `StdioTransport.new(server).open` for CLI applications
- **HTTP services**: Use `StreamableHttpTransport` for web-based servers

### Component definition patterns

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