From 38215177da4af2020632fffcd59a8b1f057a32c0 Mon Sep 17 00:00:00 2001 From: Ates Goral Date: Sun, 14 Sep 2025 00:27:30 -0400 Subject: [PATCH 1/4] Add CLAUDE.md with development guidance and architecture overview MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a7a1dea --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,74 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Development Commands + +### Core Commands +- `bundle install` - Install dependencies +- `rake test` - Run all tests +- `rake rubocop` - Run linter +- `rake` - Run tests and linting (default task) + +### Testing +- `ruby -I lib -I test test/path/to/specific_test.rb` - Run single test file +- Test files are located in `test/` directory with `_test.rb` suffix + +### Gem Management +- `gem build mcp.gemspec` - Build the gem +- Releases are triggered by updating version in `lib/mcp/version.rb` and merging to main + +## Architecture 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. + +### 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 +- `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` + +**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 + +### Example 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 \ No newline at end of file From 01d6cc059dd711dd749a314f2ec6b4cf29673797 Mon Sep 17 00:00:00 2001 From: Ates Goral Date: Sun, 14 Sep 2025 00:31:16 -0400 Subject: [PATCH 2/4] Rename CLAUDE.md to AGENTS.md and restructure to follow agents.md standard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Adopt the new agents.md format for AI coding assistant guidance - Reorganize content into standard sections: project overview, dev setup, build commands, testing, code style, and architecture - Maintain all essential technical information while improving accessibility - Support the growing ecosystem of AI tools that recognize agents.md 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md => AGENTS.md | 50 ++++++++++++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 16 deletions(-) rename CLAUDE.md => AGENTS.md (67%) diff --git a/CLAUDE.md b/AGENTS.md similarity index 67% rename from CLAUDE.md rename to AGENTS.md index a7a1dea..3df95cf 100644 --- a/CLAUDE.md +++ b/AGENTS.md @@ -1,26 +1,39 @@ -# CLAUDE.md +# AGENTS.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +## 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. -## Development Commands +## Dev environment setup +- Ruby 3.2.0+ required +- Run `bundle install` to install dependencies +- Dependencies: `json_rpc_handler` ~> 0.1, `json-schema` >= 4.1 -### Core Commands +## Build and test commands - `bundle install` - Install dependencies - `rake test` - Run all tests - `rake rubocop` - Run linter - `rake` - Run tests and linting (default task) - -### Testing - `ruby -I lib -I test test/path/to/specific_test.rb` - Run single test file -- Test files are located in `test/` directory with `_test.rb` suffix - -### Gem Management - `gem build mcp.gemspec` - Build the gem -- Releases are triggered by updating version in `lib/mcp/version.rb` and merging to main -## Architecture Overview +## 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 -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. +## Architecture overview ### Core Components @@ -68,7 +81,12 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing - `json-schema` >= 4.1 - Schema validation - Ruby 3.2.0+ required -### Example 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 \ No newline at end of file +### 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") { ... }` \ No newline at end of file From de67fcfc08d6205b338ee318c9eaa10fbd389c96 Mon Sep 17 00:00:00 2001 From: Ates Goral Date: Sun, 14 Sep 2025 00:37:23 -0400 Subject: [PATCH 3/4] Consolidate Cursor-specific rules into AGENTS.md and remove tool-specific files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add release process section to AGENTS.md with changelog guidelines - Include Keep a Changelog format requirements and entry formatting rules - Remove .cursor/rules/release-changelogs.mdc to favor universal AGENTS.md format - Ensure all AI coding assistants have access to release documentation guidelines 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .cursor/rules/release-changelogs.mdc | 17 ----------------- AGENTS.md | 10 ++++++++++ 2 files changed, 10 insertions(+), 17 deletions(-) delete mode 100644 .cursor/rules/release-changelogs.mdc diff --git a/.cursor/rules/release-changelogs.mdc b/.cursor/rules/release-changelogs.mdc deleted file mode 100644 index d247090..0000000 --- a/.cursor/rules/release-changelogs.mdc +++ /dev/null @@ -1,17 +0,0 @@ ---- -description: Updating CHANGELOG.md before cutting a new release of the gem -globs: CHANGELOG.md -alwaysApply: false ---- - -- start by refreshing your knowledge on the Keep a Changelog convention by reading the format spec referenced at the top of CHANGELOG.md -- stick to Keep a Changelog -- entries should be terse and in a top-level flat list: do not nest -- follow this format for entries: - - Terse description of the change (#nnn) -- git tags are used to mark the commit that cut a new release of the gem -- the gem version is located in [version.rb](mdc:lib/mcp/version.rb) -- use the git history, especially merge commits from PRs to construct the changelog -- when necessary, look at the diff of files changed to determine the true nature of the change -- maintenance PRs that don't concern end users of the gem should not be listed in the changelog -- when checking PRs, see if there's an upstream remote, and if so, fetch PRs from upstream instead of origin diff --git a/AGENTS.md b/AGENTS.md index 3df95cf..580eb09 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,6 +33,16 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing - 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 +- 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 From 1249d63a9f828d67d7e2b82b64354275b2bc03c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ate=C5=9F=20G=C3=B6ral?= Date: Sun, 14 Sep 2025 10:19:46 -0400 Subject: [PATCH 4/4] Add blank lines after headings Co-authored-by: Koichi ITO --- AGENTS.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 580eb09..47cae9f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 @@ -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 @@ -48,6 +55,7 @@ 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` @@ -55,16 +63,19 @@ This is the official Ruby SDK for the Model Context Protocol (MCP), implementing - 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 @@ -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") { ... }` \ No newline at end of file