https://github.com/yjacquin/fast-mcp
A Ruby Implementation of the Model Context Protocol
https://github.com/yjacquin/fast-mcp
ai llm mcp rack ruby
Last synced: about 1 year ago
JSON representation
A Ruby Implementation of the Model Context Protocol
- Host: GitHub
- URL: https://github.com/yjacquin/fast-mcp
- Owner: yjacquin
- License: mit
- Created: 2025-03-10T09:17:33.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-30T17:05:00.000Z (about 1 year ago)
- Last Synced: 2025-03-30T17:16:15.802Z (about 1 year ago)
- Topics: ai, llm, mcp, rack, ruby
- Language: Ruby
- Homepage:
- Size: 156 KB
- Stars: 229
- Watchers: 5
- Forks: 2
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ruby-ai - fast-mcp
- awesome-mcp-servers - **fast-mcp** - A Ruby Implementation of the Model Context Protocol `ruby` `ai` `llm` `mcp` `rack` `git clone https://github.com/yjacquin/fast-mcp` (🤖 AI/ML)
- awesome-mcp - yjacquin/fast-mcp - Fast MCP is a Ruby implementation of the Model Context Protocol that simplifies and secures AI model integration with Ruby applications through tools and resources APIs, multiple transport options, and seamless framework support. (MCP Frameworks and libraries / Ruby)
- awesome-openclaw-skills - yjacquin/fast-mcp
README
# Fast MCP 🚀
Connect AI models to your Ruby applications with ease
No complex protocols, no integration headaches, no compatibility issues – just beautiful, expressive Ruby code.
## 🌟 Interface your Servers with LLMs in minutes !
AI models are powerful, but they need to interact with your applications to be truly useful. Traditional approaches mean wrestling with:
- 🔄 Complex communication protocols and custom JSON formats
- 🔌 Integration challenges with different model providers
- 🧩 Compatibility issues between your app and AI tools
- 🧠 Managing the state between AI interactions and your data
Fast MCP solves all these problems by providing a clean, Ruby-focused implementation of the [Model Context Protocol](https://github.com/modelcontextprotocol), making AI integration a joy, not a chore.
## ✨ Features
- 🛠️ **Tools API** - Let AI models call your Ruby functions securely, with in-depth argument validation through [Dry-Schema](https://github.com/dry-rb/dry-schema).
- 📚 **Resources API** - Share data between your app and AI models
- 🔄 **Multiple Transports** - Choose from STDIO, HTTP, or SSE based on your needs
- 🧩 **Framework Integration** - Works seamlessly with Rails, Sinatra or any Rack app.
- 🔒 **Authentication Support** - Secure your AI-powered endpoints with ease
- 🚀 **Real-time Updates** - Subscribe to changes for interactive applications
## 💎 What Makes FastMCP Great
```ruby
# Define tools for AI models to use
server = FastMcp::Server.new(name: 'popular-users', version: '1.0.0')
# Define a tool by inheriting from FastMcp::Tool
class CreateUserTool < FastMcp::Tool
description "Create a user"
# These arguments will generate the needed JSON to be presented to the MCP Client
# And they will be validated at run time.
# The validation is based off Dry-Schema, with the addition of the description.
arguments do
required(:first_name).filled(:string).description("First name of the user")
optional(:age).filled(:integer).description("Age of the user")
required(:address).hash do
optional(:street).filled(:string)
optional(:city).filled(:string)
optional(:zipcode).filled(:string)
end
end
def call(first_name:, age: nil, address: {})
User.create!(first_name:, age:, address:)
end
end
# Register the tool with the server
server.register_tool(CreateUserTool)
# Share data resources with AI models by inheriting from FastMcp::Resource
class PopularUsers < FastMcp::Resource
uri "file://popular_users.json"
resource_name "Popular Users"
mime_type "application/json"
def content
JSON.generate(User.popular.limit(5).as_json)
end
end
# Register the resource with the server
server.register_resource(PopularUsers)
# Accessing the resource through the server
server.read_resource(PopularUsers.uri)
# Notify the resource content has been updated to clients
server.notify_resource_updated(PopularUsers.uri)
```
### 🚂 Fast Ruby on Rails implementation
```shell
bundle add fast-mcp
bin/rails generate fast_mcp:install
```
This will add a configurable `fast_mcp.rb` initializer
```ruby
require 'fast_mcp'
FastMcp.mount_in_rails(
Rails.application,
name: Rails.application.class.module_parent_name.underscore.dasherize,
version: '1.0.0',
path_prefix: '/mcp' # This is the default path prefix
# authenticate: true, # Uncomment to enable authentication
# auth_token: 'your-token', # Required if authenticate: true
) do |server|
Rails.application.config.after_initialize do
# FastMcp will automatically discover and register:
# - All classes that inherit from ApplicationTool (which uses ActionTool::Base)
# - All classes that inherit from ApplicationResource (which uses ActionResource::Base)
server.register_tools(*ApplicationTool.descendants)
server.register_resources(*ApplicationResource.descendants)
# alternatively, you can register tools and resources manually:
# server.register_tool(MyTool)
# server.register_resource(MyResource)
end
end
```
The install script will also:
- add app/resources folder
- add app/tools folder
- add app/tools/sample_tool.rb
- add app/resources/sample_resource.rb
- add ApplicationTool to inherit from
- add ApplicationResource to inherit from as well
#### Rails-friendly class naming conventions
For Rails applications, FastMCP provides Rails-style class names to better fit with Rails conventions:
- `ActionTool::Base` - An alias for `FastMcp::Tool`
- `ActionResource::Base` - An alias for `FastMcp::Resource`
These are automatically set up in Rails applications. You can use either naming convention in your code:
```ruby
# Using Rails-style naming:
class MyTool < ActionTool::Base
description "My awesome tool"
arguments do
required(:input).filled(:string)
end
def call(input:)
# Your implementation
end
end
# Using standard FastMcp naming:
class AnotherTool < FastMcp::Tool
# Both styles work interchangeably in Rails apps
end
```
When creating new tools or resources, the generators will use the Rails naming convention by default:
```ruby
# app/tools/application_tool.rb
class ApplicationTool < ActionTool::Base
# Base methods for all tools
end
# app/resources/application_resource.rb
class ApplicationResource < ActionResource::Base
# Base methods for all resources
end
```
### Easy Sinatra setup
I'll let you check out the dedicated [sinatra integration docs](./docs/sinatra_integration.md).
## 🚀 Quick Start
### Create a Server with Tools and Resources and STDIO transport
```ruby
require 'fast_mcp'
# Create an MCP server
server = FastMcp::Server.new(name: 'my-ai-server', version: '1.0.0')
# Define a tool by inheriting from FastMcp::Tool
class SummarizeTool < FastMcp::Tool
description "Summarize a given text"
arguments do
required(:text).filled(:string).description("Text to summarize")
optional(:max_length).filled(:integer).description("Maximum length of summary")
end
def call(text:, max_length: 100)
# Your summarization logic here
text.split('.').first(3).join('.') + '...'
end
end
# Register the tool with the server
server.register_tool(SummarizeTool)
# Create a resource by inheriting from FastMcp::Resource
class StatisticsResource < FastMcp::Resource
uri "data/statistics"
resource_name "Usage Statistics"
description "Current system statistics"
mime_type "application/json"
def content
JSON.generate({
users_online: 120,
queries_per_minute: 250,
popular_topics: ["Ruby", "AI", "WebDev"]
})
end
end
# Register the resource with the server
server.register_resource(StatisticsResource)
# Start the server
server.start
```
## 🧪 Testing with the inspector
MCP has developed a very [useful inspector](https://github.com/modelcontextprotocol/inspector).
You can use it to validate your implementation. I suggest you use the examples I provided with this project as an easy boilerplate.
Clone this project, then give it a go !
```shell
npx @modelcontextprotocol/inspector examples/server_with_stdio_transport.rb
```
Or to test with an SSE transport using a rack middleware:
```shell
npx @modelcontextprotocol/inspector examples/rack_middleware.rb
```
Or to test over SSE with an authenticated rack middleware:
```shell
npx @modelcontextprotocol/inspector examples/authenticated_rack_middleware.rb
```
You can test your custom implementation with the official MCP inspector by using:
```shell
# Test with a stdio transport:
npx @modelcontextprotocol/inspector path/to/your_ruby_file.rb
# Test with an HTTP / SSE server. In the UI select SSE and input your address.
npx @modelcontextprotocol/inspector
```
#### Sinatra
```ruby
# app.rb
require 'sinatra'
require 'fast_mcp'
use FastMcp::RackMiddleware.new(name: 'my-ai-server', version: '1.0.0') do |server|
# Register tools and resources here
server.register_tool(SummarizeTool)
end
get '/' do
'Hello World!'
end
```
### Integrating with Claude Desktop
Add your server to your Claude Desktop configuration at:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"my-great-server": {
"command": "ruby",
"args": [
"/Users/path/to/your/awesome/fast-mcp/server.rb"
]
}
}
}
```
## How to add a MCP server to Claude, Cursor, or other MCP clients?
Please refer to [configuring_mcp_clients](docs/configuring_mcp_clients.md)
## 📊 Supported Specifications
| Feature | Status |
|---------|--------|
| ✅ **JSON-RPC 2.0** | Full implementation for communication |
| ✅ **Tool Definition & Calling** | Define and call tools with rich argument types |
| ✅ **Resource Management** | Create, read, update, and subscribe to resources |
| ✅ **Transport Options** | STDIO, HTTP, and SSE for flexible integration |
| ✅ **Framework Integration** | Rails, Sinatra, Hanami, and any Rack-compatible framework |
| ✅ **Authentication** | Secure your AI endpoints with token authentication |
| ✅ **Schema Support** | Full JSON Schema for tool arguments with validation |
## 🗺️ Use Cases
- 🤖 **AI-powered Applications**: Connect LLMs to your Ruby app's functionality
- 📊 **Real-time Dashboards**: Build dashboards with live AI-generated insights
- 🔗 **Microservice Communication**: Use MCP as a clean protocol between services
- 📚 **Interactive Documentation**: Create AI-enhanced API documentation
- 💬 **Chatbots and Assistants**: Build AI assistants with access to your app's data
## 📖 Documentation
- [🚀 Getting Started Guide](docs/getting_started.md)
- [🧩 Integration Guide](docs/integration_guide.md)
- [🛤️ Rails Integration](docs/rails_integration.md)
- [🌐 Sinatra Integration](docs/sinatra_integration.md)
- [📚 Resources](docs/resources.md)
- [🛠️ Tools](docs/tools.md)
## 💻 Examples
Check out the [examples directory](examples) for more detailed examples:
- **🔨 Basic Examples**:
- [Simple Server](examples/server_with_stdio_transport.rb)
- [Tool Examples](examples/tool_examples.rb)
- **🌐 Web Integration**:
- [Rack Middleware](examples/rack_middleware.rb)
- [Authenticated Endpoints](examples/authenticated_rack_middleware.rb)
## 🧪 Requirements
- Ruby 3.2+
## 👥 Contributing
We welcome contributions to Fast MCP! Here's how you can help:
1. Fork the repository
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
Please read our [Contributing Guide](CONTRIBUTING.md) for more details.
## 📄 License
This project is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## 🙏 Acknowledgments
- The [Model Context Protocol](https://github.com/modelcontextprotocol) team for creating the specification
- The [Dry-Schema](https://github.com/dry-rb/dry-schema) team for the argument validation.
- All contributors to this project