Rails MCP Server

Un servidor MCP para proyectos Rails, que permite a los LLMs interactuar con tu aplicación.

Documentación

Rails MCP Server

Una implementación en Ruby de un servidor de Model Context Protocol (MCP) para proyectos Rails. Este servidor permite que los LLMs (Modelos de Lenguaje de Gran Escala) interactúen con proyectos Rails a través del Model Context Protocol, proporcionando capacidades para análisis de código, exploración y asistencia de desarrollo.

¿Qué es MCP?

El Model Context Protocol (MCP) es una forma estandarizada para que los modelos de IA interactúen con su entorno. Define un método estructurado para que los modelos soliciten y utilicen herramientas, accedan a recursos y mantengan contexto durante las interacciones.

Este Rails MCP Server implementa la especificación MCP para dar a los modelos de IA acceso a proyectos Rails para análisis de código, exploración y asistencia.

Características

Gestiona múltiples proyectos Rails
Explora archivos y estructuras de proyectos
Visualiza rutas de Rails con opciones de filtrado
Inspecciona información de modelos y relaciones (con análisis estático Prism)
Obtiene información del esquema de base de datos
Analiza relaciones controlador-vista
Analiza configuraciones de entorno
Accede a documentación completa de Rails, Turbo, Stimulus y Kamal
Arquitectura eficiente en contexto con descubrimiento progresivo de herramientas
Integración perfecta con clientes LLM

Instalación

Instala la gema:

gem install rails-mcp-server

Después de la instalación, los siguientes ejecutables estarán disponibles en tu PATH:

rails-mcp-server - El servidor MCP en sí
rails-mcp-config - Herramienta de configuración interactiva (recomendada)
rails-mcp-setup-claude - Script de configuración heredado para Claude Desktop
rails-mcp-server-download-resources - Script heredado de descarga de recursos

Configuración

Usando la Herramienta de Configuración (Recomendada)

La forma más fácil de configurar el Rails MCP Server es usando la herramienta de configuración interactiva:

rails-mcp-config

Esto proporciona una TUI (Interfaz de Usuario de Terminal) amigable para:

Gestión de Proyectos: Añadir, editar, eliminar y validar proyectos Rails
Descarga de Guías: Descargar documentación de Rails, Turbo, Stimulus y Kamal
Importación de Guías Personalizadas: Añadir tu propia documentación markdown
Integración con Claude Desktop: Configurar Claude Desktop automáticamente

La herramienta usa Gum para una experiencia mejorada si está instalado, pero funciona con un modo básico de terminal como alternativa.

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

Configuración Manual

El Rails MCP Server sigue la Especificación de Directorio Base XDG para archivos de configuración:

En macOS: $XDG_CONFIG_HOME/rails-mcp o ~/.config/rails-mcp si XDG_CONFIG_HOME no está configurado
En Windows: %APPDATA%\rails-mcp

El servidor creará automáticamente estos directorios y un archivo projects.yml vacío la primera vez que se ejecute.

Para configurar tus proyectos manualmente:

Edita el archivo projects.yml en tu directorio de configuración para incluir tus proyectos Rails:

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

Cada clave en el archivo YAML es un nombre de proyecto (que se usará con la herramienta switch_project), y cada valor es la ruta al directorio del proyecto.

Uso

Iniciando el servidor

El Rails MCP Server puede ejecutarse en dos modos:

Modo STDIO (predeterminado): Se comunica a través de entrada/salida estándar para integración directa con clientes como Claude Desktop.
Modo HTTP: Se ejecuta como un servidor HTTP con endpoints JSON-RPC y 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

Cuando se ejecuta en modo HTTP, el servidor proporciona dos endpoints:

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

Acceso de Red (Modo HTTP)

Por defecto, el servidor HTTP solo se vincula a localhost por seguridad. Si necesitas acceder al servidor desde otras máquinas en tu red local (por ejemplo, para pruebas con múltiples dispositivos), puedes usar la bandera --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

Cuando se usa --bind-all:

El servidor se vincula a 0.0.0.0 en lugar de localhost
Se permite el acceso desde rangos de IP de red local (192.168.x.x, 10.x.x.x)
El servidor acepta conexiones desde nombres de dominio .local (por ejemplo, my-computer.local)
Las características de seguridad permanecen activas para prevenir acceso no autorizado

Nota de Seguridad: Solo usa --bind-all en redes de confianza. El servidor incluye características de seguridad integradas para validar orígenes y direcciones IP, pero exponer cualquier servicio a tu red aumenta la superficie de ataque.

Opciones de Registro

El servidor registra en un archivo en el directorio ./log por defecto. Puedes personalizar el registro con estas opciones:

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

Integración con Claude Desktop

El Rails MCP Server puede usarse con Claude Desktop. Hay múltiples opciones para configurarlo:

Opción 1: Usar la herramienta de configuración (recomendada)

Ejecuta la herramienta de configuración interactiva y selecciona "Integración con Claude Desktop":

rails-mcp-config

La herramienta:

Detectará tu configuración actual de Claude Desktop
Te permitirá elegir entre modo STDIO o HTTP
Encontrará automáticamente las rutas correctas de Ruby y del servidor
Creará una copia de seguridad antes de hacer cambios
Actualizará la configuración de Claude Desktop

Opción 2: Usar el script de configuración (heredado)

Ejecuta el script de configuración que configurará automáticamente Claude Desktop:

rails-mcp-setup-claude

El script:

Creará el directorio de configuración apropiado para tu plataforma
Creará un archivo projects.yml vacío si no existe
Actualizará la configuración de Claude Desktop

Después de ejecutar el script, reinicia Claude Desktop para aplicar los cambios.

Opción 3: Configuración Directa

Crea el directorio de configuración apropiado para tu plataforma:
- macOS: $XDG_CONFIG_HOME/rails-mcp o ~/.config/rails-mcp si XDG_CONFIG_HOME no está configurado
- Windows: %APPDATA%\rails-mcp
Crea un archivo projects.yml en ese directorio con tus proyectos Rails.
Encuentra o crea el archivo de configuración de Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Añade o actualiza la configuración del servidor MCP:

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

Reinicia Claude Desktop para aplicar los cambios.

Usuarios de Ruby Version Manager

Hay dos Rubies diferentes involucrados, y el servidor los maneja de manera diferente.

1. El Ruby que ejecuta el servidor MCP

Tu cliente MCP (por ejemplo, Claude Desktop) lanza el servidor usando el Ruby predeterminado de tu sistema, omitiendo la inicialización del gestor de versiones. El servidor debe ejecutarse en el Ruby donde su gema está instalada, o el inicio fallará. Apunta el command del cliente a la ruta absoluta de ese Ruby — para un gestor de versiones, su shim funciona:

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

Reemplaza /home/your_user/.rbenv/shims/ruby con tu ruta real de Ruby (un shim de rbenv/mise/asdf, o tu Ruby de rvm/chruby).

Consejo: La herramienta rails-mcp-config detecta este Ruby automáticamente (vía RbConfig.ruby) y escribe la ruta absoluta correcta al configurar Claude Desktop.

2. El Ruby usado para inspeccionar cada proyecto Rails

Las herramientas que inician tu aplicación — get_schema, get_routes, y la mitad de introspección de analyze_models / analyze_controller_views — ejecutan bin/rails dentro del directorio del proyecto. El servidor selecciona el Ruby del proyecto automáticamente y es agnóstico a tu gestor de versiones: antepone los shims del gestor activo (mise, asdf, rbenv) al PATH del subproceso y carga rvm cuando está presente, luego usa un shell no-login para que path_helper de macOS no pueda sustituir el Ruby del sistema. La versión se toma del .ruby-version / .tool-versions / .mise.toml del proyecto, por lo que diferentes proyectos pueden usar diferentes Rubies sin configuración adicional.

No se necesita ningún workaround manual de PATH. Anteriormente estas herramientas podían recurrir al Ruby del sistema en máquinas mise/asdf, donde el Bundler de la aplicación luego fallaba al iniciar.

Usando un Proxy MCP (Avanzado)

Claude Desktop y muchos otros clientes LLM solo soportan comunicación en modo STDIO, pero podrías querer usar las capacidades HTTP/SSE del servidor. Un proxy MCP puede cerrar esta brecha:

Inicia el Rails MCP Server en modo HTTP:

rails-mcp-server --mode http

Instala y ejecuta un proxy MCP. Hay varias implementaciones disponibles en diferentes lenguajes. Un proxy MCP permite que un cliente que solo soporta comunicación STDIO se comunique vía HTTP SSE. Aquí hay un ejemplo usando un proxy MCP basado en 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

Configura Claude Desktop (u otro cliente LLM) para usar el proxy en lugar de conectarse directamente al servidor:

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

Esta configuración permite que clientes solo-STDIO se comuniquen con el Rails MCP Server a través del proxy, beneficiándose de las capacidades HTTP/SSE mientras se mantiene la compatibilidad con el cliente.

Consejo: La herramienta rails-mcp-config puede configurar el modo HTTP con mcp-remote automáticamente.

Integración con GitHub Copilot Agent

Rails MCP Server funciona con el agente de codificación GitHub Copilot de forma inmediata. El servidor auto-detecta proyectos Rails cuando se inicia desde un directorio Rails o cuando se configura con variables de entorno.

Configuración Rápida

Configura MCP - Crea .github/copilot/mcp.json en tu repositorio:

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

Pasos de Configuración - Crea .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: Variable de Entorno

También puedes usar la variable de entorno RAILS_MCP_PROJECT_PATH:

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

