Rails AI Context — Zero-config MCP server for Rails apps

rails-ai-context 让你的 Rails 应用成为 AI 编码助手的事实来源。助手不再根据训练数据猜测你的架构、关联、路由和约定，而是直接询问你的应用：通过 MCP 或命令行使用 35 个只读工具，并提供为 Claude Code、Cursor、GitHub Copilot、OpenCode 和 Codex CLI 编写的上下文文件。

一键粘贴安装

在 Rails 应用根目录打开你的 AI 工具，然后粘贴以下内容。它会安装 gem、配置当前使用的 AI 工具、检查结果，并告诉你还剩下哪一步。

Install the rails-ai-context gem in this Rails app so you can read its schema, models, routes and code through its tools instead of guessing.

1. Run `ruby -v` and `bundle exec rails -v`. rails-ai-context needs Ruby 3.1+ and Rails 7.0+. If either is older, stop and tell me.
2. Pick TOOL, the key for the AI tool you are: claude (Claude Code), cursor (Cursor), copilot (GitHub Copilot in VS Code), opencode (OpenCode), codex (Codex CLI). If you are another AI tool, stop and tell me to use the "Another MCP client" prompt instead.
3. Run `bundle add rails-ai-context --group development --version '>= 5.35.0'`. If the Gemfile already lists it, run `bundle update rails-ai-context --conservative` instead. Then run `bundle exec rails-ai-context version`: it must print 5.35.0 or newer, the first version with the flags used below. If it is older, the Gemfile pins it: change its rails-ai-context line to `gem "rails-ai-context", ">= 5.35.0", group: :development` and run `bundle update rails-ai-context --conservative`. If Bundler refuses (a frozen or deployment bundle), run `gem install rails-ai-context -v '>= 5.35.0'` instead and use `rails-ai-context init --tools TOOL --defaults` in step 4.
4. Run `bundle exec rails generate rails_ai_context:install --tools TOOL --defaults`. If it fails because the app can't boot, run `bundle exec rails-ai-context init --tools TOOL --defaults` instead; that one reads the source files when the app won't start.
5. Run `bundle exec rails-ai-context tool onboard` (or `rails-ai-context tool onboard` if you used gem install) and check it describes this app.
6. Tell me which files changed, then the "Next step" lines the install printed for TOOL, word for word. I have to do that step before your rails-ai-context MCP tools appear.

另有想法？这里有相应的提示词

已经安装？这里有用于更改设置、切换安装类型、升级、修复问题、卸载和开始使用的提示词。每条提示词都会通过标志指定每项安装选项，因此不会在 AI 工具的终端中卡在提问环节。

bundle add rails-ai-context --group development
bin/rails generate rails_ai_context:install            # asks which AI tools and what to write
bin/rails generate rails_ai_context:install --tools claude --defaults   # asks nothing

gem install rails-ai-context
rails-ai-context init                                  # or: rails-ai-context init --tools claude --defaults

claude plugin install rails-ai-context --marketplace crisnahine/rails-ai-context --scope project

然后在 AI 工具中完成一步

每种 AI 工具都会要求你先确认，才启用新项目的 MCP 服务。安装程序会打印你所选工具对应的操作步骤：

接着询问一些只有你的应用才知道的问题，例如 “users 表有哪些列？”，然后观察它调用 rails_get_schema，而不是凭空猜测。

为什么需要

你可能见过助手做出这些事：

• 为已存在的列编写迁移。
• 在关联实际是 user.articles 时调用 user.posts。
• 在基于 fixture 的测试套件中用 FactoryBot 搭建测试。
• 漏掉从父控制器继承的 before_action，然后纳闷为什么身份验证失败。
• 添加一个你已经有的 gem，或者调用一个你根本没安装的 gem 的 API。
• 凭空编造代码库中不存在的方法。

你发现问题、修复、再次提示，然后旁边的东西又坏了。Token 不贵，但反复修正会耗掉你一下午。这个 gem 从源头消除了猜测。

你将获得

选择设置方式

随时使用更改设置提示词切换，或使用新的标志重新运行安装并添加 --prune。

