Tidewave Phoenix

Melhor desenvolvimento agentic Phoenix, ferramentas em nível de runtime para seu agente conversar com seu aplicativo em execução.

GitHub
853
Experimente este MCPPatrocinado

Documentação

Tidewave Phoenix

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

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

  • executar código no contexto do aplicativo em execução (como uma sessão IEx para agentes)
  • ler os logs ao vivo do aplicativo
  • consultar seu banco de dados de desenvolvimento
  • obter localizações de código-fonte de módulos e funções
  • ler documentação fixada nas versões exatas dos pacotes hex dos quais seu projeto depende

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

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

Instalação

1. Adicione o pacote hex Tidewave ao seu aplicativo

Opção 1: Manualmente

Adicione o pacote tidewave ao seu mix.exs:

def deps do
  [
    {:tidewave, "~> 0.9", only: :dev},
    {:phoenix, ...},
  ]
end

Em seguida, para aplicativos Phoenix, vá para o seu lib/my_app_web/endpoint.ex e, logo acima do bloco if code_reloading? do, adicione:

+  if Mix.env() == :dev do
+    plug Tidewave
+  end

   if code_reloading? do

[!TIP] O Tidewave funciona melhor com Phoenix LiveView v1.1 ou posterior. Depois de atualizá-lo, certifique-se de habilitar as seguintes opções no seu config/dev.exs:

config :phoenix_live_view,
  debug_heex_annotations: true,
  debug_attributes: true

Elas estão habilitadas por padrão para aplicativos Phoenix v1.8+.

Opção 2: Usando Igniter

Alternativamente, você pode usar igniter para instalar automaticamente o Tidewave MCP em um aplicativo Phoenix existente:

# install igniter_new if you haven't already
mix archive.install hex igniter_new

# install tidewave
mix igniter.install tidewave

Projetos guarda-chuva

Para projetos guarda-chuva, você pode seguir os passos manuais acima no aplicativo que define seu endpoint Phoenix (tipicamente apps/your_app_web).

2. Adicione o Tidewave MCP ao seu agente/editor

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

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

[!TIP] Se você estiver usando worktrees, provavelmente estará executando seu servidor web em portas diferentes e, portanto, não há uma única combinação de host e porta que você possa usar.

Nesses casos, você pode querer adicionar mix tidewave.proxy como MCP STDIO em vez disso, o que adiciona um parâmetro "port" a todas as definições de ferramentas e é responsável por despachar para o aplicativo correto.

Uso

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

Ferramentas MCP disponíveis

project_eval

Avalia código Elixir dentro do seu aplicativo em execução, dando ao agente acesso ao seu runtime, dependências e dados em memória. É como um IEx para o agente.

project_eval demo

Seu agente pode usá-lo 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 uma função para ver o que retorna ou reproduzir um caminho de código com falha contra o estado do aplicativo ao vivo para depurá-lo.

execute_sql_query

Executa uma consulta SQL no banco de dados de desenvolvimento do seu aplicativo.

execute_sql_query demo

Seu agente pode usá-lo para executar qualquer SQL contra seu banco de dados de desenvolvimento. Útil para o agente verificar o resultado de uma ação.

get_docs

Obtenha a documentação de um determinado módulo/função. Ele consulta as versões exatas bloqueadas no mix.lock do seu projeto, garantindo que você obtenha informações corretas.

get_docs demo

get_logs

Lê logs gravados pelo servidor.

get_logs demo

Seu agente pode usá-lo para ver o que aconteceu após uma solicitação. Por exemplo, ler o log de solicitações e o backtrace quando algo se comporta mal.

get_source_location

Obtenha a localização do código-fonte de um determinado módulo/função, tanto no seu aplicativo quanto em suas dependências.

get_source_location demo

Seu agente pode usá-lo para ir direto para onde um módulo/função é definido, por arquivo e linha, em vez de procurar por ele, inclusive quando a definição está em uma dependência hex.

Solução de problemas

Usando vários hosts/subdomínios

Se você estiver usando vários 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 imediatamente à definição @session_options no seu lib/your_app_web/endpoint.ex:

@session_options [
  # ... your configuration
]

if code_reloading? do
  @session_options Keyword.merge(@session_options, same_site: "None", secure: true)
end

O acima permitirá que seu aplicativo seja executado incorporado dentro do Tidewave em vários 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 Política de Segurança de Conteúdo, o Tidewave habilitará automaticamente "unsafe-eval" sob script-src para que os testes contextuais do 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).

Configuração

Você pode configurar o plug Tidewave usando a seguinte sintaxe:

  plug Tidewave, options

As seguintes opções estão disponíveis:

  • :allow_remote_access - O Tidewave só permite solicitações de localhost por padrão, mesmo que seu servidor escute em outras interfaces, por motivos 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)

  • :allowed_origins - uma lista de valores comparados com o cabeçalho Origin para prevenir ataques de cross-origin e DNS rebinding. Cada valor deve ser uma string no formato [scheme:]//host[:port], onde tanto o esquema quanto a porta são opcionais. O host também pode começar com "*". Exemplo: ["//localhost:8000", "//*.test"]

  • :inspect_opts - opções personalizadas passadas para Kernel.inspect/2 ao formatar alguns resultados de ferramentas. Padrão: [charlists: :as_lists, limit: 50, pretty: true]

  • :team - defina sua configuração de Equipe Tidewave, como team: [id: "my-company"]

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

  • tmp_dir - diretório temporário que o Tidewave usa para capturas de tela e gravações. Deve ser um diretório relativo à raiz do aplicativo atual. Padrão: tmp, armazenando arquivos sob tmp/tidewave/screenshots e tmp/tidewave/recordings

Licença

Copyright (c) 2025 Dashbit

Licenciado sob a Licença Apache, 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

A menos que exigido pela lei aplicável ou acordado 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 o idioma específico que rege as permissões e limitações sob a Licença.