Rails MCP Server

Um servidor MCP para projetos Rails, permitindo que LLMs interajam com sua aplicação.

Documentação

Rails MCP Server

Uma implementação em Ruby de um servidor Model Context Protocol (MCP) para projetos Rails. Este servidor permite que LLMs (Large Language Models) interajam com projetos Rails através do Model Context Protocol, fornecendo capacidades para análise de código, exploração e assistência de desenvolvimento.

O que é MCP?

O Model Context Protocol (MCP) é uma forma padronizada para modelos de IA interagirem com seu ambiente. Ele define um método estruturado para modelos solicitarem e usarem ferramentas, acessarem recursos e manterem contexto durante interações.

Este Rails MCP Server implementa a especificação MCP para dar acesso a modelos de IA a projetos Rails para análise de código, exploração e assistência.

Recursos

Gerencie múltiplos projetos Rails
Navegue por arquivos e estruturas de projetos
Visualize rotas Rails com opções de filtragem
Inspecione informações de modelos e relacionamentos (com análise estática Prism)
Obtenha informações do esquema do banco de dados
Analise relações controlador-visão
Analise configurações de ambiente
Acesse documentação abrangente de Rails, Turbo, Stimulus e Kamal
Arquitetura eficiente em contexto com descoberta progressiva de ferramentas
Integração perfeita com clientes LLM

Instalação

Instale a gem:

gem install rails-mcp-server

Após a instalação, os seguintes executáveis estarão disponíveis no seu PATH:

rails-mcp-server - O próprio servidor MCP
rails-mcp-config - Ferramenta de configuração interativa (recomendado)
rails-mcp-setup-claude - Script de configuração legado do Claude Desktop
rails-mcp-server-download-resources - Script legado de download de recursos

Configuração

Usando a Ferramenta de Configuração (Recomendado)

A maneira mais fácil de configurar o Rails MCP Server é usando a ferramenta de configuração interativa:

rails-mcp-config

Isso fornece uma TUI (Interface de Usuário de Terminal) amigável para:

Gerenciando Projetos: Adicione, edite, remova e valide projetos Rails
Baixando Guias: Baixe documentação de Rails, Turbo, Stimulus e Kamal
Importando Guias Personalizadas: Adicione sua própria documentação markdown
Integração com Claude Desktop: Configure automaticamente o Claude Desktop

A ferramenta usa Gum para uma experiência aprimorada se instalado, mas funciona com um fallback básico de terminal.

# Install Gum for best experience (optional)
brew install gum        # macOS
sudo apt install gum    # Debian/Ubuntu
yay -S gum              # Arch Linux

Configuração Manual

O Rails MCP Server segue a Especificação de Diretório Base XDG para arquivos de configuração:

No macOS: $XDG_CONFIG_HOME/rails-mcp ou ~/.config/rails-mcp se XDG_CONFIG_HOME não estiver definido
No Windows: %APPDATA%\rails-mcp

O servidor criará automaticamente esses diretórios e um arquivo projects.yml vazio na primeira execução.

Para configurar seus projetos manualmente:

Edite o arquivo projects.yml no seu diretório de configuração para incluir seus projetos Rails:

store: "~/projects/store"
blog: "~/projects/rails-blog"
ecommerce: "/full/path/to/ecommerce-app"

Cada chave no arquivo YAML é um nome de projeto (que será usado com a ferramenta switch_project), e cada valor é o caminho para o diretório do projeto.

Uso

Iniciando o servidor

O Rails MCP Server pode rodar em dois modos:

Modo STDIO (padrão): Comunica-se via entrada/saída padrão para integração direta com clientes como Claude Desktop.
Modo HTTP: Roda como um servidor HTTP com endpoints JSON-RPC e Server-Sent Events (SSE).

# Start in default STDIO mode
rails-mcp-server

# Start in HTTP mode on the default port (6029)
rails-mcp-server --mode http

# Start in HTTP mode on a custom port
rails-mcp-server --mode http -p 8080

