Tidewave Rails

Tidewave Rails

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

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

• ejecutar código en el contexto de la aplicación en ejecución (como una consola de Rails para agentes)
• leer los logs en vivo de la aplicación
• consultar tu base de datos de desarrollo
• obtener las ubicaciones del código fuente de clases y métodos
• leer documentación fijada a las versiones exactas de las gemas de las que depende tu aplicación

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

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

Instalación

1. Añade la gema Tidewave a tu aplicación

Puedes añadir Tidewave Rails a tu aplicación ejecutando:

bundle add tidewave --group development

o añadiendo manualmente la gema tidewave al grupo de desarrollo en tu Gemfile:

gem "tidewave", group: :development

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

Añade el servidor MCP de Tidewave a tu editor o a la configuración de tu 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:3000/tidewave/mcp.

También tenemos instrucciones específicas para:

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

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 Ruby en el contexto de tu aplicación en ejecución, con acceso a su runtime, dependencias cargadas y datos en memoria, devolviendo el resultado más cualquier cosa impresa en la salida estándar. Es como una consola de Rails para el agente.

Tu agente puede usarla 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 un método para ver qué devuelve o reproducir una ruta de código que falla contra el estado vivo de la aplicación para depurarla.

execute_sql_query

Ejecuta una consulta SQL contra la base de datos de desarrollo de tu aplicación y devuelve las filas al agente.

Tu agente puede usarla para ejecutar cualquier SQL contra tu base de datos de desarrollo. Por ejemplo, pídele que inserte algunos registros de prueba para ver cómo se ve una página con datos realistas. O, después de una acción de creación, el agente puede verificar si el registro se guardó con los valores esperados.

get_docs

Busca la documentación de una clase, método o constante, leyendo desde las versiones exactas de las gemas bloqueadas en el Gemfile.lock de tu aplicación.

Tu agente puede usarla cuando no esté seguro de cómo funciona una clase o método, para que el código que genere se base en la documentación de las versiones exactas de las gemas que usa tu aplicación, en lugar de datos de entrenamiento que pueden estar desactualizados o una búsqueda genérica de documentación que no puede garantizar que coincida con la versión de la que depende tu aplicación.

get_source_location

Devuelve el archivo y la línea donde está definida una clase, módulo o método, tanto en tu aplicación como en sus dependencias.

Tu agente puede usarla para ir directamente a donde está definida una clase o método, por archivo y línea, en lugar de buscarlo con grep, incluso cuando la definición vive en una dependencia de gema.

Además, como resuelve la ubicación desde tu aplicación en ejecución en lugar de analizar el texto fuente, maneja la metaprogramación, donde un método se genera en tiempo de ejecución y no aparece como un def literal que grep pueda encontrar.

[!NOTE]

¿Por qué no hay herramientas para rutas, asociaciones, etc.?

Tidewave no incluye herramientas para listar tus rutas, asociaciones, etc., porque los agentes están mejor leyendo sus respectivos archivos fuente, lo que les da más contexto y les permite realizar cualquier edición necesaria sin llamadas adicionales a herramientas.

En cambio, Tidewave busca llenar los vacíos que faltan, como evaluar código dentro de tu aplicación Rails (sin iniciar nuevas instancias) y encontrar la ubicación del código fuente, lo que puede ser complicado, incluso con grep, debido a la metaprogramación y a los diferentes lugares donde Bundler puede instalar tus dependencias.

Solución de problemas

La barra de herramientas de Tidewave no aparece

Esto puede ocurrir si estás comprimiendo tus respuestas (gzip, brotli, etc.) después de que el middleware de Tidewave se ejecute. Usa bin/rails middleware y asegúrate de que Tidewave venga después de Rack::Deflater o similar. También revisa los logs de tu navegador y terminal para ver si hay errores.

Uso de múltiples hosts/subdominios

Si estás usando múltiples hosts/subdominios durante el desarrollo, debes usar *.localhost, ya que dichos dominios se consideran seguros en los navegadores. Además, añade lo siguiente a config/initializers/development.rb:

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

Y asegúrate de estar usando la versión rack-session 2.1.0 o posterior.

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).

Entorno de producción

Tidewave es una herramienta poderosa que puede ayudarte a desarrollar tu aplicación web más rápido y de manera más eficiente. Sin embargo, es importante tener en cuenta que Tidewave no está pensado para usarse en un entorno de producción.

Tidewave lanzará un error si se usa en cualquier entorno donde la recarga de código esté deshabilitada (lo que típicamente incluye producción).

Configuración

Puedes configurar tidewave usando la siguiente sintaxis:

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

La siguiente configuración está disponible:

• 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)

• logger_middleware - El middleware de logger que Tidewave debe envolver para silenciar sus propios logs

• preferred_orm - qué ORM usar, ya sea :active_record (por defecto) o :sequel

• team - configura tu equipo de Tidewave, como config.tidewave.team = { id: "my-company" }

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

Agradecimientos

Un agradecimiento a Yorick Jacquin por la versión inicial de este proyecto.

Desarrollo

Ejecuta la suite de Minitest con:

bundle exec ruby -Itest test/all_test.rb

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 conocer el idioma específico que rige los permisos y las limitaciones bajo la Licencia.