Tidewave Rails

Tidewave Rails

O Tidewave Rails é um servidor MCP que fornece ferramentas em nível de runtime para desenvolver aplicativos Ruby on Rails usando agentes de codificação.

Seu agente poderá usar este servidor MCP para conversar com seu aplicativo Rails em execução durante o desenvolvimento para:

• executar código no contexto do aplicativo em execução (como um console Rails para agentes)
• ler os logs ao vivo do aplicativo
• consultar seu banco de dados de desenvolvimento
• obter localizações de origem de classes e métodos
• ler documentação fixada nas versões exatas das gems das quais seu aplicativo depende

Este servidor MCP é um componente de código aberto do Tidewave, o ambiente de desenvolvimento agêntico para Rails e Phoenix.

Você pode usar este projeto como um servidor MCP autônomo ou integrado ao produto Tidewave seguindo as instruções abaixo.

Instalação

1. Adicione a gem Tidewave ao seu aplicativo

Você pode adicionar o Tidewave Rails ao seu aplicativo executando:

bundle add tidewave --group development

ou adicionando manualmente a gem tidewave ao grupo de desenvolvimento no seu Gemfile:

gem "tidewave", group: :development

2. Adicione o MCP Tidewave ao seu agente/editor

Adicione o servidor MCP Tidewave ao seu editor ou à configuração do cliente MCP como tipo "http" (streamable), apontando para o caminho /tidewave/mcp e a porta em que seu aplicativo web está rodando. Por exemplo, http://localhost:3000/tidewave/mcp.

Também temos instruções específicas para:

• Claude Code
• Codex
• Cursor
• Neovim
• OpenCode
• VS Code
• Outros

Uso

Como com qualquer outro servidor MCP, seu agente chamará as ferramentas expostas pelo MCP Tidewave sempre que julgar apropriado. Mas você também pode instruí-lo a chamá-las explicitamente.

Ferramentas MCP disponíveis

project_eval

Avalia código Ruby no contexto do seu aplicativo em execução, com acesso ao seu runtime, dependências carregadas e dados em memória, retornando o resultado mais qualquer coisa impressa na saída padrão. É como um console Rails para o agente.

Seu agente pode usá-la quando preferir executar código em vez de assumir comportamento, fundamentando seu próximo passo no que o aplicativo em execução realmente faz. Por exemplo, chamar um método para ver o que retorna ou reproduzir um caminho de código com falha contra o estado vivo do aplicativo para depurá-lo.

execute_sql_query

Executa uma consulta SQL contra o banco de dados de desenvolvimento do seu aplicativo e retorna as linhas ao agente.

Seu agente pode usá-la para executar qualquer SQL contra seu banco de dados de desenvolvimento. Por exemplo, peça para inserir alguns registros de teste para ver como uma página fica com dados realistas. Ou, após uma ação de criação, o agente pode verificar se o registro foi salvo com os valores esperados.

get_docs

Consulta a documentação de uma classe, método ou constante, lendo das versões exatas das gems travadas no Gemfile.lock do seu aplicativo.

Seu agente pode usá-la quando não tiver certeza de como uma classe ou método funciona, para que o código gerado seja fundamentado na documentação das versões exatas das gems que seu aplicativo usa, em vez de dados de treinamento que podem estar desatualizados ou uma consulta genérica de documentação que não pode garantir que corresponda à versão da qual seu aplicativo depende.

get_source_location

Retorna o arquivo e a linha onde uma classe, módulo ou método é definido, tanto no seu aplicativo quanto em suas dependências.

Seu agente pode usá-la para ir direto ao local onde uma classe ou método é definido, por arquivo e linha, em vez de procurar com grep, inclusive quando a definição está em uma dependência de gem.

Além disso, como ela resolve a localização a partir do seu aplicativo em execução em vez de analisar o texto-fonte, ela lida com metaprogramação, onde um método é gerado em runtime e não aparece como um def literal para o grep encontrar.

[!NOTE]

Por que não há ferramentas para rotas, associações, etc.?

