mcp 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b72cdaffe97298a6d6d8b88973b4ea2236909dfb9bf46cc6694ae9331a102a5a
-  data.tar.gz: dbab122901fa44329aa03d355fcf35df70087ab88a3f919100740d46261b1319
+  metadata.gz: 451bdb587fa89621924916d7cc137cf44a3a2293cf7803c3c6af1d97fb57332a
+  data.tar.gz: 3175f6a5d60426d5441b99b2bbf6d50b90d31daa9b713796029547f5efc6ab6a
 SHA512:
-  metadata.gz: 4f3200c4d2520fa6b1c720b7e1547be5cbaea15d2ba76f8491dedd5ef840f8fae59017cd3ea965796c7cda0ab353e78579291e3f3559250412ae9f1f901eb0b7
-  data.tar.gz: 91c4dff59524cd390a2cfc92921862cb1dc9446b483b699d7ac722a40438716c56c494b34d84d211aeafd4fc152fcfaf9ae10c354c1c3c104c27ca0a0f4f83a1
+  metadata.gz: 4b9e312c047ebc31d0826ec2520e14fef34fd0a23f42d9bf849f4a64b8cdb924341aa8a431aab497824849da476de5b8b2d55ad3b3996b9871e04b9022161aa3
+  data.tar.gz: 772762d9cf650278dd0756867a995e57e13366e1a4a2a5b306433d8d9246e8bed2aadb00e057d4f31a521603dab6f8fadcbcdfc9650806c79d9881e2e1913acb

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'

data/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
           - { ruby: head, allowed-failure: true }
     name: Test Ruby ${{ matrix.entry.ruby }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.entry.ruby }}
@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     name: RuboCop
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 3.2 # Specify the oldest supported Ruby version.

data/.github/workflows/release.yml

@@ -16,7 +16,7 @@ jobs:
       id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
       contents: write # IMPORTANT: this permission is required for `rake release` to push the release tag
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:

data/.rubocop.yml

@@ -7,3 +7,6 @@ plugins:
 
 Gemspec/DevelopmentDependencies:
   Enabled: true
+
+Minitest/LiteralAsActualArgument:
+  Enabled: true

data/AGENTS.md

@@ -0,0 +1,119 @@
+# 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
+- `rake` - Run tests and linting (default task)
+- `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
+
+## 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
+- 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
+- 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
+
+### 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") { ... }`

data/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2025-10-15
+
+### Added
+
+- Client resources support with `resources/list` and `resources/read` methods (#160)
+- `_meta` field support for Tool schema (#124)
+- `_meta` field support for Prompt
+- `title` field support for prompt arguments
+- `call_tool_raw` method to client for accessing full tool responses (#149)
+- Structured content support in tool responses (#147)
+- AGENTS.md development guidance documentation (#134)
+- Dependabot configuration for automated dependency updates (#138)
+
+### Changed
+
+- Set default `content` to empty array instead of `nil` (#150)
+- Improved prompt spec compliance (#153)
+- Allow output schema to be array of objects (#144)
+- Return 202 response code for accepted JSON-RPC notifications (#114)
+- Added validation to `MCP::Configuration` setters (#145)
+- Updated metaschema URI format for cross-OS compatibility
+
+### Fixed
+
+- Client tools functionality and test coverage (#166)
+- Client resources test for empty responses (#162)
+- Documentation typos and incorrect examples (#157, #146)
+- Removed redundant transport requires (#154)
+- Cleaned up unused block parameters and magic comments
+
+## [0.3.0] - 2025-09-14
+
+### Added
+
+- Tool output schema support with comprehensive validation (#122)
+- HTTP client transport layer for MCP clients (#28)
+- Tool annotations validation for protocol compatibility (#122)
+- Server instructions support (#87)
+- Title support in server info (#119)
+- Default values for tool annotation hints (#118)
+- Notifications/initialized method implementation (#84)
+
+### Changed
+
+- Make default protocol version the latest specification version (#83)
+- Protocol version validation to ensure valid values (#80)
+- Improved tool handling for tools with no arguments (#85, #86)
+- Better error handling and response API (#109)
+
+### Fixed
+
+- JSON-RPC notification format in Streamable HTTP transport (#91)
+- Errors when title is not specified (#126)
+- Tools with missing arguments handling (#86)
+- Namespacing issues in README examples (#89)
+
 ## [0.2.0] - 2025-07-15
 
 ### Added

data/Gemfile

@@ -6,10 +6,6 @@ source "https://rubygems.org"
 gemspec
 
 # Specify development dependencies below
-gem "minitest", "~> 5.1", require: false
-gem "minitest-reporters"
-gem "mocha"
-
 gem "rubocop-minitest", require: false
 gem "rubocop-rake", require: false
 gem "rubocop-shopify", require: false
@@ -22,3 +18,10 @@ gem "activesupport"
 gem "debug"
 gem "rake", "~> 13.0"
 gem "sorbet-static-and-runtime"
+
+group :test do
+  gem "faraday", ">= 2.0"
+  gem "minitest", "~> 5.1", require: false
+  gem "mocha"
+  gem "webmock"
+end