MCP on Ruby

A Ruby implementation of the Model Context Protocol (MCP) specification, enabling standardized AI application interactions with external tools and data sources.

Documentation | Examples | Contributing

📋 Table of Contents

• Features
• Installation
• Quick Start
  • Server Setup
  • Client Setup
• Core Concepts
• Security
• Advanced Usage
• Development
• Contributing
• License

✨ Features

• Full MCP Protocol Support - Implements the latest MCP specification
• Multiple Transport Options - HTTP and STDIO transports
• Comprehensive Capabilities
  • 🛠️ Tools (model-controlled actions)
  • 📚 Resources (application-controlled context)
  • 💬 Prompts (user-controlled interactions)
  • 📁 Roots (filesystem integration)
• Security First
  • OAuth 2.1 Authentication
  • JWT Implementation
  • Scope-based Authorization
• Real-time Communication
  • Bidirectional messaging
  • Streaming support
  • JSON-RPC 2.0 standard

🚀 Installation

Add to your Gemfile:

gem 'mcp_on_ruby'

Then run:

bundle install

Or install directly:

gem install mcp_on_ruby

🏁 Quick Start

Server Setup

Create a basic MCP server with tools:

require 'mcp_on_ruby'

server = MCP::Server.new do |s|
  # Define a tool
  s.tool "weather.get_forecast" do |params|
    location = params[:location]
    { forecast: "Sunny", temperature: 72, location: location }
  end
  
  # Add a resource
  s.resource "user.profile" do
    { name: "John", email: "john@example.com" }
  end
end

server.start

Client Setup

Connect to an MCP server:

require 'mcp_on_ruby'

client = MCP::Client.new(url: "http://localhost:3000")
client.connect

# List available tools
tools = client.tools.list

# Call a tool
result = client.tools.call("weather.get_forecast", 
  { location: "San Francisco" }
)

🎯 Core Concepts

1. Tools

Model-controlled functions with JSON Schema-defined parameters:

server.tools.define('example') do
  parameter :name, :string
  
  execute do |params|
    "Hello, #{params[:name]}!"
  end
end

2. Resources

Application-controlled data sources:

server.resource "user.profile" do
  { name: "John", email: "john@example.com" }
end

3. Authentication

Secure your server with OAuth 2.1:

oauth_provider = MCP::Server::Auth::OAuth.new(
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  token_expiry: 3600,
  jwt_secret: 'your-jwt-secret',
  issuer: 'your-server'
)

🔒 Security

OAuth 2.1 Implementation

• Token-based authentication
• JWT validation
• Automatic token refresh
• Scope-based authorization

Permission Management

• Method-level permissions
• Scope requirements
• Middleware architecture

📚 Advanced Usage

Check out our examples directory for complete implementations:

• Simple Server
• Authentication
• Rails Integration
• Streaming

For more advanced topics, visit our Wiki.

💻 Development

# Clone the repository
git clone https://github.com/nagstler/mcp_on_ruby.git

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Start console
bundle exec bin/console

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ for the Ruby community