Limitaciones

GitHub Copilot Agent solo soporta herramientas MCP, no recursos o prompts
El analizador load_guide funciona vía execute_tool, pero requiere que las guías se descarguen durante la configuración

Para instrucciones detalladas, consulta docs/COPILOT_AGENT.md.

Cómo Funciona el Servidor

El Rails MCP Server implementa el Model Context Protocol usando:

Modo STDIO: Lee solicitudes JSON-RPC 2.0 desde la entrada estándar y devuelve respuestas a la salida estándar.
Modo HTTP: Proporciona endpoints HTTP para solicitudes JSON-RPC 2.0 y Server-Sent Events.

Cada solicitud incluye un número de secuencia para emparejar solicitudes con respuestas, como se define en la especificación MCP. El servidor mantiene el contexto del proyecto y proporciona capacidades de análisis específicas de Rails en múltiples bases de código.

Arquitectura Eficiente en Contexto

El servidor usa una arquitectura de descubrimiento progresivo de herramientas para minimizar el uso de contexto. En lugar de exponer todas las herramientas de antemano, proporciona 3 herramientas de arranque que permiten a los LLMs descubrir e invocar los analizadores de introspección bajo demanda:

switch_project - Selecciona el proyecto Rails activo
search_tools - Descubre herramientas disponibles por categoría o palabra clave
execute_tool - Invoca analizadores internos con parámetros

Este diseño mantiene el contexto inicial pequeño mientras expone el conjunto completo de analizadores bajo demanda.

Guía para Agentes de IA

Para agentes de IA (Claude, GPT, etc.) que usan este servidor, consulta la completa Guía para Agentes de IA que cubre:

Flujo de trabajo de inicio rápido
Guía de selección de herramientas para tareas comunes
Errores comunes y cómo evitarlos
Manejo de errores y estrategias de respaldo
Integración con otros servidores MCP (por ejemplo, Neovim MCP)

Herramientas Disponibles

El servidor proporciona 3 herramientas registradas más analizadores internos accesibles vía execute_tool.

Herramientas Registradas

1. `switch_project`

Descripción: Cambia el proyecto Rails activo. Debe llamarse antes de usar otras herramientas.

Parámetros:

project_name: (String, requerido) Nombre del proyecto como se define en projects.yml

Después de cambiar, verás una Guía de Inicio Rápido con comandos comunes.

2. `search_tools`

Descripción: Descubre herramientas disponibles por categoría o palabra clave.

Parámetros:

query: (String, opcional) Término de búsqueda (por ejemplo, 'routes', 'model', 'schema')
category: (String, opcional) Filtrar por categoría: models, database, routing, controllers, files, project, guides
detail_level: (String, opcional) Detalle de salida: 'names', 'summary', o 'full' (predeterminado: 'summary')

3. `execute_tool`

Descripción: Invoca analizadores internos por nombre.

Parámetros:

tool_name: (String, requerido) Nombre del analizador (por ejemplo, 'get_routes', 'analyze_models')
params: (Hash, opcional) Parámetros para el analizador

Analizadores Internos (vía execute_tool)

`project_info`

Recupera información completa del proyecto incluyendo versión de Rails, estructura de directorios y organización.

execute_tool(tool_name: "project_info")

`list_files`

Lista archivos que coinciden con un patrón en un directorio.

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

`get_file`

Recupera el contenido de un archivo específico.

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

`get_routes`

Recupera las rutas de Rails con filtrado 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`

Analiza modelos de Active Record con asociaciones, validaciones y análisis estático opcional de 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 analizar
model_names: Arreglo de modelos a analizar
detail_level: 'names', 'summary' o 'full'
analysis_type: 'introspection', 'static' o 'full' (incluye análisis AST de Prism)

`get_schema`

Recupera información del esquema de la base de datos.

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`