# Start in HTTP mode binding to all interfaces (for local network access)
rails-mcp-server --mode http --bind-all

Ao rodar em modo HTTP, o servidor fornece dois endpoints:

Endpoint JSON-RPC: http://localhost:<port>/mcp/messages
Endpoint SSE: http://localhost:<port>/mcp/sse

Acesso à Rede (Modo HTTP)

Por padrão, o servidor HTTP só vincula ao localhost por segurança. Se você precisar acessar o servidor de outras máquinas na sua rede local (por exemplo, para testes com múltiplos dispositivos), você pode usar a flag --bind-all:

# Allow access from any machine on your local network
rails-mcp-server --mode http --bind-all

# With a custom port
rails-mcp-server --mode http --bind-all -p 8080

Ao usar --bind-all:

O servidor vincula a 0.0.0.0 em vez de localhost
O acesso é permitido a partir de faixas de IP de rede local (192.168.x.x, 10.x.x.x)
O servidor aceita conexões de nomes de domínio .local (por exemplo, my-computer.local)
Recursos de segurança permanecem ativos para prevenir acesso não autorizado

Nota de Segurança: Use --bind-all apenas em redes confiáveis. O servidor inclui recursos de segurança integrados para validar origens e endereços IP, mas expor qualquer serviço à sua rede aumenta a superfície de ataque.

Opções de Registro

O servidor registra em um arquivo no diretório ./log por padrão. Você pode personalizar o registro com estas opções:

# Set the log level (debug, info, error)
rails-mcp-server --log-level debug

Integração com Claude Desktop

O Rails MCP Server pode ser usado com o Claude Desktop. Existem múltiplas opções para configurar isso:

Opção 1: Use a ferramenta de configuração (recomendado)

Execute a ferramenta de configuração interativa e selecione "Integração com Claude Desktop":

rails-mcp-config

A ferramenta irá:

Detectar sua configuração atual do Claude Desktop
Permitir que você escolha entre modo STDIO ou HTTP
Encontrar automaticamente os caminhos corretos de Ruby e servidor
Criar um backup antes de fazer alterações
Atualizar a configuração do Claude Desktop

Opção 2: Use o script de configuração (legado)

Execute o script de configuração que configurará automaticamente o Claude Desktop:

rails-mcp-setup-claude

O script irá:

Criar o diretório de configuração apropriado para sua plataforma
Criar um arquivo projects.yml vazio se não existir
Atualizar a configuração do Claude Desktop

Após executar o script, reinicie o Claude Desktop para aplicar as alterações.

Opção 3: Configuração Direta

Crie o diretório de configuração apropriado para sua plataforma:
- macOS: $XDG_CONFIG_HOME/rails-mcp ou ~/.config/rails-mcp se XDG_CONFIG_HOME não estiver definido
- Windows: %APPDATA%\rails-mcp
Crie um arquivo projects.yml nesse diretório com seus projetos Rails.
Encontre ou crie o arquivo de configuração do Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Adicione ou atualize a configuração do servidor MCP:

{
  "mcpServers": {
    "railsMcpServer": {
      "command": "ruby",
      "args": ["/full/path/to/rails-mcp-server/exe/rails-mcp-server"] 
    }
  }
}

Reinicie o Claude Desktop para aplicar as alterações.

Usuários de Gerenciadores de Versão Ruby

Dois Rubies diferentes estão envolvidos, e o servidor os trata de forma diferente.

1. O Ruby que executa o servidor MCP

Seu cliente MCP (por exemplo, Claude Desktop) inicia o servidor usando o Ruby padrão do seu sistema, ignorando a inicialização do gerenciador de versão. O servidor deve rodar no Ruby onde sua gem está instalada, ou a inicialização falhará. Aponte o command do cliente para o caminho absoluto desse Ruby — para um gerenciador de versão, seu shim funciona:

{
  "mcpServers": {
    "railsMcpServer": {
      "command": "/home/your_user/.rbenv/shims/ruby",
      "args": ["/full/path/to/rails-mcp-server/exe/rails-mcp-server"] 
    }
  }
}