O Tidewave não inclui ferramentas para listar suas rotas, associações, etc., porque os agentes são melhores lendo seus respectivos arquivos-fonte, o que dá aos agentes mais contexto e permite que eles façam qualquer edição necessária sem chamadas adicionais de ferramentas.

Em vez disso, o Tidewave visa preencher lacunas ausentes, como avaliar código dentro do seu aplicativo Rails (sem iniciar novas instâncias) e encontrar a localização da origem, o que pode ser complicado, mesmo com grep, devido à metaprogramação e aos diferentes lugares onde o Bundler pode instalar suas dependências.

Solução de problemas

A barra de ferramentas do Tidewave está ausente

Isso pode acontecer se você estiver comprimindo suas respostas (gzip, brotli, etc.) após o middleware do Tidewave ser executado. Use bin/rails middleware e certifique-se de que o Tidewave venha depois de Rack::Deflater ou similar. Verifique também os logs do seu navegador e terminal para quaisquer erros.

Usando múltiplos hosts/subdomínios

Se você estiver usando múltiplos hosts/subdomínios durante o desenvolvimento, você deve usar *.localhost, pois tais domínios são considerados seguros pelos navegadores. Além disso, adicione o seguinte a config/initializers/development.rb:

config.session_store :cookie_store,
  key: "__your_app_session",
  same_site: :none,
  secure: true,
  assume_ssl: true

E certifique-se de estar usando rack-session versão 2.1.0 ou posterior.

O acima permitirá que seu aplicativo seja executado incorporado dentro do Tidewave em múltiplos subdomínios, desde que esteja usando um contexto seguro (como admin.localhost, www.foobar.localhost, etc.).

Política de segurança de conteúdo

Se você habilitou a Content-Security-Policy, o Tidewave habilitará automaticamente "unsafe-eval" sob script-src para que os testes contextuais no navegador funcionem corretamente. Ele também desabilita a diretiva frame-ancestors. Isso é feito apenas nos ambientes em que o Tidewave é carregado (desenvolvimento por padrão).

Ambiente de produção

O Tidewave é uma ferramenta poderosa que pode ajudá-lo a desenvolver seu aplicativo web de forma mais rápida e eficiente. No entanto, é importante observar que o Tidewave não deve ser usado em um ambiente de produção.

O Tidewave levantará um erro se for usado em qualquer ambiente onde o recarregamento de código esteja desabilitado (o que normalmente inclui produção).

Configuração

Você pode configurar tidewave usando a seguinte sintaxe:

  config.tidewave.team = { id: "my-company" }

A seguinte configuração está disponível:

• allow_remote_access - O Tidewave só permite requisições de localhost por padrão, mesmo que seu servidor escute em outras interfaces, por questões de segurança. Leia nossas diretrizes de segurança para mais informações e quando permitir acesso remoto (se você souber o que está fazendo)

• logger_middleware - O middleware de logger que o Tidewave deve envolver para silenciar seus próprios logs

• preferred_orm - qual ORM usar, seja :active_record (padrão) ou :sequel

• team - defina sua configuração de equipe Tidewave, como config.tidewave.team = { id: "my-company" }

• toolbar - controla se a barra de ferramentas do Tidewave é injetada em páginas HTML. O padrão é true

Agradecimentos

Um agradecimento a Yorick Jacquin pela versão inicial deste projeto.

Desenvolvimento

Execute a suíte Minitest com:

bundle exec ruby -Itest test/all_test.rb

Licença

Copyright (c) 2025 Dashbit

Licenciado sob a Apache License, Versão 2.0 (a "Licença"); você não pode usar este arquivo exceto em conformidade com a Licença. Você pode obter uma cópia da Licença em http://www.apache.org/licenses/LICENSE-2.0

Salvo disposição em contrário da lei aplicável ou acordo por escrito, o software distribuído sob a Licença é distribuído "COMO ESTÁ", SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas. Consulte a Licença para os termos específicos que regem as permissões e limitações sob a Licença.