Rails Active MCP

Nota: Este es solo un proyecto personal y, aunque funciona en su mayor parte, todavía lo estoy desarrollando y trato activamente de hacerlo un poco más útil para mis usos.

Rails Active MCP

Una gema de Ruby que proporciona acceso seguro a la consola de Rails a través de Model Context Protocol (MCP) para agentes de IA y herramientas de desarrollo. Construida con el SDK oficial de MCP para Ruby, ofrece un manejo profesional del protocolo y compatibilidad a futuro.

Funciona con cualquier cliente compatible con MCP, incluidos Claude Desktop, Claude Code, VS Code (GitHub Copilot), Cursor, Windsurf, ChatGPT, Gemini CLI, Amazon Q Developer, JetBrains IDEs, Zed, Warp, Cline y muchos más.

Inicio rápido

Ponte en marcha en tres pasos:

1. Instala la gema

Añade a Gemfile de tu aplicación Rails:

gem 'rails-active-mcp'

bundle install

2. Ejecuta el instalador

rails generate rails_active_mcp:install

Esto crea un inicializador, scripts de servidor y te pide que selecciones qué clientes MCP usas. Generará automáticamente los archivos de configuración correctos a nivel de proyecto (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) para que tu cliente MCP detecte el servidor cuando abras el proyecto.

3. Conecta tu cliente MCP

Si seleccionaste tu cliente MCP durante la instalación, ya está listo: solo abre el proyecto y el servidor se detectará automáticamente.

Para configuración manual o clientes adicionales, el servidor usa transporte STDIO. A continuación se muestran ejemplos de configuración para herramientas populares.

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

claude mcp add rails-active-mcp -- bundle exec rails-active-mcp-server

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"]
    }
  }
}

