Tidewave Phoenix

Mejor desarrollo agéntico de Phoenix, herramientas a nivel de ejecución para que tu agente hable con tu aplicación en funcionamiento.

GitHub
853
Prueba este MCPPatrocinado

Documentación

Tidewave Phoenix

Tidewave Phoenix es un servidor MCP que proporciona herramientas a nivel de runtime para desarrollar aplicaciones Phoenix usando agentes de codificación.

Tu agente podrá usar este servidor MCP para comunicarse con tu aplicación Phoenix en ejecución durante el desarrollo y así:

  • ejecutar código en el contexto de la aplicación en ejecución (como una sesión de IEx para agentes)
  • leer los logs en vivo de la aplicación
  • consultar tu base de datos de desarrollo
  • obtener las ubicaciones de origen de módulos y funciones
  • leer documentación fijada a las versiones exactas de los paquetes hex de los que depende tu proyecto

Este servidor MCP es un componente de código abierto de Tidewave, el entorno de desarrollo agéntico para Phoenix y Rails.

Puedes usar este proyecto como un servidor MCP independiente o integrado con el producto Tidewave siguiendo las instrucciones de instalación a continuación.

Instalación

1. Añade el paquete hex de Tidewave a tu aplicación

Opción 1: Manualmente

Añade el paquete tidewave a tu mix.exs:

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

Luego, para aplicaciones Phoenix, ve a tu lib/my_app_web/endpoint.ex y justo encima del bloque if code_reloading? do, añade:

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

   if code_reloading? do

[!TIP] Tidewave funciona mejor con Phoenix LiveView v1.1 o posterior. Una vez que lo actualices, asegúrate de habilitar las siguientes opciones en tu config/dev.exs:

config :phoenix_live_view,
  debug_heex_annotations: true,
  debug_attributes: true

Estas están habilitadas por defecto para aplicaciones Phoenix v1.8+.

Opción 2: Usando Igniter

Alternativamente, puedes usar igniter para instalar automáticamente Tidewave MCP en una aplicación Phoenix existente:

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

# install tidewave
mix igniter.install tidewave

Proyectos umbrella

Para proyectos umbrella, puedes seguir los pasos manuales anteriores en la aplicación que define tu endpoint de Phoenix (típicamente apps/your_app_web).

2. Añade el MCP de Tidewave a tu agente/editor

Añade el servidor MCP de Tidewave a tu editor o configuración de cliente MCP como tipo "http" (transmisible), apuntando a la ruta /tidewave/mcp y al puerto en el que se está ejecutando tu aplicación web. Por ejemplo, http://localhost:4000/tidewave/mcp.

También tenemos instrucciones específicas para:

[!TIP] Si estás usando worktrees, es probable que estés ejecutando tu servidor web en diferentes puertos y, por lo tanto, no hay una única combinación de host y puerto que puedas usar.

En tales casos, es posible que desees añadir mix tidewave.proxy como MCP STDIO en su lugar, lo que añade un parámetro "port" a todas las definiciones de herramientas y es responsable de enviar a la aplicación correcta.

Uso

Como con cualquier otro servidor MCP, tu agente llamará a las herramientas expuestas por el MCP de Tidewave cuando lo considere oportuno. Pero también puedes indicarle que las llame explícitamente.

Herramientas MCP disponibles

project_eval

Evalúa código Elixir dentro de tu aplicación en ejecución, dando al agente acceso a tu runtime, dependencias y datos en memoria. Es como un IEx para el agente.

project_eval demo

Tu agente puede usarlo cuando prefiera ejecutar código en lugar de asumir comportamiento, basando su siguiente paso en lo que la aplicación en ejecución realmente hace. Por ejemplo, llamar a una función para ver qué devuelve o reproducir una ruta de código fallida contra el estado vivo de la aplicación para depurarla.

execute_sql_query

Ejecuta una consulta SQL dentro de la base de datos de desarrollo de tu aplicación.

