Rails AI 桥接工具

Requirements

• Ruby >= 3.2, Rails >= 7.1
• mcp gem (installed automatically)
• Optional: listen gem for watch mode, ripgrep for fast code search

---

Install profiles

The generator prompts you to pick a profile (or pass --profile to skip the prompt):

```bash

MCP Server Setup

The install generator creates .mcp.json for MCP-capable clients. Claude Code and Cursor can auto-detect it, while Codex can use the generated AGENTS.md plus your local Codex configuration.

This project keeps server.json aligned with GitHub metadata for MCP registry packaging when you choose to publish a release artifact.

To start manually: rails ai:serve

<details> <summary><strong>Claude Desktop setup</strong></summary>

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "rails-ai-bridge": {
      "command": "bundle",
      "args": ["exec", "rails", "ai:serve"],
      "cwd": "/path/to/your/rails/app"
    }
  }
}

<details> <summary><strong>HTTP transport (for remote clients)</strong></summary>

rails ai:serve_http  # Starts at http://127.0.0.1:6029/mcp

Or auto-mount inside your Rails app:

RailsAiBridge.configure do |config|
  config.auto_mount = true
  config.http_mcp_token = "generate-a-long-random-secret" # or ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]
  # Production only: explicit opt-in + token required (see SECURITY.md)
  # config.allow_auto_mount_in_production = true
  config.http_path  = "/mcp"
  # Optional: reject HTTP requests when no Bearer/JWT/static auth is configured (safer beyond localhost)
  # config.mcp.require_http_auth = true
end

Clients must send Authorization: Bearer <token> when a token is configured.

Security note: keep the HTTP transport bound to 127.0.0.1 unless you add your own network and authentication controls. The tools are read-only, but they can still expose sensitive application structure. Generated context and the built-in conventions resource filter secret-bearing config paths, but MCP access should still be treated as internal. In production, rails ai:serve_http and auto_mount require a configured MCP token; auto_mount also requires allow_auto_mount_in_production = true. For operational hardening (tokens, proxies, require_http_auth, stdio threat model), see docs/mcp-security.md and SECURITY.md. </details>

---

Codex Setup

Codex support is centered on AGENTS.md at the repository root.

• Run rails ai:bridge:codex to regenerate AGENTS.md and .codex/README.md.
• Keep AGENTS.md committed so Codex sees project-specific instructions.
• Keep personal preferences in ~/.codex/AGENTS.md; use the repository AGENTS.md for shared guidance.
• When Codex is connected to the generated MCP server, prefer the rails_* tools and start with detail:"summary".

---

Quick start

From RubyGems (once published):

bundle add rails-ai-bridge
rails generate rails_ai_bridge:install

From GitHub (before or alongside RubyGems):

bundle add rails-ai-bridge --github=igmarin/rails-ai-bridge
rails generate rails_ai_bridge:install

Or add to your Gemfile:

gem "rails-ai-bridge", github: "igmarin/rails-ai-bridge"

Then bundle install and run the generator as above.

The install generator creates .mcp.json (MCP auto-discovery), sets up config/initializers/rails_ai_bridge.rb, and interactively guides you through generating your first bridge files.

Configuration

```ruby

config/initializers/rails_ai_bridge.rb

RailsAiBridge.configure do |config| # Presets: :standard (9 introspectors, default) or :full (27). Add opt-in extras as needed. config.preset = :standard

# Cherry-pick on top of a preset # config.introspectors += %i[non_ar_models views turbo auth api database_stats]

# Context mode: :compact (≤150 lines, default) or :full (dump everything) # config.context_mode = :compact

# Exclude models from introspection config.excluded_models += %w[AdminUser InternalAuditLog]

# Tag primary domain models as core_entity (semantic context for AI + Claude rules) # config.core_models += %w[User Order Project]

# Exclude paths from code search config.excluded_paths += %w[vendor/bundle]

# Cache TTL for MCP tool responses (seconds) config.cache_ttl = 30 end ```

<details> <summary><strong>All configuration options</strong></summary>

Other HTTP MCP knobs live only on the nested object, for example RailsAiBridge.configuration.mcp.authorize, mcp.mode, mcp.security_profile, and mcp.require_auth_in_production — see docs/GUIDE.md and docs/mcp-security.md. </details>

Verify the integration in *your* Rails app

1. bundle install must finish cleanly — until it does, bundle exec rails -T and rails ai:serve (from .mcp.json) cannot be verified. Merging this gem to main does not fix a broken or incomplete bundle on the host app.
2. Regenerate in one shot — run rails ai:bridge (not only a single format) so route/controller summaries and relevance ordering stay consistent across CLAUDE.md, .cursor/rules/, and .github/instructions/.
3. Keep team-specific rules — generated files are snapshots. Use config/rails_ai_bridge/overrides.md for org-specific constraints (merged only after you delete the first-line ` stub). Until then, the gem does not inject placeholder text into Copilot/Codex. See **overrides.md.example** for an outline. Alternatively re-merge into generated files after each rails ai:bridge (see .codex/README.md`).
4. Tune list sizes — RailsAiBridge.configure { |c| c.copilot_compact_model_list_limit = 5 } (and codex_compact_model_list_limit); set 0 to list no model names and point only to MCP.
5. Check your readiness — rails ai:doctor prints a 0–100 score and flags anything missing after first install.

---

Rubydex Integration (Semantic Code Analysis)

Rubydex is Shopify's high-performance Ruby static analysis toolkit. rails-ai-bridge leverages rubydex out-of-the-box for semantic code understanding.

Setup:

Rubydex is installed automatically as a core dependency and is enabled by default.

To customize it in your initializer (config/initializers/rails_ai_bridge.rb):

   RailsAiBridge.configure do |config|
     # config.rubydex_enabled = false # Set to false to disable semantic analysis

     # Optional: enable the semantic introspector (adds :semantic to introspectors)
     config.semantic_introspector_enabled = true
     config.introspectors += %i[semantic]

     # Optional: control semantic context depth in generated files
     # config.semantic_context_depth = :standard  # :summary, :standard, or :full

     # Optional: incremental re-indexing (skip unchanged files on subsequent runs)
     # config.rubydex_incremental_threshold = 0.3  # full rebuild if >30% of files changed
     # config.rubydex_persist_index = true          # survive process restarts
   end
   

What you get:

Internal architecture: The RubydexAdapter wraps the rubydex API as a thin coordinator delegating to three single-responsibility collaborators: Serializer (hash conversion), Indexer (graph construction + source file scanning), and MethodCounter (flat method-counting pipeline). Incremental re-indexing is handled by the IncrementalIndexer service, which tracks file mtimes and triggers a full rebuild when the changed-file ratio exceeds rubydex_incremental_threshold. See CONTRIBUTING.md for the full project layout.

Configuration options:

Performance considerations: Rubydex indexes your Ruby source files at startup. For large codebases, the initial indexing may take a few seconds. Subsequent calls re-use the in-memory index and only re-parse changed files, keeping re-indexing overhead proportional to churn rather than codebase size.

---

Why rails-ai-bridge over alternatives?

Comparison reflects typical documented setups; verify against each project before treating any row as absolute.

---

vs. Other Ruby MCP Projects

---