Substitua /home/your_user/.rbenv/shims/ruby pelo seu caminho real do Ruby (um shim rbenv/mise/asdf, ou seu Ruby rvm/chruby).

Dica: A ferramenta rails-mcp-config detecta este Ruby automaticamente (via RbConfig.ruby) e escreve o caminho absoluto correto ao configurar o Claude Desktop.

2. O Ruby usado para inspecionar cada projeto Rails

Ferramentas que inicializam seu aplicativo — get_schema, get_routes, e a metade de introspecção de analyze_models / analyze_controller_views — executam bin/rails dentro do diretório do projeto. O servidor seleciona o Ruby do projeto automaticamente e é agnóstico ao seu gerenciador de versão: ele antepõe os shims do gerenciador ativo (mise, asdf, rbenv) ao PATH do subprocesso e carrega rvm quando presente, então usa um shell não-login para que o path_helper do macOS não possa substituir o Ruby do sistema. A versão é obtida do .ruby-version / .tool-versions / .mise.toml do projeto, então projetos diferentes podem usar Rubies diferentes sem configuração adicional.

Nenhum workaround manual de PATH é necessário. Anteriormente, essas ferramentas podiam cair no Ruby do sistema em máquinas mise/asdf, onde o Bundler do aplicativo então falhava ao inicializar.

Usando um Proxy MCP (Avançado)

O Claude Desktop e muitos outros clientes LLM só suportam comunicação em modo STDIO, mas você pode querer usar as capacidades HTTP/SSE do servidor. Um proxy MCP pode preencher essa lacuna:

Inicie o Rails MCP Server em modo HTTP:

rails-mcp-server --mode http

Instale e execute um proxy MCP. Existem várias implementações disponíveis em diferentes linguagens. Um proxy MCP permite que um cliente que só suporta comunicação STDIO se comunique via HTTP SSE. Aqui está um exemplo usando um proxy MCP baseado em JavaScript:

# Install the Node.js based MCP proxy
npm install -g mcp-remote

# Run the proxy, pointing to your running Rails MCP Server
npx mcp-remote http://localhost:6029/mcp/sse

Configure o Claude Desktop (ou outro cliente LLM) para usar o proxy em vez de conectar diretamente ao servidor:

{
  "mcpServers": {
    "railsMcpServer": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:6029/mcp/sse"]
    }
  }
}

Esta configuração permite que clientes apenas-STDIO se comuniquem com o Rails MCP Server através do proxy, beneficiando-se das capacidades HTTP/SSE enquanto mantém a compatibilidade com o cliente.

Dica: A ferramenta rails-mcp-config pode configurar o modo HTTP com mcp-remote automaticamente.

Integração com GitHub Copilot Agent

O Rails MCP Server funciona com o agente de codificação GitHub Copilot prontamente. O servidor detecta automaticamente projetos Rails quando iniciado a partir de um diretório Rails ou quando configurado com variáveis de ambiente.

Configuração Rápida

Configure MCP - Crie .github/copilot/mcp.json no seu repositório:

{
  "mcpServers": {
    "rails": {
      "type": "local",
      "command": "rails-mcp-server",
      "args": ["--single-project"],
      "tools": ["switch_project", "search_tools", "execute_tool"]
    }
  }
}

Etapas de Configuração - Crie .github/workflows/copilot-setup-steps.yml:

name: "Copilot Setup Steps"

on: workflow_dispatch

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true

      - name: Install Rails MCP Server
        run: gem install rails-mcp-server

Alternativa: Variável de Ambiente

Você também pode usar a variável de ambiente RAILS_MCP_PROJECT_PATH:

{
  "mcpServers": {
    "rails": {
      "type": "local",
      "command": "rails-mcp-server",
      "env": {
        "RAILS_MCP_PROJECT_PATH": "."
      },
      "tools": ["switch_project", "search_tools", "execute_tool"]
    }
  }
}

Limitações

