Rails Active MCP

Nota: Este é apenas um projeto pessoal e, embora funcione na maioria dos casos, ainda estou desenvolvendo-o e tentando ativamente torná-lo um pouco mais útil para meus usos.

Rails Active MCP

Uma gem Ruby que fornece acesso seguro ao console do Rails através do Model Context Protocol (MCP) para agentes de IA e ferramentas de desenvolvimento. Construída usando o SDK oficial MCP Ruby para tratamento profissional de protocolo e compatibilidade à prova de futuro.

Funciona com qualquer cliente compatível com MCP, incluindo Claude Desktop, Claude Code, VS Code (GitHub Copilot), Cursor, Windsurf, ChatGPT, Gemini CLI, Amazon Q Developer, JetBrains IDEs, Zed, Warp, Cline e muitos outros.

Início Rápido

Comece a usar em três etapas:

1. Instale a gem

Adicione ao Gemfile da sua aplicação Rails:

gem 'rails-active-mcp'

bundle install

2. Execute o instalador

rails generate rails_active_mcp:install

Isso cria um inicializador, scripts de servidor e solicita que você selecione quais clientes MCP você usa. Ele gerará automaticamente os arquivos de configuração corretos no nível do projeto (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) para que seu cliente MCP detecte o servidor quando você abrir o projeto.

3. Conecte seu cliente MCP

Se você selecionou seu cliente MCP durante a instalação, está pronto — basta abrir o projeto e o servidor será detectado automaticamente.

Para configuração manual ou clientes adicionais, o servidor usa transporte STDIO. Abaixo estão exemplos de configuração para ferramentas populares.

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

claude mcp add rails-active-mcp -- bundle exec rails-active-mcp-server

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"]
    }
  }
}

