rails-ai-context

Da a tu asistente de codificación con IA información real sobre tu aplicación Rails

:star: Si esta gema te ahorra un bucle de corrección, ¡dale una estrella en GitHub!

Por qué • Características • Primeros pasos • Uso • Herramientas • Configuración • Documentación

rails-ai-context es una gema de Ruby que convierte tu aplicación Rails en la fuente de verdad para los asistentes de codificación con IA. En lugar de adivinar tu esquema, asociaciones, rutas y convenciones a partir de los datos de entrenamiento, el asistente pregunta a tu aplicación: 45 herramientas de solo lectura servidas a través de MCP o ejecutadas desde la CLI, además de archivos de contexto generados para Claude Code, Cursor, GitHub Copilot, OpenCode y Codex CLI.

[!TIP] No tienes que añadir nada a tu Gemfile si no quieres. Ejecuta gem install rails-ai-context y luego rails-ai-context init dentro de cualquier aplicación Rails. También funciona en una aplicación que no arranca: pasa --no-boot y todas las herramientas responden desde los archivos fuente.

Por qué

Has visto a tu asistente hacer esto:

• Escribir una migración para una columna que ya existe.

• Llamar a user.posts cuando la asociación es user.articles.

• Generar pruebas con FactoryBot en una suite basada en fixtures.

• Perderse un before_action heredado de un controlador padre y luego preguntarse por qué falla la autenticación.

• Añadir una gema que ya tienes, o llamar a una API de una que no tienes.

• Inventar un método que no está en el código.

Lo detectas, lo arreglas, vuelves a preguntar y algo cercano se rompe. Los tokens son baratos; el bucle de corrección es lo que te cuesta la tarde. Esta gema elimina la adivinanza desde el origen.

Related MCP server: Synapse

Características

• 45 herramientas de solo lectura para esquema, modelos, controladores, rutas, vistas, Stimulus, Turbo, trabajos, servicios, mailers, i18n, gemas, configuración, pruebas, seguridad, rendimiento y más. Cada respuesta proviene de tu aplicación.

• Análisis de AST con Prism para la introspección de modelos. Cada resultado incluye [VERIFIED] o [INFERRED] para que el asistente sepa qué es información real y qué necesita una comprobación en tiempo de ejecución.

• Tres formas de acceso: MCP por stdio, MCP montado dentro de tu aplicación Rails por HTTP, o CLI directa en cualquier terminal.

• Archivos de contexto generados para Claude Code, Cursor, GitHub Copilot, OpenCode y Codex CLI, con la configuración de MCP que cada herramienta detecta automáticamente al abrir el proyecto.

• Recursos en vivo: URIs rails:// y rails-ai-context:// que se inspeccionan de nuevo en cada lectura.

• Reglas contra la alucinación incluidas en todos los archivos de contexto generados, activadas por defecto.

• Nivel estático: cuando la aplicación no puede arrancar, las herramientas responden desde config/routes.rb, db/schema.rb, las migraciones y los archivos fuente, y lo indican.

• Funciona con formas reales de aplicación: packs de packwerk, motores en el repositorio, volcados de esquema de múltiples bases de datos, Mongoid, aplicaciones solo API.

• Herramientas personalizadas: registra tus propias clases MCP::Tool junto a las integradas y pruébalas con el TestHelper incluido.

Primeros pasos

Requisitos

• Ruby 3.1 o más reciente

• Rails 7.0 o más reciente

• Opcional: brakeman para security_scan, listen para watch, ripgrep para un search_code más rápido

Instalación en el Gemfile

bundle add rails-ai-context --group development
rails generate rails_ai_context:install

El generador pregunta qué herramientas de IA utilizas y si quieres el modo MCP o CLI, y luego escribe los archivos de contexto, la configuración de MCP para cada herramienta y config/initializers/rails_ai_context.rb. Volver a ejecutarlo es seguro: conserva lo que ya tienes y añade lo que falta.

Instalación independiente

gem install rails-ai-context
cd your-rails-app
rails-ai-context init
rails-ai-context serve

Sin cambios en el Gemfile. La configuración vive en .rails-ai-context.yml. Funciona con rbenv, rvm, asdf, mise, chruby y el Ruby del sistema. Consulta Instalación independiente.

Comprueba que funciona

