rails-ai-context

为你的 AI 编码助手提供关于 Rails 应用的真实信息

:star: 如果这个 gem 帮你省下了一次修正循环，请在 GitHub 上给它加星！

为什么 • 功能 • 快速开始 • 用法 • 工具 • 配置 • 文档

rails-ai-context 是一个 Ruby gem，它把你的 Rails 应用变成 AI 编码助手的真实信息来源。助手不再根据训练数据猜测你的 schema、关联、路由和约定，而是直接询问你的应用：通过 MCP 提供或从 CLI 运行的 45 个只读工具，以及为 Claude Code、Cursor、GitHub Copilot、OpenCode 和 Codex CLI 生成的上下文文件。

[!TIP] 如果你不想，就不需要往 Gemfile 里加任何东西。gem install rails-ai-context，然后在任何 Rails 应用内运行 rails-ai-context init。它也能在无法启动的应用上工作：传入 --no-boot，每个工具都会从源文件中回答。

为什么

你见过你的助手做过这些事：

• 为一个已经存在的列写迁移。

• 当关联是 user.articles 时调用 user.posts。

• 在基于 fixture 的测试套件中用 FactoryBot 搭建测试。

• 漏掉从父控制器继承的 before_action，然后奇怪为什么认证失败。

• 添加你已经有的 gem，或者调用你没有的 gem 的 API。

• 发明一个代码库中不存在的方法。

你发现它、修复它、重新提示，然后旁边的东西又坏了。token 很便宜；真正浪费你一下午的是修正循环。这个 gem 从源头消除了猜测。

Related MCP server: Synapse

功能

• 45 个只读工具，涵盖 schema、模型、控制器、路由、视图、Stimulus、Turbo、jobs、services、mailers、i18n、gems、配置、测试、安全、性能等。每个答案都来自你的应用。

• Prism AST 解析用于模型内省。每个结果都带有 [VERIFIED] 或 [INFERRED]，让助手知道什么是真实信息，什么需要运行时检查。

• 三种接入方式：通过 stdio 的 MCP、通过 HTTP 挂载在 Rails 应用内的 MCP，或任何终端中的纯 CLI。

• 生成的上下文文件，适用于 Claude Code、Cursor、GitHub Copilot、OpenCode 和 Codex CLI，并带有每个工具在项目打开时自动检测的 MCP 配置。

• 实时资源：rails:// 和 rails-ai-context:// URI，每次读取时都会重新内省。

• 反幻觉规则，随每个生成的上下文文件提供，默认开启。

• 静态层：当应用无法启动时，工具从 config/routes.rb、db/schema.rb、迁移和源文件中回答，并明确说明。

• 适用于真实应用形态：packwerk packs、仓库内引擎、多数据库 schema 转储、Mongoid、仅 API 应用。

• 自定义工具：在内置工具旁边注册你自己的 MCP::Tool 类，并使用捆绑的 TestHelper 测试它们。

快速开始

要求

• Ruby 3.1 或更高

• Rails 7.0 或更高

• 可选：brakeman 用于 security_scan，listen 用于 watch，ripgrep 用于更快的 search_code

在 Gemfile 中安装

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

生成器会询问你使用哪些 AI 工具以及是否需要 MCP 或 CLI 模式，然后写入上下文文件、每个工具的 MCP 配置，以及 config/initializers/rails_ai_context.rb。重新运行是安全的；它会保留你已有的内容，并添加缺失的部分。

独立安装

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

无需修改 Gemfile。配置位于 .rails-ai-context.yml。支持 rbenv、rvm、asdf、mise、chruby 和系统 Ruby。参见 独立安装。

检查是否正常工作

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

然后在你的 AI 工具中打开项目。它写入的 MCP 配置会在打开时被拾取，助手开始调用 rails_get_model_details 而不是猜测。

[!NOTE] 上面的 CLI 命令是给你用的。当 MCP 连接时，助手会自己调用相同的工具；你永远不需要输入它们。

用法

通过 stdio 的 MCP

默认方式。每个 AI 工具都有自己的配置文件（.mcp.json、.cursor/mcp.json、.vscode/mcp.json、opencode.json、.codex/config.toml），指向：

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

通过 HTTP 的 MCP

将服务器挂载到你的应用内部。它继承你的路由、认证和中间件，不需要第二个进程。

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

将客户端指向 http://localhost:3000/mcp。还有一个独立的 HTTP 进程：rails-ai-context serve --transport http --port 6029。