Analiza las relaciones controlador-vista con análisis estático opcional de 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`

Analiza las configuraciones de entorno para detectar inconsistencias y problemas de seguridad.

execute_tool(tool_name: "analyze_environment_config")

`load_guide`

Carga guías de documentación de Rails, Turbo, Stimulus, Kamal o 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 y Documentación

El Rails MCP Server proporciona acceso a documentación completa tanto a través de la herramienta load_guide como mediante acceso directo a recursos MCP. Puedes acceder a las guías oficiales de Rails, Turbo, Stimulus y Kamal, así como importar tu propia documentación personalizada.

Categorías de Recursos Disponibles

Guías de Rails: Documentación oficial de Ruby on Rails 8.0.2
Guías de Turbo: Documentación oficial del framework Turbo (Hotwire)
Guías de Stimulus: Documentación oficial del framework JavaScript Stimulus
Guías de Kamal: Documentación oficial de la herramienta de despliegue Kamal
Guías Personalizadas: Tus archivos markdown importados

Comenzando con los Recursos

La forma más fácil de gestionar recursos es usando la herramienta de configuración:

rails-mcp-config

Luego selecciona "Descargar guías" o "Importar guías personalizadas" del menú.

Alternativamente, puedes usar las herramientas de línea de comandos heredadas:

# 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 Acceso a Recursos

Acceso basado en herramientas: Usa la herramienta load_guide en conversaciones
Acceso directo a recursos: Los clientes MCP pueden consultar recursos usando patrones URI como rails://guides/{guide_name}

Para información completa sobre descargar, gestionar y usar recursos, consulta la Guía de Recursos.

Pruebas y Depuración

La forma más fácil de probar y depurar el Rails MCP Server es usando el MCP Inspector, una herramienta de desarrollo diseñada específicamente para probar y depurar servidores MCP.

Para usar MCP Inspector con Rails MCP Server:

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

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

Esto hará lo siguiente:

Iniciar tu Rails MCP Server en modo HTTP
Lanzar la interfaz de MCP Inspector en tu navegador (puerto predeterminado: 6274)
Configurar un servidor proxy MCP (puerto predeterminado: 6277)

En la interfaz de MCP Inspector, puedes:

Ver todas las herramientas disponibles (deberías ver 3 herramientas registradas)
Ejecutar llamadas a herramientas de forma interactiva
Ver detalles de solicitudes y respuestas
Depurar problemas en tiempo real

La interfaz del Inspector proporciona una interfaz intuitiva para interactuar con tu servidor MCP, facilitando las pruebas y la depuración de tu implementación del Rails MCP Server.

Flujo de Trabajo de Pruebas

Cambia a un proyecto: switch_project con el nombre de tu proyecto
Descubre herramientas: search_tools para ver los analizadores disponibles
Prueba analizadores: execute_tool para invocar analizadores específicos (p. ej. get_routes, get_schema)
Lee un archivo: execute_tool con get_file, p. ej. { "path": "Gemfile" }

Integración con Clientes LLM

Este servidor está diseñado para integrarse con clientes LLM que soporten el Model Context Protocol, como Claude Desktop u otras aplicaciones compatibles con MCP.

Para usar con un cliente MCP:

Inicia el Rails MCP Server (usará el modo STDIO por defecto)
Conecta tu cliente compatible con MCP al servidor
El cliente podrá usar las herramientas disponibles para interactuar con tus proyectos Rails

Para equipos que usan un cliente de IA gobernado o un plano de control para acceso a herramientas, aprobaciones, registros de auditoría e informes de costos, consulta Clientes MCP Gobernados.

Seguridad

Para problemas de seguridad, consulta SECURITY.md.

Licencia

Este servidor Rails MCP se publica bajo la Licencia MIT, una licencia de código abierto permisiva que permite uso libre, modificación, distribución y uso privado.

Por la presente se otorga permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y de los archivos de documentación asociados (el "Software"), para tratar con el Software sin restricción, incluidos, sin limitación, los derechos de usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir que las personas a quienes se les proporcione el Software hagan lo mismo, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUIDAS, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE CUALQUIER RECLAMO, DAÑO U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO MODO, QUE SURJA DE, O EN RELACIÓN CON, EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.

Contribuciones

Los informes de errores y las solicitudes de extracción son bienvenidos en GitHub en https://github.com/maquina-app/rails-mcp-server.

Rails MCP Server

Documentación

Rails MCP Server

¿Qué es MCP?

Características

Instalación

Configuración

Usando la Herramienta de Configuración (Recomendada)

Configuración Manual

Uso

Iniciando el servidor

Acceso de Red (Modo HTTP)

Opciones de Registro

Integración con Claude Desktop

Opción 1: Usar la herramienta de configuración (recomendada)

Opción 2: Usar el script de configuración (heredado)

Opción 3: Configuración Directa

Usuarios de Ruby Version Manager

1. El Ruby que ejecuta el servidor MCP

2. El Ruby usado para inspeccionar cada proyecto Rails

Usando un Proxy MCP (Avanzado)

Integración con GitHub Copilot Agent

Configuración Rápida

Alternativa: Variable de Entorno

Limitaciones

Cómo Funciona el Servidor

Arquitectura Eficiente en Contexto

Guía para Agentes de IA

Herramientas Disponibles

Herramientas Registradas

1. switch_project

2. search_tools

3. execute_tool

Analizadores Internos (vía execute_tool)

project_info

list_files

get_file

get_routes

analyze_models

get_schema

analyze_controller_views

analyze_environment_config

load_guide

Recursos y Documentación

Categorías de Recursos Disponibles

Comenzando con los Recursos

Métodos de Acceso a Recursos

Pruebas y Depuración

Flujo de Trabajo de Pruebas

Integración con Clientes LLM

Seguridad

Licencia

Contribuciones

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`