rails ai:doctor                                  # in-Gemfile: readiness score + diagnostics
rails-ai-context doctor                          # standalone

rails 'ai:tool[schema]' table=users
rails 'ai:tool[model_details]' model=User
rails 'ai:tool[search_code]' pattern=publishable? match_type=trace

A continuación, abre el proyecto en tu herramienta de IA. La configuración de MCP que escribió se detecta al abrir, y el asistente empieza a llamar a rails_get_model_details en lugar de adivinar.

[!NOTE] Los comandos de CLI anteriores son para ti. Cuando MCP está conectado, el asistente llama a las mismas herramientas por sí mismo; nunca las escribes tú.

Uso

MCP por stdio

El modo predeterminado. Cada herramienta de IA recibe su propio archivo de configuración (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, opencode.json, .codex/config.toml) que apunta a:

rails ai:serve             # in-Gemfile
rails-ai-context serve     # standalone

MCP por HTTP

Monta el servidor dentro de tu aplicación. Hereda tu enrutamiento, autenticación y middleware, y no necesita un segundo proceso.

# config/routes.rb
mount RailsAiContext::Engine, at: "/mcp"

Apunta el cliente a http://localhost:3000/mcp. También hay un proceso HTTP independiente: rails-ai-context serve --transport http --port 6029.

[!WARNING] Cada cliente conectado que abre el canal SSE mantiene un hilo del servidor durante toda la conexión. Está bien para desarrollo; aumenta el número de hilos de Puma o usa el proceso HTTP independiente si varios clientes comparten la aplicación.

CLI

Las mismas 45 herramientas, sin servidor, en cualquier terminal.

rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
rails-ai-context tool schema --table users --detail full

Los nombres de las herramientas se resuelven de forma flexible: schema, get_schema y rails_get_schema funcionan todas. La mayoría de las herramientas aceptan detail=summary|standard|full.

Comandos

Banderas compartidas por los comandos que leen la aplicación: --app-path PATH para apuntar a otro directorio, --environment ENV para establecer RAILS_ENV, y --no-boot para omitir el intento de arranque y responder desde el código fuente. Lista completa en la referencia de CLI.

Herramientas

Cada herramienta es de solo lectura y responde desde tu aplicación.

Algunas que conviene conocer desde el primer día:

• search_code con match_type=trace devuelve la definición, el código fuente, todos los llamadores agrupados por tipo y las pruebas, en una sola llamada. Eso sustituye de 4 a 5 lecturas de archivos.

• get_controllers devuelve el código fuente de la acción con los filtros heredados, los strong params y el mapa de renderizado.

• get_model_details devuelve asociaciones, validaciones, scopes, enums y macros del AST, cada uno etiquetado como [VERIFIED] o [INFERRED].

• query ejecuta SQL de solo lectura con un tiempo de espera, un límite de filas y redacción de columnas. read_logs redacta los datos sensibles antes de que salgan del proceso.

Los parámetros de los 45 están en la referencia de herramientas; ejemplos resueltos en recetas.

Recursos en vivo

Los clientes MCP también pueden leer datos estructurados como recursos. Las plantillas se inspeccionan de nuevo en cada petición:

Además, 9 recursos estáticos: rails://schema, routes, conventions, gems, controllers, config, tests, migrations, engines.

Reglas anti-alucinación

Cada archivo de contexto generado (CLAUDE.md, .cursor/rules/, .github/instructions/, AGENTS.md) incluye seis reglas que el asistente lee antes de escribir código:

1. Verifica antes de escribir. Nunca hagas referencia a una columna, asociación, ruta, helper, método, clase, partial o gema que una llamada a herramienta en este turno no haya confirmado.

2. Marca cada suposición con [ASSUMPTION]. «Necesitaría comprobar X primero» es una buena respuesta.

3. Los datos de entrenamiento describen un Rails promedio. Esta app no es promedio. Cuando algo parezca obviamente estándar, consulta de todos modos.

4. Comprueba la cadena de herencia antes de cada edición: filtros heredados, concerns, includes, padres STI.

5. La salida vacía de una herramienta es información. «0 llamadores encontrados» significa investigar, no continuar.

6. El contexto obsoleto miente. Vuelve a consultar después de escribir.