O GitHub Copilot Agent só suporta ferramentas MCP, não recursos ou prompts
O analisador load_guide funciona via execute_tool, mas requer que os guias sejam baixados durante a configuração

Para instruções detalhadas, veja docs/COPILOT_AGENT.md.

Como o Servidor Funciona

O Rails MCP Server implementa o Model Context Protocol usando:

Modo STDIO: Lê solicitações JSON-RPC 2.0 da entrada padrão e retorna respostas para a saída padrão.
Modo HTTP: Fornece endpoints HTTP para solicitações JSON-RPC 2.0 e Server-Sent Events.

Cada solicitação inclui um número de sequência para corresponder solicitações com respostas, conforme definido na especificação MCP. O servidor mantém contexto do projeto e fornece capacidades de análise específicas do Rails em múltiplos codebases.

Arquitetura Eficiente em Contexto

O servidor usa uma arquitetura de descoberta progressiva de ferramentas para minimizar o uso de contexto. Em vez de expor todas as ferramentas antecipadamente, ele fornece 3 ferramentas de inicialização que permitem que LLMs descubram e invoquem os analisadores de introspecção sob demanda:

switch_project - Selecione o projeto Rails ativo
search_tools - Descubra ferramentas disponíveis por categoria ou palavra-chave
execute_tool - Invoque analisadores internos com parâmetros

Este design mantém o contexto inicial pequeno enquanto expõe o conjunto completo de analisadores sob demanda.

Guia para Agentes de IA

Para agentes de IA (Claude, GPT, etc.) usando este servidor, veja o abrangente Guia para Agentes de IA que cobre:

Fluxo de trabalho de início rápido
Guia de seleção de ferramentas para tarefas comuns
Armadilhas comuns e como evitá-las
Tratamento de erros e estratégias de fallback
Integração com outros servidores MCP (por exemplo, Neovim MCP)

Ferramentas Disponíveis

O servidor fornece 3 ferramentas registradas mais analisadores internos acessíveis via execute_tool.

Ferramentas Registradas

1. `switch_project`

Descrição: Altere o projeto Rails ativo. Deve ser chamado antes de usar outras ferramentas.

Parâmetros:

project_name: (String, obrigatório) Nome do projeto conforme definido em projects.yml

Após a troca, você verá um Guia de Início Rápido com comandos comuns.

2. `search_tools`

Descrição: Descubra ferramentas disponíveis por categoria ou palavra-chave.

Parâmetros:

query: (String, opcional) Termo de busca (por exemplo, 'routes', 'model', 'schema')
category: (String, opcional) Filtrar por categoria: models, database, routing, controllers, files, project, guides
detail_level: (String, opcional) Detalhe da saída: 'names', 'summary' ou 'full' (padrão: 'summary')

3. `execute_tool`

Descrição: Invoque analisadores internos pelo nome.

Parâmetros:

tool_name: (String, obrigatório) Nome do analisador (por exemplo, 'get_routes', 'analyze_models')
params: (Hash, opcional) Parâmetros para o analisador

Analisadores Internos (via execute_tool)

`project_info`

Recupere informações abrangentes do projeto incluindo versão do Rails, estrutura de diretórios e organização.

execute_tool(tool_name: "project_info")

`list_files`

Liste arquivos que correspondem a um padrão em um diretório.

execute_tool(tool_name: "list_files", params: { directory: "app/models", pattern: "*.rb" })

`get_file`

Recupera o conteúdo de um arquivo específico.

execute_tool(tool_name: "get_file", params: { path: "app/models/user.rb" })

`get_routes`

Recupera as rotas do Rails com filtragem opcional.

execute_tool(tool_name: "get_routes")
execute_tool(tool_name: "get_routes", params: { controller: "users" })
execute_tool(tool_name: "get_routes", params: { verb: "POST" })
execute_tool(tool_name: "get_routes", params: { path_contains: "api" })

`analyze_models`

Analisa modelos Active Record com associações, validações e análise estática opcional do Prism.