工作原理

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\n35 tools · 5 templates · 9 resources"]
    B --> D["CLI\nrake / Thor\nsame 35 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

内部实现详见架构和内省器。

工具

所有工具均为只读，答案都来自你的应用。

第一天值得了解的 4 个工具：

• search_code 配合 match_type=trace：在一次调用中返回定义、源代码、按文件分组并标注类型的所有调用方，以及测试。这可替代 4 到 5 次文件读取。
• get_controllers：返回操作源代码，以及继承的过滤器、强参数和渲染映射。
• get_model_details：从 AST 中返回关联、验证、作用域、枚举和宏，并标记为 [VERIFIED] 或 [INFERRED]。
• query：执行只读 SQL，并设置超时、行数限制和列脱敏。

通过 MCP 使用时，每个名称都带有 rails_ 前缀（rails_get_schema）。从 CLI 使用时，短名称即可：schema、get_schema 和 rails_get_schema 都能解析。全部 35 个工具的参数见工具参考；操作指南中提供了实际示例。

三种连接方式

MCP over stdio 是默认方式。每个 AI 工具都有自己的配置文件（.mcp.json、.cursor/mcp.json、.vscode/mcp.json、opencode.json、.codex/config.toml），用于启动 bundle exec rails-ai-context serve，也可以独立运行 rails-ai-context serve。在 Windows 上，每个配置都会通过 cmd /c 启动，因为 gem 的可执行文件在 Windows 上是批处理文件。

MCP over HTTP 会在应用内挂载服务，使其继承应用的路由、身份验证和中间件：

# config/routes.rb
mount RailsAiContext::Engine, at: "/mcp" if defined?(RailsAiContext::Engine)

if 可确保在未安装 gem 时（例如 Bundler 跳过开发组的生产环境）仍能加载路由文件。在开发和测试环境之外，除非设置 config.allow_http_in_production = true，否则该端点会拒绝所有请求并返回 403，因为它本身没有身份验证（参见 Security）。此外，还可以启动独立的 HTTP 进程：rails-ai-context serve --transport http --port 6029。

CLI 无需服务即可在任何终端中运行相同的 35 个工具：

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

大约一半的工具接受 detail=summary|standard|full。

应用无法启动时

读取应用的命令会尝试完整启动应用，以便进行实时反射。如果启动失败（缺少 ENV 变量、服务无法访问、初始化程序损坏），它们会回退到静态层级，而不会直接退出：从 config/routes.rb 读取路由，从 db/schema.rb、db/structure.sql 或迁移文件读取架构，并从源代码读取模型和控制器。每条响应都会显示说明降级情况的横幅，静态数据会标记为 [STATIC]，需要应用已启动才能提供的部分会标记为 [UNAVAILABLE] 并说明原因。--no-boot 会直接跳过启动尝试。doctor 仍需要应用能够启动，因为诊断启动问题正是它的用途。

代码会从常规目录结构、packwerk packs（packs/*/app/*）、仓库内的引擎（engines/*/app/*）以及 .rails-ai-context.yml 中的任何 extra_app_paths 查找。详情参见 Compatibility。

命令

该可执行文件会像 bin/rails 一样查找应用，因此可从任何子目录运行。应用读取命令共用的标志：使用 --app-path PATH 指定其他目录，使用 --environment ENV 设置 RAILS_ENV，使用 --no-boot 从源代码生成响应。完整列表见 CLI reference。

说明

这些命令供你使用。连接 MCP 后，助手会自行调用相同的工具。

配置

# config/initializers/rails_ai_context.rb
if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
  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"
  input_schema(properties: { period: { type: "string" } })

  def self.call(period: "week", server_context: nil)
    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"]

include RailsAiContext::TestHelper

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

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

卸载

bundle exec rails-ai-context uninstall && bundle remove rails-ai-context   # in the Gemfile
rails-ai-context uninstall                                                 # standalone

它会移除上下文文件、MCP 条目、配置、.gitignore 中对应的行以及 pre-commit 钩子，并保留你编写的内容：你在 CLAUDE.md 中添加的行、MCP 配置中的其他服务，以及你编辑过的钩子。也可以粘贴卸载提示词。

文档