execute_sql_query demo

Tu agente puede usarlo para ejecutar cualquier SQL contra tu base de datos de desarrollo. Útil para que el agente verifique el resultado de una acción.

get_docs

Obtén la documentación de un módulo/función dado. Consulta las versiones exactas bloqueadas en el mix.lock de tu proyecto, asegurando que obtienes información correcta.

get_docs demo

get_logs

Lee los logs escritos por el servidor.

get_logs demo

Tu agente puede usarlo para ver qué sucedió después de una solicitud. Por ejemplo, leer el log de solicitudes y el backtrace cuando algo se comporta mal.

get_source_location

Obtén la ubicación de origen de un módulo/función dado, tanto en tu aplicación como en sus dependencias.

get_source_location demo

Tu agente puede usarlo para ir directamente a donde está definido un módulo/función, por archivo y línea, en lugar de buscarlo, incluso cuando la definición vive en una dependencia hex.

Solución de problemas

Uso de múltiples hosts/subdominios

Si estás usando múltiples hosts/subdominios durante el desarrollo, debes usar *.localhost, ya que dichos dominios son considerados seguros por los navegadores. Además, añade lo siguiente inmediatamente @session_options definición en tu 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

Lo anterior permitirá que tu aplicación se ejecute integrada dentro de Tidewave en múltiples subdominios, siempre que esté usando un contexto seguro (como admin.localhost, www.foobar.localhost, etc).

Política de seguridad de contenido

Si has habilitado Content-Security-Policy, Tidewave habilitará automáticamente "unsafe-eval" bajo script-src para que las pruebas contextuales del navegador funcionen correctamente. También deshabilita la directiva frame-ancestors. Esto se hace solo en los entornos donde Tidewave está cargado (desarrollo por defecto).

Configuración

Puedes configurar el plug Tidewave usando la siguiente sintaxis:

  plug Tidewave, options

Las siguientes opciones están disponibles:

  • :allow_remote_access - Tidewave solo permite solicitudes desde localhost por defecto, incluso si tu servidor escucha en otras interfaces, por razones de seguridad. Lee nuestras pautas de seguridad para más información y cuándo permitir acceso remoto (si sabes lo que estás haciendo)

  • :allowed_origins - una lista de valores comparados contra el encabezado Origin para prevenir ataques de cross origin y DNS rebinding. Cada valor debe ser una cadena con la forma [scheme:]//host[:port], donde tanto el esquema como el puerto son opcionales. El host también puede comenzar con "*". Ejemplo: ["//localhost:8000", "//*.test"]

  • :inspect_opts - opciones personalizadas pasadas a Kernel.inspect/2 al formatear algunos resultados de herramientas. Por defecto: [charlists: :as_lists, limit: 50, pretty: true]

  • :team - establece tu configuración de Tidewave Team, como team: [id: "my-company"]

  • :toolbar - controla si la barra de herramientas de Tidewave se inyecta en tus páginas HTML. Por defecto: true

  • tmp_dir - directorio temporal que Tidewave usa para capturas de pantalla y grabaciones. Debe ser un directorio relativo a la raíz de la aplicación actual. Por defecto: tmp, almacenando archivos bajo tmp/tidewave/screenshots y tmp/tidewave/recordings

Licencia

Copyright (c) 2025 Dashbit

Licenciado bajo la Licencia Apache, Versión 2.0 (la "Licencia"); no puedes usar este archivo excepto en cumplimiento con la Licencia. Puedes obtener una copia de la Licencia en http://www.apache.org/licenses/LICENSE-2.0

Salvo que lo exija la ley aplicable o se acuerde por escrito, el software distribuido bajo la Licencia se distribuye "TAL CUAL", SIN GARANTÍAS NI CONDICIONES DE NINGÚN TIPO, ya sean expresas o implícitas. Consulta la Licencia para el lenguaje específico que rige los permisos y limitaciones bajo la Licencia.