execute_tool(tool_name: "analyze_models")
execute_tool(tool_name: "analyze_models", params: { model_name: "User" })
execute_tool(tool_name: "analyze_models", params: { model_name: "User", analysis_type: "full" })
execute_tool(tool_name: "analyze_models", params: { detail_level: "names" })

Parâmetros:

model_name: Modelo específico a ser analisado
model_names: Matriz de modelos a serem analisados
detail_level: 'names', 'summary' ou 'full'
analysis_type: 'introspection', 'static' ou 'full' (inclui análise AST do Prism)

`get_schema`

Recupera informações do esquema do banco de dados.

execute_tool(tool_name: "get_schema")
execute_tool(tool_name: "get_schema", params: { table_name: "users" })
execute_tool(tool_name: "get_schema", params: { detail_level: "tables" })

`analyze_controller_views`

Analisa as relações entre controladores e visões com análise estática opcional do Prism.

execute_tool(tool_name: "analyze_controller_views")
execute_tool(tool_name: "analyze_controller_views", params: { controller_name: "users" })
execute_tool(tool_name: "analyze_controller_views", params: { controller_name: "users", analysis_type: "full" })

`analyze_environment_config`

Analisa as configurações de ambiente em busca de inconsistências e problemas de segurança.

execute_tool(tool_name: "analyze_environment_config")

`load_guide`

Carrega guias de documentação do Rails, Turbo, Stimulus, Kamal ou personalizadas.

execute_tool(tool_name: "load_guide", params: { library: "rails" })
execute_tool(tool_name: "load_guide", params: { library: "rails", guide: "getting_started" })
execute_tool(tool_name: "load_guide", params: { library: "turbo" })
execute_tool(tool_name: "load_guide", params: { library: "stimulus" })
execute_tool(tool_name: "load_guide", params: { library: "custom", guide: "tailwind" })

Recursos e Documentação

O Rails MCP Server fornece acesso a documentação abrangente por meio da ferramenta load_guide e acesso direto a recursos MCP. Você pode acessar guias oficiais para Rails, Turbo, Stimulus e Kamal, bem como importar sua própria documentação personalizada.

Categorias de Recursos Disponíveis

Guias do Rails: Documentação oficial do Ruby on Rails 8.0.2
Guias do Turbo: Documentação oficial do framework Turbo (Hotwire)
Guias do Stimulus: Documentação oficial do framework JavaScript Stimulus
Guias do Kamal: Documentação oficial da ferramenta de implantação Kamal
Guias Personalizadas: Seus arquivos markdown importados

Começando com Recursos

A maneira mais fácil de gerenciar recursos é usando a ferramenta de configuração:

rails-mcp-config

Em seguida, selecione "Baixar guias" ou "Importar guias personalizadas" no menu.

Alternativamente, você pode usar as ferramentas de linha de comando legadas:

# Download Rails guides
rails-mcp-server-download-resources rails

# Download Turbo guides
rails-mcp-server-download-resources turbo

# Import custom markdown files
rails-mcp-server-download-resources --file /path/to/your/docs/

Métodos de Acesso a Recursos

Acesso baseado em ferramentas: Use a ferramenta load_guide em conversas
Acesso direto a recursos: Clientes MCP podem consultar recursos usando padrões de URI como rails://guides/{guide_name}

Para informações completas sobre download, gerenciamento e uso de recursos, consulte o Guia de Recursos.

Testes e Depuração

A maneira mais fácil de testar e depurar o Rails MCP Server é usando o MCP Inspector, uma ferramenta de desenvolvedor projetada especificamente para testar e depurar servidores MCP.

Para usar o MCP Inspector com o Rails MCP Server:

# Install and run MCP Inspector
npm -g install @modelcontextprotocol/inspector

npx @modelcontextprotocol/inspector /path/to/rails-mcp-server

Isso irá:

Iniciar seu Rails MCP Server em modo HTTP
Abrir a interface do MCP Inspector no seu navegador (porta padrão: 6274)
Configurar um servidor proxy MCP (porta padrão: 6277)

Na interface do MCP Inspector, você pode:

