Fast MCP

Uma implementação em Ruby do servidor Model Context Protocol (MCP) para integrar modelos de IA em aplicações Ruby.

Documentação

Fast MCP 🚀

Conecte modelos de IA às suas aplicações Ruby com facilidade

Sem protocolos complexos, sem dores de cabeça com integração, sem problemas de compatibilidade – apenas código Ruby bonito e expressivo.

🌟 Interface seus Servidores com LLMs em minutos

Os modelos de IA são poderosos, mas precisam interagir com suas aplicações para serem realmente úteis. Abordagens tradicionais significam lidar com:

🔄 Protocolos de comunicação complexos e formatos JSON personalizados
🔌 Desafios de integração com diferentes provedores de modelos
🧩 Problemas de compatibilidade entre sua aplicação e ferramentas de IA
🧠 Gerenciamento do estado entre interações de IA e seus dados

O Fast MCP resolve todos esses problemas fornecendo uma implementação limpa e focada em Ruby do Model Context Protocol, tornando a integração com IA uma alegria, não uma tarefa árdua.

✨ Recursos

🛠️ API de Ferramentas - Deixe os modelos de IA chamarem suas funções Ruby com segurança, com validação aprofundada de argumentos através do Dry-Schema.
📚 API de Recursos - Compartilhe dados entre sua aplicação e modelos de IA
🔄 Múltiplos Transportes - Escolha entre STDIO, HTTP ou SSE conforme suas necessidades
🧩 Integração com Frameworks - Funciona perfeitamente com Rails, Sinatra ou qualquer aplicação Rack.
🔒 Suporte a Autenticação - Proteja seus endpoints alimentados por IA com facilidade
🚀 Atualizações em Tempo Real - Assine mudanças para aplicações interativas
🎯 Filtragem Dinâmica - Controle o acesso a ferramentas/recursos com base no contexto da solicitação (permissões, versões de API, etc.)

💎 O Que Torna o FastMCP Excelente

# 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).description("The shipping address").hash do
      required(:street).filled(:string).description("Street address")
      optional(:city).filled(:string).description("City name")
      optional(:zipcode).maybe(:string).description("Postal code")
    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 "myapp:///users/popular"
  resource_name "Popular Users"
  mime_type "application/json"

  def content
    JSON.generate(User.popular.limit(5).as_json)
  end
end

class User < FastMcp::Resource
  uri "myapp:///users/{id}" # This is a resource template
  resource_name "user"
  mime_type "application/json"

  def content
    id = params[:id] # params are computed from the uri pattern

    JSON.generate(User.find(id).as_json)
  end
end

# Register the resource with the server
server.register_resources(PopularUsers, User)

# 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.variabilized_uri)

# Notifiy the content of a resource from a template has been updated to clients
server.notify_resource_updated(User.variabilized_uri(id: 1))

🎯 Filtragem Dinâmica de Ferramentas

Controle quais ferramentas e recursos estão disponíveis com base no contexto da solicitação:

# Tag your tools for easy filtering
class AdminTool < FastMcp::Tool
  tags :admin, :dangerous
  description "Perform admin operations"

  def call
    # Admin only functionality
  end
end

# Filter tools based on user permissions
server.filter_tools do |request, tools|
  user_role = request.params['role']

  case user_role
  when 'admin'
    tools # Admins see all tools
  when 'user'
    tools.reject { |t| t.tags.include?(:admin) }
  else
    tools.select { |t| t.tags.include?(:public) }
  end
end

🚂 Implementação Rápida para Ruby on Rails

bundle add fast-mcp
bin/rails generate fast_mcp:install

Isso adicionará um inicializador fast_mcp.rb configurável

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
  messages_route: 'messages', # This is the default route for the messages endpoint
  sse_route: 'sse', # This is the default route for the SSE endpoint
  # Add allowed origins below, it defaults to Rails.application.config.hosts
  # allowed_origins: ['localhost', '127.0.0.1', 'example.com', /.*\.example\.com/],
  # localhost_only: true, # Set to false to allow connections from other hosts
  # whitelist specific ips to if you want to run on localhost and allow connections from other IPs
  # allowed_ips: ['127.0.0.1', '::1']
  # 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

O script de instalação também irá:

adicionar a pasta app/resources
adicionar a pasta app/tools
adicionar app/tools/sample_tool.rb
adicionar app/resources/sample_resource.rb
adicionar ApplicationTool para herança
adicionar ApplicationResource para herança também

Convenções de nomenclatura de classes amigáveis ao Rails

Para aplicações Rails, o FastMCP fornece nomes de classes no estilo Rails para melhor se adequar às convenções do Rails:

ActionTool::Base - Um alias para FastMcp::Tool
ActionResource::Base - Um alias para FastMcp::Resource

Eles são configurados automaticamente em aplicações Rails. Você pode usar qualquer uma das convenções de nomenclatura em seu código:

# 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

Ao criar novas ferramentas ou recursos, os geradores usarão a convenção de nomenclatura do Rails por padrão:

# 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

Configuração fácil com Sinatra

Vou deixar você conferir a documentação dedicada de integração com sinatra.

🚀 Início Rápido

Crie um Servidor com Ferramentas e Recursos e transporte STDIO

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

🧪 Testando com o inspetor

O MCP desenvolveu um inspetor muito útil. Você pode usá-lo para validar sua implementação. Sugiro que use os exemplos que forneci com este projeto como um modelo fácil. Clone este projeto e experimente!

npx @modelcontextprotocol/inspector examples/server_with_stdio_transport.rb

Ou para testar com um transporte SSE usando um middleware rack:

npx @modelcontextprotocol/inspector examples/rack_middleware.rb

Ou para testar via SSE com um middleware rack autenticado:

npx @modelcontextprotocol/inspector examples/authenticated_rack_middleware.rb

Você pode testar sua implementação personalizada com o inspetor oficial do MCP usando:

# 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

# 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

Integrando com o Claude Desktop

Adicione seu servidor à configuração do Claude Desktop em:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-great-server": {
      "command": "ruby",
      "args": ["/Users/path/to/your/awesome/fast-mcp/server.rb"]
    }
  }
}

Como adicionar um servidor MCP ao Claude, Cursor ou outros clientes MCP?

Consulte configuring_mcp_clients

📊 Especificações Suportadas

Recurso	Status
✅ JSON-RPC 2.0	Implementação completa para comunicação
✅ Definição e Chamada de Ferramentas	Defina e chame ferramentas com tipos de argumentos ricos
✅ Gerenciamento de Recursos e Modelos de Recursos	Crie, leia, atualize e assine recursos
✅ Opções de Transporte	STDIO, HTTP e SSE para integração flexível
✅ Integração com Frameworks	Rails, Sinatra, Hanami e qualquer framework compatível com Rack
✅ Autenticação	Proteja seus endpoints de IA com autenticação por token
✅ Suporte a Schema	JSON Schema completo para argumentos de ferramentas com validação

🗺️ Casos de Uso

🤖 Aplicações Alimentadas por IA: Conecte LLMs à funcionalidade da sua aplicação Ruby
📊 Dashboards em Tempo Real: Crie dashboards com insights gerados por IA ao vivo
🔗 Comunicação entre Microsserviços: Use MCP como um protocolo limpo entre serviços
📚 Documentação Interativa: Crie documentação de API aprimorada por IA
💬 Chatbots e Assistentes: Crie assistentes de IA com acesso aos dados da sua aplicação

🔒 Recursos de Segurança

O Fast MCP inclui recursos de segurança integrados para proteger suas aplicações:

Proteção contra Rebinding de DNS

O transporte HTTP/SSE valida o cabeçalho Origin em todas as conexões recebidas para prevenir ataques de rebinding de DNS, que poderiam permitir que sites maliciosos interajam com servidores MCP locais.

# Configure allowed origins (defaults to ['localhost', '127.0.0.1'])
FastMcp.rack_middleware(app,
  allowed_origins: ['localhost', '127.0.0.1', 'your-domain.com', /.*\.your-domain\.com/],
  localhost_only: false,
  allowed_ips: ['192.168.1.1', '10.0.0.1'],
  # other options...
)

Autenticação

O Fast MCP suporta autenticação baseada em token para todas as conexões:

# Enable authentication
FastMcp.authenticated_rack_middleware(app,
  auth_token: 'your-secret-token',
  # other options...
)

📖 Documentação

💻 Exemplos

Confira o diretório de exemplos para exemplos mais detalhados:

🔨 Exemplos Básicos:
- Servidor Simples
- Exemplos de Ferramentas
🌐 Integração Web:
- Middleware Rack
- Endpoints Autenticados

🧪 Requisitos

Ruby 3.2+

👥 Contribuindo

Aceitamos contribuições para o Fast MCP! Veja como você pode ajudar:

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b my-new-feature)
Faça commit das suas alterações (git commit -am 'Add some feature')
Envie para a branch (git push origin my-new-feature)
Crie um novo Pull Request

Leia nosso Guia de Contribuição para mais detalhes.

📄 Licença

Este projeto está disponível como código aberto sob os termos da Licença MIT.

🙏 Agradecimentos

A equipe do Model Context Protocol por criar a especificação
A equipe do Dry-Schema pela validação de argumentos.
Todos os contribuidores deste projeto