Activadas por defecto. Desactívalas con config.anti_hallucination_rules = false si prefieres las tuyas propias.

Cuando la app no puede arrancar

rails-ai-context intenta un arranque completo para la reflexión en vivo. Cuando el arranque falla (variables de entorno ausentes, un servicio inaccesible, un initializer roto), los comandos de lectura de la app recurren al nivel estático en lugar de fallar: rutas desde config/routes.rb, esquema desde db/schema.rb, db/structure.sql o migraciones, modelos y controladores desde sus archivos fuente. Cada respuesta lleva un banner que indica la degradación, los datos estáticos se etiquetan como [STATIC] y las secciones que necesitan una app arrancada informan de [UNAVAILABLE] con el motivo.

--no-boot omite el intento por completo, lo que es rápido e inmune a los efectos secundarios del arranque. doctor sigue necesitando una app arrancable; diagnosticar el arranque es su trabajo.

El código se encuentra en el diseño convencional, en packs de packwerk (packs/*/app/*), en engines dentro del repositorio (engines/*/app/*) y en cualquier extra_app_paths de .rails-ai-context.yml. Los volcados de esquema de múltiples bases de datos (db/queue_schema.rb y similares) aparecen en una sección Secondary databases. Las apps Mongoid reciben una señal de esquema [UNAVAILABLE] más datos de modelo estáticos en lugar de una tabla vacía, y las apps solo API reciben «no aplicable» de las herramientas de vistas y frontend en lugar de un espacio en blanco silencioso. Detalles en Compatibilidad.

Configuración

# config/initializers/rails_ai_context.rb
if defined?(RailsAiContext)
  RailsAiContext.configure do |config|
    config.ai_tools  = %i[claude cursor]   # which AI tools to generate for
    config.tool_mode = :mcp                # :mcp (default) or :cli
    config.preset    = :full               # :full (40 introspectors) or :standard (17)
  end
end

Las instalaciones independientes usan las mismas claves en .rails-ai-context.yml. Todas las opciones con sus valores por defecto están en Configuración.

Herramientas personalizadas

Registra tus propias herramientas junto a las integradas:

# app/mcp_tools/rails_get_business_metrics.rb
class RailsGetBusinessMetrics < MCP::Tool
  tool_name "rails_get_business_metrics"
  description "Key business metrics for this app"

  def call(period: "week")
    MCP::Tool::Response.new([{ type: "text", text: "Users this #{period}: #{User.recent.count}" }])
  end
end

# config/initializers/rails_ai_context.rb
config.custom_tools = ["RailsGetBusinessMetrics"]

Pruébalas con el helper incluido (RSpec o Minitest):

include RailsAiContext::TestHelper

response = execute_tool("business_metrics", period: "month")
assert_tool_response_includes(response, "Users")

Consulta Herramientas personalizadas.

Observabilidad

Cada llamada MCP dispara un evento ActiveSupport::Notifications:

ActiveSupport::Notifications.subscribe("rails_ai_context.tools.call") do |event|
  ms = (event.payload[:duration].to_f * 1000).round
  Rails.logger.info "[MCP] #{event.payload[:tool_name]} #{ms}ms"
end

Cómo funciona

graph TD
    A["Your Rails app\nmodels + schema + routes + controllers + views + jobs"] -->|"40 introspectors"| B
    B["rails-ai-context\nPrism AST · cached · confidence-tagged\nstatic tier when the app can't boot"]
    B --> C["MCP server\nstdio / HTTP\n45 tools · 5 templates · 9 resources"]
    B --> D["CLI\nrake / Thor\nsame 45 tools"]
    B --> E["Context files\nCLAUDE.md · .cursor/rules/ · .github/instructions/ · AGENTS.md"]

    style A fill:#4a9eff,stroke:#2d7ad4,color:#fff
    style B fill:#2d2d2d,stroke:#555,color:#fff
    style C fill:#0984e3,stroke:#0770c2,color:#fff
    style D fill:#00cec9,stroke:#00b5b0,color:#fff
    style E fill:#a29bfe,stroke:#8c83f0,color:#fff

Los detalles internos, la lista de introspectores y el motor AST están en Arquitectura e Introspectores.

Documentación

Creado por un desarrollador de Rails con más de 10 años en producción. Si te ahorra tiempo, considera patrocinar el proyecto.