{"id":26889771,"url":"https://github.com/yjacquin/fast-mcp","last_synced_at":"2025-04-07T22:11:40.938Z","repository":{"id":282289809,"uuid":"945879706","full_name":"yjacquin/fast-mcp","owner":"yjacquin","description":"A Ruby Implementation of the Model Context Protocol","archived":false,"fork":false,"pushed_at":"2025-03-30T17:05:00.000Z","size":160,"stargazers_count":229,"open_issues_count":12,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-30T17:16:15.802Z","etag":null,"topics":["ai","llm","mcp","rack","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yjacquin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-10T09:17:33.000Z","updated_at":"2025-03-30T16:45:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"5c436784-c5e8-43fe-9599-cb047071527a","html_url":"https://github.com/yjacquin/fast-mcp","commit_stats":null,"previous_names":["yjacquin/fast-mcp","yjacquin/fast_mcp"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yjacquin%2Ffast-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yjacquin%2Ffast-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yjacquin%2Ffast-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yjacquin%2Ffast-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yjacquin","download_url":"https://codeload.github.com/yjacquin/fast-mcp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247737788,"owners_count":20987721,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","llm","mcp","rack","ruby"],"created_at":"2025-03-31T21:56:27.144Z","updated_at":"2025-04-07T22:11:40.928Z","avatar_url":"https://github.com/yjacquin.png","language":"Ruby","funding_links":[],"categories":["Open Source","Ruby","📚 Projects (1974 total)","🤖 AI/ML","MCP Frameworks and libraries","MCP Servers \u0026 Protocol"],"sub_categories":["MCP","MCP Servers","Ruby"],"readme":"# Fast MCP 🚀\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003eConnect AI models to your Ruby applications with ease\u003c/h3\u003e\n  \u003cp\u003eNo complex protocols, no integration headaches, no compatibility issues – just beautiful, expressive Ruby code.\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://badge.fury.io/rb/fast-mcp\"\u003e\u003cimg src=\"https://badge.fury.io/rb/fast-mcp.svg\" alt=\"Gem Version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/yjacquin/fast-mcp/workflows/CI/badge.svg\"\u003e\u003cimg src=\"https://github.com/yjacquin/fast-mcp/workflows/CI/badge.svg\" alt=\"CI Status\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /\u003e\u003c/a\u003e\n  \u003ca href=\"code_of_conduct.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg\" alt=\"Contributor Covenant\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## 🌟 Interface your Servers with LLMs in minutes !\n\nAI models are powerful, but they need to interact with your applications to be truly useful. Traditional approaches mean wrestling with:\n\n- 🔄 Complex communication protocols and custom JSON formats\n- 🔌 Integration challenges with different model providers\n- 🧩 Compatibility issues between your app and AI tools\n- 🧠 Managing the state between AI interactions and your data\n\nFast 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.\n\n## ✨ Features\n\n- 🛠️ **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).\n- 📚 **Resources API** - Share data between your app and AI models\n- 🔄 **Multiple Transports** - Choose from STDIO, HTTP, or SSE based on your needs\n- 🧩 **Framework Integration** - Works seamlessly with Rails, Sinatra or any Rack app.\n- 🔒 **Authentication Support** - Secure your AI-powered endpoints with ease\n- 🚀 **Real-time Updates** - Subscribe to changes for interactive applications\n\n\n## 💎 What Makes FastMCP Great\n```ruby\n# Define tools for AI models to use\nserver = FastMcp::Server.new(name: 'popular-users', version: '1.0.0')\n\n# Define a tool by inheriting from FastMcp::Tool\nclass CreateUserTool \u003c FastMcp::Tool\n  description \"Create a user\"\n  \n    # These arguments will generate the needed JSON to be presented to the MCP Client\n    # And they will be validated at run time.\n    # The validation is based off Dry-Schema, with the addition of the description.\n  arguments do\n    required(:first_name).filled(:string).description(\"First name of the user\")\n    optional(:age).filled(:integer).description(\"Age of the user\")\n    required(:address).hash do\n      optional(:street).filled(:string)\n      optional(:city).filled(:string)\n      optional(:zipcode).filled(:string)\n    end\n  end\n  \n  def call(first_name:, age: nil, address: {})\n    User.create!(first_name:, age:, address:)\n  end\nend\n\n# Register the tool with the server\nserver.register_tool(CreateUserTool)\n\n# Share data resources with AI models by inheriting from FastMcp::Resource\nclass PopularUsers \u003c FastMcp::Resource\n  uri \"file://popular_users.json\"\n  resource_name \"Popular Users\"\n  mime_type \"application/json\"\n  \n  def content\n    JSON.generate(User.popular.limit(5).as_json)\n  end\nend\n\n# Register the resource with the server\nserver.register_resource(PopularUsers)\n\n# Accessing the resource through the server\nserver.read_resource(PopularUsers.uri)\n\n# Notify the resource content has been updated to clients\nserver.notify_resource_updated(PopularUsers.uri)\n```\n\n### 🚂 Fast Ruby on Rails implementation\n```shell\nbundle add fast-mcp\nbin/rails generate fast_mcp:install\n```\n\nThis will add a configurable `fast_mcp.rb` initializer\n\n```ruby\nrequire 'fast_mcp'\n\nFastMcp.mount_in_rails(\n  Rails.application,\n  name: Rails.application.class.module_parent_name.underscore.dasherize,\n  version: '1.0.0',\n  path_prefix: '/mcp' # This is the default path prefix\n  # authenticate: true,       # Uncomment to enable authentication\n  # auth_token: 'your-token', # Required if authenticate: true\n) do |server|\n  Rails.application.config.after_initialize do\n    # FastMcp will automatically discover and register:\n    # - All classes that inherit from ApplicationTool (which uses ActionTool::Base)\n    # - All classes that inherit from ApplicationResource (which uses ActionResource::Base)\n    server.register_tools(*ApplicationTool.descendants)\n    server.register_resources(*ApplicationResource.descendants)\n    # alternatively, you can register tools and resources manually:\n    # server.register_tool(MyTool)\n    # server.register_resource(MyResource)\n  end\nend\n```\nThe install script will also:\n- add app/resources folder\n- add app/tools folder\n- add app/tools/sample_tool.rb\n- add app/resources/sample_resource.rb\n- add ApplicationTool to inherit from\n- add ApplicationResource to inherit from as well\n\n#### Rails-friendly class naming conventions\n\nFor Rails applications, FastMCP provides Rails-style class names to better fit with Rails conventions:\n\n- `ActionTool::Base` - An alias for `FastMcp::Tool`\n- `ActionResource::Base` - An alias for `FastMcp::Resource`\n\nThese are automatically set up in Rails applications. You can use either naming convention in your code:\n\n```ruby\n# Using Rails-style naming:\nclass MyTool \u003c ActionTool::Base\n  description \"My awesome tool\"\n  \n  arguments do\n    required(:input).filled(:string)\n  end\n  \n  def call(input:)\n    # Your implementation\n  end\nend\n\n# Using standard FastMcp naming:\nclass AnotherTool \u003c FastMcp::Tool\n  # Both styles work interchangeably in Rails apps\nend\n```\n\nWhen creating new tools or resources, the generators will use the Rails naming convention by default:\n\n```ruby\n# app/tools/application_tool.rb\nclass ApplicationTool \u003c ActionTool::Base\n  # Base methods for all tools\nend\n\n# app/resources/application_resource.rb\nclass ApplicationResource \u003c ActionResource::Base\n  # Base methods for all resources\nend\n```\n\n### Easy Sinatra setup\nI'll let you check out the dedicated [sinatra integration docs](./docs/sinatra_integration.md).\n\n## 🚀 Quick Start\n\n### Create a Server with Tools and Resources and STDIO transport\n\n```ruby\nrequire 'fast_mcp'\n\n# Create an MCP server\nserver = FastMcp::Server.new(name: 'my-ai-server', version: '1.0.0')\n\n# Define a tool by inheriting from FastMcp::Tool\nclass SummarizeTool \u003c FastMcp::Tool\n  description \"Summarize a given text\"\n  \n  arguments do\n    required(:text).filled(:string).description(\"Text to summarize\")\n    optional(:max_length).filled(:integer).description(\"Maximum length of summary\")\n  end\n  \n  def call(text:, max_length: 100)\n    # Your summarization logic here\n    text.split('.').first(3).join('.') + '...'\n  end\nend\n\n# Register the tool with the server\nserver.register_tool(SummarizeTool)\n\n# Create a resource by inheriting from FastMcp::Resource\nclass StatisticsResource \u003c FastMcp::Resource\n  uri \"data/statistics\"\n  resource_name \"Usage Statistics\"\n  description \"Current system statistics\"\n  mime_type \"application/json\"\n  \n  def content\n    JSON.generate({\n      users_online: 120,\n      queries_per_minute: 250,\n      popular_topics: [\"Ruby\", \"AI\", \"WebDev\"]\n    })\n  end\nend\n\n# Register the resource with the server\nserver.register_resource(StatisticsResource)\n\n# Start the server\nserver.start\n```\n\n## 🧪 Testing with the inspector\n\nMCP has developed a very [useful inspector](https://github.com/modelcontextprotocol/inspector).\nYou can use it to validate your implementation. I suggest you use the examples I provided with this project as an easy boilerplate.\nClone this project, then give it a go !\n\n```shell\nnpx @modelcontextprotocol/inspector examples/server_with_stdio_transport.rb\n```\nOr to test with an SSE transport using a rack middleware:\n```shell\nnpx @modelcontextprotocol/inspector examples/rack_middleware.rb\n```\n\nOr to test over SSE with an authenticated rack middleware:\n```shell\nnpx @modelcontextprotocol/inspector examples/authenticated_rack_middleware.rb\n```\n\nYou can test your custom implementation with the official MCP inspector by using:\n```shell\n# Test with a stdio transport:\nnpx @modelcontextprotocol/inspector path/to/your_ruby_file.rb\n\n# Test with an HTTP / SSE server. In the UI select SSE and input your address.\nnpx @modelcontextprotocol/inspector\n```\n\n#### Sinatra\n\n```ruby\n# app.rb\nrequire 'sinatra'\nrequire 'fast_mcp'\n\nuse FastMcp::RackMiddleware.new(name: 'my-ai-server', version: '1.0.0') do |server|\n  # Register tools and resources here\n  server.register_tool(SummarizeTool)\nend\n\nget '/' do\n  'Hello World!'\nend\n```\n\n### Integrating with Claude Desktop\n\nAdd your server to your Claude Desktop configuration at:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"my-great-server\": {\n      \"command\": \"ruby\",\n      \"args\": [\n        \"/Users/path/to/your/awesome/fast-mcp/server.rb\"\n      ]\n    }\n  }\n}\n```\n\n## How to add a MCP server to Claude, Cursor, or other MCP clients?\nPlease refer to [configuring_mcp_clients](docs/configuring_mcp_clients.md)\n\n## 📊 Supported Specifications\n\n| Feature | Status |\n|---------|--------|\n| ✅ **JSON-RPC 2.0** | Full implementation for communication |\n| ✅ **Tool Definition \u0026 Calling** | Define and call tools with rich argument types |\n| ✅ **Resource Management** | Create, read, update, and subscribe to resources |\n| ✅ **Transport Options** | STDIO, HTTP, and SSE for flexible integration |\n| ✅ **Framework Integration** | Rails, Sinatra, Hanami, and any Rack-compatible framework |\n| ✅ **Authentication** | Secure your AI endpoints with token authentication |\n| ✅ **Schema Support** | Full JSON Schema for tool arguments with validation |\n\n## 🗺️ Use Cases\n\n- 🤖 **AI-powered Applications**: Connect LLMs to your Ruby app's functionality\n- 📊 **Real-time Dashboards**: Build dashboards with live AI-generated insights\n- 🔗 **Microservice Communication**: Use MCP as a clean protocol between services\n- 📚 **Interactive Documentation**: Create AI-enhanced API documentation\n- 💬 **Chatbots and Assistants**: Build AI assistants with access to your app's data\n\n## 📖 Documentation\n\n- [🚀 Getting Started Guide](docs/getting_started.md)\n- [🧩 Integration Guide](docs/integration_guide.md)\n- [🛤️ Rails Integration](docs/rails_integration.md)\n- [🌐 Sinatra Integration](docs/sinatra_integration.md)\n- [📚 Resources](docs/resources.md)\n- [🛠️ Tools](docs/tools.md)\n\n## 💻 Examples\n\nCheck out the [examples directory](examples) for more detailed examples:\n\n- **🔨 Basic Examples**:\n  - [Simple Server](examples/server_with_stdio_transport.rb)\n  - [Tool Examples](examples/tool_examples.rb)\n\n- **🌐 Web Integration**:\n  - [Rack Middleware](examples/rack_middleware.rb)\n  - [Authenticated Endpoints](examples/authenticated_rack_middleware.rb)\n\n## 🧪 Requirements\n\n- Ruby 3.2+\n\n## 👥 Contributing\n\nWe welcome contributions to Fast MCP! Here's how you can help:\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\nPlease read our [Contributing Guide](CONTRIBUTING.md) for more details.\n\n## 📄 License\n\nThis project is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## 🙏 Acknowledgments\n\n- The [Model Context Protocol](https://github.com/modelcontextprotocol) team for creating the specification\n- The [Dry-Schema](https://github.com/dry-rb/dry-schema) team for the argument validation.\n- All contributors to this project\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyjacquin%2Ffast-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyjacquin%2Ffast-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyjacquin%2Ffast-mcp/lists"}