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 ツールをセットアップして、結果を確認し、残っている手順を 1 つだけ案内します。

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 ツールで1つ操作します

どの AI ツールでも、新しいプロジェクトの MCP サーバーは、許可するまで保留されます。インストール時に、選択した各ツールで必要な手順が表示されます：

次に、「usersテーブルにはどのようなカラムがありますか？」 のように、アプリについてしか分からないことを質問してみてください。推測する代わりに rails_get_schema が呼び出される様子を確認できます。

理由

アシスタントが次のようなことをするのを見たことがあるでしょう。

• すでに存在するカラムのマイグレーションを作成する。
• アソシエーションが user.articles なのに、user.posts を呼び出す。
• フィクスチャベースのテストスイートで、FactoryBot を使ったテストをひな形から作成する。
• 親コントローラーから継承した before_action を見落とし、認証に失敗する理由がわからなくなる。
• すでにある gem を追加したり、使っていない gem の API を呼び出したりする。
• コードベースに存在しないメソッドをでっち上げる。

間違いに気づいて修正し、再度プロンプトを入力すると、今度はその近くの別の箇所が壊れます。トークンは安価でも、修正のループで午後がつぶれてしまいます。この 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つのツール：

• match_type=trace を指定した search_code は、定義、ソース、ファイルごとにグループ化され種類がラベル付けされたすべての呼び出し元、テストを1回の呼び出しで返します。これにより、ファイルを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個すべてのパラメーターはツールリファレンスに、実際の使用例はレシピに記載されています。

接続方法は 3 つあります

stdio 経由の MCPがデフォルトです。各 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 では、gem の実行ファイルがバッチファイルであるため、それぞれcmd /c経由で起動します。

HTTP 経由の MCPは、サーバーをアプリ内にマウントし、アプリのルーティング、認証、ミドルウェアを引き継ぎます。

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

ifを使うことで、gem がインストールされていない環境（本番環境など）でもルートファイルを読み込めます。本番環境では、Bundler が development グループをスキップします。開発環境とテスト環境以外では、独自の認証機能がないため、config.allow_http_in_production = trueを設定しない限り、エンドポイントはすべてのリクエストを403で拒否します（セキュリティを参照）。単独の 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/*/app/*）、リポジトリ内のエンジン（engines/*/app/*）、および.rails-ai-context.ymlのextra_app_pathsから検索されます。詳しくは互換性を参照してください。

コマンド

このバイナリはbin/railsと同じ方法でアプリを検出するため、どのサブディレクトリからでも実行できます。アプリ読み取りコマンドで共通のフラグを指定できます。別のディレクトリを対象にするには--app-path PATH、RAILS_ENVを設定するには--environment ENV、ソースから応答するには--no-bootを使います。すべてのフラグについてはCLI リファレンスを参照してください。

メモ

これらのコマンドはユーザー向けです。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 の該当行、プリコミットフックを削除し、作成した内容は保持します。たとえば、CLAUDE.md に追加した行、MCP 設定内の他のサーバー、編集したフックはそのまま残ります。または、アンインストール用プロンプトを貼り付けてください。

ドキュメント