{
  "servers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

{
  "context_servers": {
    "rails-active-mcp": {
      "command": {
        "path": "bundle",
        "args": ["exec", "rails-active-mcp-server"],
        "env": {}
      }
    }
  }
}

{
  "mcpServers": {
    "rails-active-mcp": {
      "command": "bundle",
      "args": ["exec", "rails-active-mcp-server"],
      "cwd": "/path/to/your/rails/project"
    }
  }
}

Una vez conectado, aparecerán automáticamente cuatro herramientas: console_execute, model_info, safe_query y dry_run.

Prueba a preguntar a tu asistente de IA:

• "Muéstrame todos los usuarios creados en la última semana"
• "¿Cuál es el valor promedio de los pedidos?"
• "Revisa el esquema y las asociaciones del modelo User"
• "Analiza este código para verificar su seguridad: User.delete_all"

Características

• 🔒 Ejecución segura: Comprobaciones de seguridad avanzadas que previenen operaciones peligrosas
• 🚀 SDK oficial de MCP: Construido con el SDK oficial de MCP para Ruby, garantiza un manejo robusto del protocolo
• 📊 Consultas de solo lectura: Consultas seguras a la base de datos con limitación automática de resultados
• 🔍 Análisis de código: Capacidad de ejecución en seco para analizar código antes de ejecutarlo
• 📝 Registro de auditoría: Registro completo de ejecuciones para seguridad y depuración
• ⚙️ Configurable: Configuración flexible para diferentes entornos
• 🛡️ Listo para producción: Modos de seguridad estrictos para entornos de producción
• ⚡ Implementación profesional: Instrumentación, temporización y manejo de errores integrados

Configuración

El instalador crea una configuración predeterminada en config/initializers/rails_active_mcp.rb. Los valores predeterminados funcionan de inmediato, pero puedes personalizar el comportamiento:

RailsActiveMcp.configure do |config|
  # Safety and execution
  config.safe_mode = true              # Block dangerous operations
  config.command_timeout = 30          # Seconds before timeout
  config.max_results = 100             # Limit query results
  config.allowed_models = []           # Empty = all models allowed
  config.custom_safety_patterns = []   # Additional patterns to block

  # Logging
  config.enable_logging = true
  config.log_level = :info             # :debug, :info, :warn, :error
  config.log_executions = false        # Log all code executions
  config.audit_file = nil              # Path to audit log file

  # Environment presets (call instead of setting individually)
  # config.production_mode!
  # config.development_mode!
  # config.test_mode!
end

Uso

Cliente MCP (recomendado)

Una vez conectado (consulta Inicio rápido), tu cliente MCP ejecuta el servidor automáticamente. El servidor carga tu aplicación Rails, inicializa los modelos y proporciona acceso seguro a tu entorno Rails mediante transporte STDIO.

Uso directo

También puedes usar la gema directamente en Ruby:

# Execute code safely
result = RailsActiveMcp.execute("User.count")

# Check if code is safe
RailsActiveMcp.safe?("User.delete_all") # => false

Ejecutar el servidor manualmente

Si necesitas ejecutar el servidor directamente (por ejemplo, para depurar):

bundle exec rails-active-mcp-server

# With debug logging
RAILS_MCP_DEBUG=1 bundle exec rails-active-mcp-server

Tareas Rake

La gema proporciona varias tareas rake para diagnóstico y pruebas:

# Show status and diagnostics
rails rails_active_mcp:status

# Validate configuration
rails rails_active_mcp:validate_config

# Test MCP tools are working
rails rails_active_mcp:test_tools

# Check if code is safe
rails rails_active_mcp:check_safety['User.delete_all']

# Execute code with safety checks
rails rails_active_mcp:execute['User.count']

# Print Claude Desktop configuration
rails rails_active_mcp:install_claude_config

# Run performance benchmarks
rails rails_active_mcp:benchmark

Herramientas MCP disponibles

El servidor Rails Active MCP proporciona cuatro potentes herramientas que aparecen automáticamente en cualquier cliente MCP conectado:

1. console_execute

Ejecuta código Ruby con comprobaciones de seguridad y protección de tiempo de espera:

• Propósito: Ejecutar comandos de consola de Rails de forma segura
• Seguridad: Detección integrada de operaciones peligrosas
• Tiempo de espera: Tiempo de ejecución configurable
• Registro: Todas las ejecuciones se registran para auditoría

Ejemplo de prompt:

"Ejecuta User.where(active: true).count"

2. model_info

Obtén información detallada sobre los modelos de Rails:

• Información de esquema: Tipos de columna, restricciones, índices
• Asociaciones: Relaciones has_many, belongs_to, has_one
• Validaciones: Todas las validaciones y reglas del modelo
• Métodos: Métodos de instancia y de clase disponibles

Ejemplo de prompt:

"Muéstrame la estructura del modelo User"

3. safe_query

Ejecuta consultas seguras y de solo lectura a la base de datos:

• Solo lectura: Solo se permiten operaciones SELECT
• Ejecución segura: Análisis automático de consultas
• Limitación de resultados: Evita volcados de datos grandes
• Contexto del modelo: Funciona dentro de las definiciones de tus modelos

Ejemplo de prompt:

"Obtén los 10 pedidos más recientes" "Cuenta los usuarios activos"

Puedes pasar un hash where opcional para filtrar registros antes de invocar el método. Por ejemplo, safe_query(model: "User", method: "count", where: { active: true }) ejecuta User.where(active: true).count. Lo mismo aplica para sum, average, minimum, maximum, pluck y exists?.

4. dry_run

Analiza código Ruby para verificar su seguridad sin ejecutarlo:

• Evaluación de riesgo: Clasifica el código por nivel de peligro
• Análisis de seguridad: Identifica problemas potenciales
• Recomendaciones: Sugiere alternativas más seguras
• Cero ejecución: Nunca ejecuta el código real

Ejemplo de prompt:

"Analiza este código para verificar su seguridad: User.delete_all"

Características de seguridad

Detección automática de operaciones peligrosas

La gema detecta y bloquea automáticamente:

• Eliminaciones masivas (delete_all, destroy_all)
• Comandos del sistema (system, exec, backticks)
• Operaciones de archivos (File.delete, FileUtils)
• Ejecución de SQL crudo
• Evaluación de código (eval, send)
• Manipulación de procesos (exit, fork)

Niveles de seguridad

• Crítico: Nunca permitido (comandos del sistema, eliminación de archivos)
• Alto: Bloqueado en modo seguro (eliminaciones masivas, eval)
• Medio: Registrado pero permitido (SQL crudo, update_all)
• Bajo: Generalmente seguro (acceso al entorno, require)

Modo de solo lectura

La gema puede detectar operaciones de solo lectura y proporcionar seguridad adicional:

# These are considered safe read-only operations
User.find(1)
User.where(active: true).count
Post.includes(:comments).limit(10)

Arquitectura

Construida sobre el SDK oficial de MCP para Ruby

Rails Active MCP usa el SDK oficial de MCP para Ruby (gema mcp) para:

• Manejo profesional del protocolo: Implementación robusta de JSON-RPC 2.0
• Instrumentación integrada: Informes automáticos de tiempo y errores
• A prueba de futuro: Actualizaciones automáticas a medida que evoluciona la especificación MCP
• Cumplimiento de estándares: Compatibilidad total con el protocolo MCP

Implementación del servidor

El servidor está implementado en lib/rails_active_mcp/sdk/server.rb y proporciona:

• Transporte STDIO: Compatible con todos los principales clientes MCP
• Registro de herramientas: Descubrimiento automático de herramientas disponibles
• Manejo de errores: Informes y recuperación completos de errores
• Integración con Rails: Integración profunda con aplicaciones Rails

Arquitectura de herramientas

Cada herramienta se implementa como una clase separada en lib/rails_active_mcp/sdk/tools/:

• ConsoleExecuteTool: Ejecución segura de código
• ModelInfoTool: Introspección de modelos
• SafeQueryTool: Acceso de solo lectura a la base de datos
• DryRunTool: Análisis de seguridad de código

Manejo de errores

La gema proporciona tipos de error específicos:

• RailsActiveMcp::SafetyError: El código no pasó las comprobaciones de seguridad
• RailsActiveMcp::TimeoutError: Tiempo de espera agotado durante la ejecución
• RailsActiveMcp::ExecutionError: Fallo general de ejecución

Todos los errores se informan correctamente a través del protocolo MCP con mensajes detallados.

Desarrollo y pruebas

# Run tests
bundle exec rspec

# Test MCP server protocol compliance
./bin/test-mcp-output

Contribuciones

1. Haz un fork
2. Crea tu rama de características (git checkout -b my-new-feature)
3. Realiza tus cambios (git commit -am 'Add some feature')
4. Sube la rama (git push origin my-new-feature)
5. Crea una nueva solicitud de extracción

Licencia

La gema está disponible como código abierto bajo la Licencia MIT.