Ver todas as ferramentas disponíveis (você deve ver 3 ferramentas registradas)
Executar chamadas de ferramentas interativamente
Visualizar detalhes de requisições e respostas
Depurar problemas em tempo real

A interface do Inspector fornece uma interface intuitiva para interagir com seu servidor MCP, facilitando o teste e a depuração da sua implementação do Rails MCP Server.

Fluxo de Trabalho de Testes

Mude para um projeto: switch_project com o nome do seu projeto
Descubra ferramentas: search_tools para ver os analisadores disponíveis
Teste analisadores: execute_tool para invocar analisadores específicos (ex.: get_routes, get_schema)
Leia um arquivo: execute_tool com get_file, ex.: { "path": "Gemfile" }

Integração com Clientes LLM

Este servidor foi projetado para ser integrado com clientes LLM que suportam o Model Context Protocol, como Claude Desktop ou outros aplicativos compatíveis com MCP.

Para usar com um cliente MCP:

Inicie o Rails MCP Server (ele usará o modo STDIO por padrão)
Conecte seu cliente compatível com MCP ao servidor
O cliente poderá usar as ferramentas disponíveis para interagir com seus projetos Rails

Para equipes que usam um cliente de IA gerenciado ou plano de controle para acesso a ferramentas, aprovações, trilhas de auditoria e relatórios de custos, consulte Clientes MCP Gerenciados.

Segurança

Para preocupações de segurança, consulte SECURITY.md.

Licença

Este servidor Rails MCP é distribuído sob a Licença MIT, uma licença de código aberto permissiva que permite uso gratuito, modificação, distribuição e uso privado.

A permissão é concedida, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e dos arquivos de documentação associados (o "Software"), para lidar com o Software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e permitir que pessoas a quem o Software seja fornecido façam o mesmo, sujeito às seguintes condições:

O aviso de direitos autorais acima e este aviso de permissão devem ser incluídos em todas as cópias ou partes substanciais do Software.

O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIABILIDADE, ADEQUAÇÃO A UM FIM ESPECÍFICO E NÃO VIOLAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO DE CONTRATO, ATO ILÍCITO OU DE OUTRA FORMA, DECORRENTE DE, OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.

Contribuindo

Relatórios de bugs e pull requests são bem-vindos no GitHub em https://github.com/maquina-app/rails-mcp-server.

Rails MCP Server

Documentação

Rails MCP Server

O que é MCP?

Recursos

Instalação

Configuração

Usando a Ferramenta de Configuração (Recomendado)

Configuração Manual

Uso

Iniciando o servidor

Acesso à Rede (Modo HTTP)

Opções de Registro

Integração com Claude Desktop

Opção 1: Use a ferramenta de configuração (recomendado)

Opção 2: Use o script de configuração (legado)

Opção 3: Configuração Direta

Usuários de Gerenciadores de Versão Ruby

1. O Ruby que executa o servidor MCP

2. O Ruby usado para inspecionar cada projeto Rails

Usando um Proxy MCP (Avançado)

Integração com GitHub Copilot Agent

Configuração Rápida

Alternativa: Variável de Ambiente

Limitações

Como o Servidor Funciona

Arquitetura Eficiente em Contexto

Guia para Agentes de IA

Ferramentas Disponíveis

Ferramentas Registradas

1. switch_project

2. search_tools

3. execute_tool

Analisadores Internos (via execute_tool)

project_info

list_files

get_file

get_routes

analyze_models

get_schema

analyze_controller_views

analyze_environment_config

load_guide

Recursos e Documentação

Categorias de Recursos Disponíveis

Começando com Recursos

Métodos de Acesso a Recursos

Testes e Depuração

Fluxo de Trabalho de Testes

Integração com Clientes LLM

Segurança

Licença

Contribuindo

1. `switch_project`

2. `search_tools`

3. `execute_tool`

`project_info`

`list_files`

`get_file`

`get_routes`

`analyze_models`

`get_schema`

`analyze_controller_views`

`analyze_environment_config`

`load_guide`