[!WARNING] 每个打开 SSE 通道的已连接客户端都会在连接生命周期内占用一个服务器线程。开发时没问题；如果有多个客户端共享应用，请提高 Puma 的线程数，或使用独立的 HTTP 进程。

CLI

同样的 45 个工具，无需服务器，任何终端都可以。

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

工具名称可以宽松解析：schema、get_schema 和 rails_get_schema 都可以。大多数工具接受 detail=summary|standard|full。

命令

应用读取命令共享的标志：--app-path PATH 用于指定另一个目录，--environment ENV 用于设置 RAILS_ENV，--no-boot 用于跳过启动尝试并从源码回答。完整列表见 CLI 参考。

工具

每个工具都是只读的，并从你的应用回答。

第一天值得了解的几项：

• search_code 配合 match_type=trace 一次调用即可返回定义、源码、按类型分组的全部调用方以及测试。这相当于替代了 4 到 5 次文件读取。

• get_controllers 返回动作源码，包含继承的过滤器、强参数和渲染映射。

• get_model_details 从 AST 返回关联、校验、作用域、枚举和宏，每一项都标记为 [VERIFIED] 或 [INFERRED]。

• query 以超时、行数限制和列脱敏方式运行只读 SQL。read_logs 在敏感数据离开进程之前对其进行脱敏。

全部 45 个工具的参数见工具参考；实际示例见配方。

实时资源

MCP 客户端还可以将结构化数据作为资源读取。模板会在每次请求时重新内省：

另有 9 个静态资源：rails://schema、routes、conventions、gems、controllers、config、tests、migrations、engines。

反幻觉规则

每个生成的上下文文件（CLAUDE.md、.cursor/rules/、.github/instructions/、AGENTS.md）都附带六条规则，助手在编写代码前会先阅读这些规则：

1. 先验证再编写。绝不引用本轮工具调用未确认的列、关联、路由、辅助方法、方法、类、局部模板或 gem。

2. 用 [ASSUMPTION] 标记每一个假设。“我需要先检查 X”就是一个好的回答。

3. 训练数据描述的是普通的 Rails。这个应用并不普通。当某件事感觉明显是标准做法时，仍然要查询。

4. 每次编辑前检查继承链：继承的过滤器、concerns、includes、STI 父类。

5. 空的工具输出也是信息。“找到 0 个调用方”意味着需要调查，而不是继续。

6. 过期的上下文会误导。写入后要重新查询。

默认开启。如果你更喜欢自己的规则，可以用 config.anti_hallucination_rules = false 关闭。

当应用无法启动时

rails-ai-context 会尝试完整启动以进行实时反射。当启动失败（缺少 ENV 变量、服务不可达、初始化器损坏）时，应用读取命令会回退到静态层而不是直接失败：路由来自 config/routes.rb，模式来自 db/schema.rb、db/structure.sql 或迁移，模型和控制器来自其源文件。每个响应都会带有一个横幅说明降级情况，静态数据标记为 [STATIC]，需要已启动应用的部分会报告 [UNAVAILABLE] 并附上原因。

--no-boot 直接跳过启动尝试，速度快且不受启动时副作用影响。doctor 仍然需要可启动的应用；诊断启动问题正是它的职责。

代码可以在常规布局、packwerk 包（packs/*/app/*）、仓库内引擎（engines/*/app/*）以及 .rails-ai-context.yml 中的任何 extra_app_paths 中找到。多数据库模式转储（db/queue_schema.rb 等）会显示在 Secondary databases 部分下。Mongoid 应用会收到 [UNAVAILABLE] 模式信号以及静态模型数据，而不是空表；仅 API 应用会从视图和前端工具收到“不适用”，而不是静默空白。详见兼容性。

配置

# 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

独立安装使用 .rails-ai-context.yml 中的相同键。所有选项及其默认值见配置。

自定义工具

在内置工具旁边注册你自己的工具：

# 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"]

使用捆绑的辅助工具（RSpec 或 Minitest）测试它们：

include RailsAiContext::TestHelper

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

参见自定义工具。

可观测性

每次 MCP 调用都会触发一个 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

工作原理

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

内部机制、内省器列表和 AST 引擎见架构和内省器。

文档

由一位拥有 10 年以上生产环境经验的 Rails 开发者构建。如果它为你节省了时间，请考虑赞助该项目。