{
  "servers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

{
  "context_servers": {
    "rails-active-mcp": {
      "command": {
        "path": "bundle",
        "args": ["exec", "rails-active-mcp-server"],
        "env": {}
      }
    }
  }
}

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

Uma vez conectado, quatro ferramentas aparecerão automaticamente: console_execute, model_info, safe_query e dry_run.

Tente perguntar ao seu assistente de IA:

• "Mostre-me todos os usuários criados na última semana"
• "Qual é o valor médio do pedido?"
• "Verifique o esquema e as associações do modelo User"
• "Analise este código para segurança: User.delete_all"

Recursos

• 🔒 Execução Segura: Verificações avançadas de segurança previnem operações perigosas
• 🚀 SDK Oficial MCP: Construída com o SDK oficial MCP Ruby para tratamento robusto de protocolo
• 📊 Consultas Somente Leitura: Consultas seguras ao banco de dados com limitação automática de resultados
• 🔍 Análise de Código: Capacidades de dry-run para analisar código antes da execução
• 📝 Registro de Auditoria: Registro completo de execução para segurança e depuração
• ⚙️ Configurável: Configuração flexível para diferentes ambientes
• 🛡️ Pronto para Produção: Modos de segurança rigorosos para ambientes de produção
• ⚡ Implementação Profissional: Instrumentação, temporização e tratamento de erros integrados

Configuração

O instalador cria uma configuração padrão em config/initializers/rails_active_mcp.rb. Os padrões funcionam imediatamente, mas você pode personalizar o comportamento:

RailsActiveMcp.configure do |config|
  # Safety and execution
  config.safe_mode = true              # Block dangerous operations
  config.command_timeout = 30          # Seconds before timeout
  config.max_results = 100             # Limit query results
  config.allowed_models = []           # Empty = all models allowed
  config.custom_safety_patterns = []   # Additional patterns to block

  # Logging
  config.enable_logging = true
  config.log_level = :info             # :debug, :info, :warn, :error
  config.log_executions = false        # Log all code executions
  config.audit_file = nil              # Path to audit log file

  # Environment presets (call instead of setting individually)
  # config.production_mode!
  # config.development_mode!
  # config.test_mode!
end

Uso

Cliente MCP (Recomendado)

Uma vez conectado (veja Início Rápido), seu cliente MCP executa automaticamente o servidor para você. O servidor carrega sua aplicação Rails, inicializa modelos e fornece acesso seguro ao seu ambiente Rails via transporte STDIO.

Uso Direto

Você também pode usar a gem diretamente em Ruby:

# Execute code safely
result = RailsActiveMcp.execute("User.count")

# Check if code is safe
RailsActiveMcp.safe?("User.delete_all") # => false

Executando o Servidor Manualmente

Se você precisar executar o servidor diretamente (por exemplo, para depuração):

bundle exec rails-active-mcp-server

# With debug logging
RAILS_MCP_DEBUG=1 bundle exec rails-active-mcp-server

Tarefas Rake

A gem fornece várias tarefas rake para diagnóstico e teste:

# Show status and diagnostics
rails rails_active_mcp:status

# Validate configuration
rails rails_active_mcp:validate_config

# Test MCP tools are working
rails rails_active_mcp:test_tools

# Check if code is safe
rails rails_active_mcp:check_safety['User.delete_all']

# Execute code with safety checks
rails rails_active_mcp:execute['User.count']

# Print Claude Desktop configuration
rails rails_active_mcp:install_claude_config

# Run performance benchmarks
rails rails_active_mcp:benchmark

Ferramentas MCP Disponíveis

O servidor Rails Active MCP fornece quatro ferramentas poderosas que aparecem automaticamente em qualquer cliente MCP conectado:

1. console_execute

Execute código Ruby com verificações de segurança e proteção de tempo limite:

• Propósito: Executar comandos do console Rails com segurança
• Segurança: Detecção integrada de operações perigosas
• Tempo limite: Tempo limite de execução configurável
• Registro: Todas as execuções são registradas para auditoria

Exemplo de prompt:

"Execute User.where(active: true).count"

2. model_info

Obtenha informações detalhadas sobre modelos Rails:

• Informações de Esquema: Tipos de coluna, restrições, índices
• Associações: Relacionamentos has_many, belongs_to, has_one
• Validações: Todas as validações e regras do modelo
• Métodos: Métodos de instância e de classe disponíveis

Exemplo de prompt:

"Mostre-me a estrutura do modelo User"

3. safe_query

Execute consultas de banco de dados seguras e somente leitura:

• Somente Leitura: Apenas operações SELECT permitidas
• Execução Segura: Análise automática de consultas
• Limitação de Resultados: Previne grandes despejos de dados
• Contexto do Modelo: Funciona dentro das definições do seu modelo

Exemplo de prompt:

"Obtenha os 10 pedidos mais recentes" "Conte usuários ativos"

Você pode passar um hash opcional where para filtrar registros antes de invocar o método. Por exemplo, safe_query(model: "User", method: "count", where: { active: true }) executa User.where(active: true).count. O mesmo se aplica a sum, average, minimum, maximum, pluck e exists?.

4. dry_run

Analise código Ruby para segurança sem executar:

• Avaliação de Risco: Categoriza o código por nível de perigo
• Análise de Segurança: Identifica problemas potenciais
• Recomendações: Sugere alternativas mais seguras
• Zero Execução: Nunca executa o código real

Exemplo de prompt:

"Analise este código para segurança: User.delete_all"

Recursos de Segurança

Detecção Automática de Operações Perigosas

A gem detecta e bloqueia automaticamente:

• Exclusões em massa (delete_all, destroy_all)
• Comandos de sistema (system, exec, crases)
• Operações de arquivo (File.delete, FileUtils)
• Execução de SQL bruto
• Avaliação de código (eval, send)
• Manipulação de processos (exit, fork)

Níveis de Segurança

• Crítico: Nunca permitido (comandos de sistema, exclusão de arquivos)
• Alto: Bloqueado no modo seguro (exclusões em massa, eval)
• Médio: Registrado, mas permitido (SQL bruto, update_all)
• Baixo: Geralmente seguro (acesso ao ambiente, require)

Modo Somente Leitura

A gem pode detectar operações somente leitura e fornecer segurança adicional:

# These are considered safe read-only operations
User.find(1)
User.where(active: true).count
Post.includes(:comments).limit(10)

Arquitetura

Construído com o SDK Oficial MCP Ruby

Rails Active MCP usa o SDK oficial MCP Ruby (gem mcp) para:

• Tratamento Profissional de Protocolo: Implementação robusta de JSON-RPC 2.0
• Instrumentação Integrada: Temporização automática e relatório de erros
• À Prova de Futuro: Atualizações automáticas conforme a especificação MCP evolui
• Conformidade com Padrões: Compatibilidade total com o protocolo MCP

Implementação do Servidor

O servidor é implementado em lib/rails_active_mcp/sdk/server.rb e fornece:

• Transporte STDIO: Compatível com todos os principais clientes MCP
• Registro de Ferramentas: Descoberta automática de ferramentas disponíveis
• Tratamento de Erros: Relatório abrangente de erros e recuperação
• Integração Rails: Integração profunda com aplicações Rails

Arquitetura de Ferramentas

Cada ferramenta é implementada como uma classe separada em lib/rails_active_mcp/sdk/tools/:

• ConsoleExecuteTool: Execução segura de código
• ModelInfoTool: Introspecção de modelos
• SafeQueryTool: Acesso somente leitura ao banco de dados
• DryRunTool: Análise de segurança de código

Tratamento de Erros

A gem fornece tipos de erro específicos:

• RailsActiveMcp::SafetyError: O código falhou nas verificações de segurança
• RailsActiveMcp::TimeoutError: A execução expirou
• RailsActiveMcp::ExecutionError: Falha geral de execução

Todos os erros são reportados adequadamente através do protocolo MCP com mensagens detalhadas.

Desenvolvimento e Testes

# Run tests
bundle exec rspec

# Test MCP server protocol compliance
./bin/test-mcp-output

Contribuindo

1. Faça um fork
2. Crie sua branch de recurso (git checkout -b my-new-feature)
3. Faça commit das suas alterações (git commit -am 'Add some feature')
4. Envie para a branch (git push origin my-new-feature)
5. Crie um novo Pull Request

Licença

A gem está disponível como código aberto sob a Licença MIT.