rails-ai-context 2.0.1 → 2.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +25 -0
- data/README.md +139 -326
- data/docs/GUIDE.md +23 -14
- data/lib/generators/rails_ai_context/install/install_generator.rb +79 -48
- data/lib/rails_ai_context/configuration.rb +5 -0
- data/lib/rails_ai_context/tasks/rails_ai_context.rake +79 -8
- data/lib/rails_ai_context/tools/get_routes.rb +13 -1
- data/lib/rails_ai_context/tools/get_schema.rb +13 -1
- data/lib/rails_ai_context/tools/get_test_info.rb +88 -0
- data/lib/rails_ai_context/tools/get_view.rb +7 -5
- data/lib/rails_ai_context/tools/search_code.rb +307 -40
- data/lib/rails_ai_context/tools/validate.rb +48 -0
- data/lib/rails_ai_context/version.rb +1 -1
- data/server.json +2 -2
- metadata +1 -1
data/README.md
CHANGED
|
@@ -1,273 +1,182 @@
|
|
|
1
1
|
# rails-ai-context
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
### Your AI is guessing. This gem makes it know.
|
|
4
4
|
|
|
5
5
|
[](https://rubygems.org/gems/rails-ai-context)
|
|
6
6
|
[](https://registry.modelcontextprotocol.io)
|
|
7
7
|
[](https://github.com/crisnahine/rails-ai-context/actions)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
**Works with:** Claude Code • Cursor • GitHub Copilot • Windsurf • OpenCode
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
## The Problem
|
|
15
|
-
|
|
16
|
-
AI agents working on Rails apps operate blind. They read files one at a time but never see the full picture — how your schema connects to your models, which callbacks fire on save, what filters apply to a controller action, which Stimulus controllers exist, or what your UI conventions are.
|
|
17
|
-
|
|
18
|
-
The result: **guess-and-check coding.** The agent writes code, it breaks, it reads more files, fixes it, breaks again. Each iteration wastes tokens and erodes trust.
|
|
19
|
-
|
|
20
|
-
## The Solution
|
|
21
|
-
|
|
22
|
-
**rails-ai-context** gives your AI agent what a senior Rails developer has naturally: a structured mental model of the entire application.
|
|
12
|
+
> Built by a Rails developer with 10 years of production experience. Yes, AI helped write this gem — the same way AI helps me ship features at work. I designed the architecture, made every decision, reviewed every line, and wrote 575 tests. The gem exists because I understand Rails deeply enough to know what AI agents get wrong and what context they need to get it right.
|
|
23
13
|
|
|
24
14
|
```bash
|
|
25
|
-
|
|
15
|
+
gem "rails-ai-context", group: :development
|
|
26
16
|
rails generate rails_ai_context:install
|
|
27
|
-
rails ai:context
|
|
28
17
|
```
|
|
29
18
|
|
|
30
|
-
|
|
19
|
+
That's it. Your AI now has 25 live MCP tools that understand your entire Rails app. Zero config.
|
|
31
20
|
|
|
32
|
-
|
|
21
|
+
---
|
|
33
22
|
|
|
34
|
-
|
|
23
|
+
## What AI gets wrong without this
|
|
35
24
|
|
|
36
|
-
|
|
25
|
+
Right now, your AI agent:
|
|
37
26
|
|
|
38
|
-
|
|
27
|
+
- **Reads all 2,000 lines of schema.rb** to find one column type
|
|
28
|
+
- **Misses encrypted columns** — doesn't know `gemini_api_key` is encrypted
|
|
29
|
+
- **Shows 25 Devise methods** as if they're your code
|
|
30
|
+
- **Doesn't see inherited filters** — misses `authenticate_user!` from ApplicationController
|
|
31
|
+
- **Uses underscores in Stimulus HTML** — `data-cook_status` instead of `data-cook-status`
|
|
32
|
+
- **Breaks Turbo Stream wiring** — broadcasts to channels nobody subscribes to
|
|
33
|
+
- **Permits wrong params** — doesn't cross-check against your schema
|
|
34
|
+
- **Guesses your UI patterns** — invents new button styles instead of matching yours
|
|
39
35
|
|
|
40
|
-
|
|
36
|
+
**Every wrong guess = a wasted iteration.** You fix it, re-run, it breaks something else.
|
|
41
37
|
|
|
42
|
-
|
|
38
|
+
---
|
|
43
39
|
|
|
44
|
-
|
|
40
|
+
## What AI knows with this
|
|
45
41
|
|
|
46
|
-
|
|
42
|
+
One call. Full picture.
|
|
47
43
|
|
|
48
44
|
```
|
|
49
|
-
|
|
50
|
-
Agent: rails_get_model_details(model:"Cook") → associations, validations, scopes, callbacks, concern methods
|
|
51
|
-
Agent: rails_get_controllers(controller:"cooks", action:"create") → source code + applicable filters + strong params body
|
|
52
|
-
Agent: rails_validate(files:["app/models/cook.rb"], level:"rails") → catches column/route/partial errors before execution
|
|
45
|
+
rails_search_code(pattern: "can_cook?", match_type: "trace")
|
|
53
46
|
```
|
|
54
47
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
48
|
+
```
|
|
49
|
+
# Trace: can_cook?
|
|
50
|
+
|
|
51
|
+
## Definition
|
|
52
|
+
app/models/concerns/plan_limitable.rb:8
|
|
53
|
+
def can_cook?
|
|
54
|
+
p = effective_plan
|
|
55
|
+
return true if p.unlimited_cooks?
|
|
56
|
+
(cooks_this_month || 0) < p.cooks_per_month
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
## Calls internally
|
|
60
|
+
- unlimited_cooks?
|
|
61
|
+
|
|
62
|
+
## Called from (8 sites)
|
|
63
|
+
### app/controllers/cooks_controller.rb (Controller)
|
|
64
|
+
24: unless current_user.can_cook?
|
|
65
|
+
### app/views/cooks/new.html.erb (View)
|
|
66
|
+
7: <% unless current_user.can_cook? %>
|
|
67
|
+
### test/models/concerns/plan_limitable_test.rb (Test)
|
|
68
|
+
24: assert @user.can_cook?
|
|
69
|
+
29: assert_not @user.can_cook?
|
|
70
|
+
```
|
|
66
71
|
|
|
67
|
-
|
|
72
|
+
Definition + source code + every caller grouped by type + what it calls internally. **One tool call replaces 6 file reads.**
|
|
68
73
|
|
|
69
74
|
---
|
|
70
75
|
|
|
71
|
-
##
|
|
76
|
+
## Measured token savings
|
|
72
77
|
|
|
73
|
-
|
|
74
|
-
|-------|--------|---------------|
|
|
75
|
-
| **rails-ai-context (full)** | **28,834** | 25 MCP tools + generated docs + split rules |
|
|
76
|
-
| rails-ai-context CLAUDE.md only | 33,106 | Generated docs + rules, no MCP tools |
|
|
77
|
-
| Normal Claude `/init` | 40,700 | Generic CLAUDE.md only |
|
|
78
|
-
| No rails-ai-context | 45,477 | Nothing — discovers everything from scratch |
|
|
78
|
+
Tested on a real Rails 8 app (5 models, 19 controllers, 95 routes):
|
|
79
79
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
```
|
|
80
|
+
| Task | Without gem | With gem | Saved |
|
|
81
|
+
|------|-------------|----------|-------|
|
|
82
|
+
| Trace a method across the codebase | ~9,080 tokens (read 5 files) | ~198 tokens (1 MCP call) | **98%** |
|
|
83
|
+
| Understand a feature (schema + model + controller) | ~5,200 tokens (read 3 files) | ~1,500 tokens (2 MCP calls) | **71%** |
|
|
84
|
+
| Check all table columns | ~2,573 tokens (read schema.rb) | ~908 tokens (1 MCP call) | **65%** |
|
|
86
85
|
|
|
87
|
-
|
|
86
|
+
"Without" = AI reads files it would realistically need. "With" = MCP tools return only what's relevant.
|
|
88
87
|
|
|
89
|
-
>
|
|
88
|
+
> Savings scale with app size. A 50-model app reads more files per task — MCP calls stay the same size.
|
|
90
89
|
|
|
91
|
-
But
|
|
90
|
+
But tokens are the side effect. The real value:
|
|
92
91
|
|
|
93
|
-
- **
|
|
94
|
-
- **Cross-file
|
|
95
|
-
- **
|
|
96
|
-
- **No stale context** — live reload invalidates caches when files change mid-session
|
|
92
|
+
- **First attempt is correct** — AI understands associations, callbacks, and constraints before writing code
|
|
93
|
+
- **Cross-file validation** — catches wrong columns, missing partials, broken routes in one call
|
|
94
|
+
- **Matches your patterns** — your button classes, your test style, your flash messages
|
|
97
95
|
|
|
98
96
|
---
|
|
99
97
|
|
|
100
98
|
## 25 Live MCP Tools
|
|
101
99
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
| Tool |
|
|
105
|
-
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `rails_get_service_pattern` | Service objects — interface, dependencies, side effects, error handling, calling convention |
|
|
126
|
-
| `rails_get_job_pattern` | Background jobs — queue, retries, guard clauses, service calls, Turbo broadcasts, schedules |
|
|
100
|
+
Every tool is **read-only** and returns structured, token-efficient data. Start with `detail:"summary"`, drill into specifics.
|
|
101
|
+
|
|
102
|
+
| Tool | One-liner |
|
|
103
|
+
|------|-----------|
|
|
104
|
+
| `rails_search_code` | **Trace mode**: definition + class context + source + internal calls + sibling methods + callers with route chain + test coverage. Also: `"definition"`, `"call"`, `"class"` filters, smart pagination |
|
|
105
|
+
| `rails_get_context` | **Composite**: schema + model + controller + routes + views in one call |
|
|
106
|
+
| `rails_analyze_feature` | **Full-stack**: everything about a feature — models, controllers, routes, services, jobs, views, Stimulus, tests |
|
|
107
|
+
| `rails_validate` | **Syntax + semantic + security** in one call. Catches wrong columns, missing partials, broken routes, Brakeman vulnerabilities |
|
|
108
|
+
| `rails_get_controllers` | Action source code + inherited filters + render map + side effects + private methods inline |
|
|
109
|
+
| `rails_get_schema` | Columns with `[indexed]`, `[unique]`, `[encrypted]`, `[default: value]` hints + model name inline |
|
|
110
|
+
| `rails_get_model_details` | Associations, validations, scopes with lambda body, enum backing types, macros, delegations, constants |
|
|
111
|
+
| `rails_get_routes` | Code-ready helpers (`cook_path(@record)`), controller filters inline, required params |
|
|
112
|
+
| `rails_get_view` | Templates with ivars, Turbo wiring, Stimulus refs, partial locals — pipe-separated, scannable |
|
|
113
|
+
| `rails_get_stimulus` | Copy-paste HTML data-attributes (dashes, not underscores) + reverse view lookup |
|
|
114
|
+
| `rails_get_design_system` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards, modals |
|
|
115
|
+
| `rails_get_test_info` | Fixture contents with relationships + test template matching your app's patterns |
|
|
116
|
+
| `rails_get_conventions` | Your app's actual patterns — auth checks, flash messages, create action template, test patterns |
|
|
117
|
+
| `rails_get_turbo_map` | Broadcast → subscription wiring with mismatch warnings |
|
|
118
|
+
| `rails_get_partial_interface` | Partial locals contract — what to pass, what methods are called on each local |
|
|
119
|
+
| `rails_get_concern` | Public methods, signatures, which models include it |
|
|
120
|
+
| `rails_get_callbacks` | Callbacks in Rails execution order with source code |
|
|
121
|
+
| `rails_get_service_pattern` | Interface, dependencies, side effects, error handling, who calls it |
|
|
122
|
+
| `rails_get_job_pattern` | Queue, retries, guard clauses, Turbo broadcasts, schedules |
|
|
127
123
|
| `rails_get_env` | Environment variables, credentials keys (not values), external service dependencies |
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
124
|
+
| `rails_get_helper_methods` | App + framework helpers with view usage cross-references |
|
|
125
|
+
| `rails_get_config` | Database adapter, auth framework, assets stack, Action Cable, middleware |
|
|
126
|
+
| `rails_get_gems` | Notable gems with versions, categories, and config file locations |
|
|
127
|
+
| `rails_get_edit_context` | Method-aware code extraction with class/method context header |
|
|
128
|
+
| `rails_security_scan` | Brakeman static analysis — SQL injection, XSS, mass assignment |
|
|
131
129
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
Schema, routes, models, and controllers tools support a `detail` parameter — critical for large apps:
|
|
135
|
-
|
|
136
|
-
| Level | Returns | Default limit |
|
|
137
|
-
|-------|---------|---------------|
|
|
138
|
-
| `summary` | Names + counts | 50 |
|
|
139
|
-
| `standard` | Names + key details *(default)* | 25 |
|
|
140
|
-
| `full` | Everything (indexes, FKs, constraints) | 10 |
|
|
141
|
-
|
|
142
|
-
```ruby
|
|
143
|
-
rails_get_schema(detail: "summary") # → all tables with column counts
|
|
144
|
-
rails_get_schema(table: "users") # → full detail for one table
|
|
145
|
-
rails_get_routes(controller: "users") # → routes for one controller
|
|
146
|
-
rails_get_model_details(model: "User") # → associations, validations, scopes
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
A safety net (`max_tool_response_chars`, default 120K) truncates oversized responses with hints to use filters.
|
|
130
|
+
> **[Full parameter documentation →](docs/GUIDE.md)**
|
|
150
131
|
|
|
151
132
|
---
|
|
152
133
|
|
|
153
|
-
##
|
|
154
|
-
|
|
155
|
-
`rails ai:context` generates context files tailored to each AI assistant:
|
|
134
|
+
## How It Works
|
|
156
135
|
|
|
157
136
|
```
|
|
158
|
-
|
|
159
|
-
│
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
│
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
│
|
|
166
|
-
│
|
|
167
|
-
|
|
168
|
-
│
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
│
|
|
172
|
-
│
|
|
173
|
-
│
|
|
174
|
-
│
|
|
175
|
-
│
|
|
176
|
-
|
|
177
|
-
├── ⚡ OpenCode
|
|
178
|
-
│ ├── AGENTS.md native OpenCode context
|
|
179
|
-
│ ├── app/models/AGENTS.md auto-loaded when editing models
|
|
180
|
-
│ └── app/controllers/AGENTS.md auto-loaded when editing controllers
|
|
181
|
-
│
|
|
182
|
-
├── 🔵 Windsurf
|
|
183
|
-
│ ├── .windsurfrules ≤5,800 chars (6K limit)
|
|
184
|
-
│ └── .windsurf/rules/
|
|
185
|
-
│ ├── rails-context.md project overview
|
|
186
|
-
│ ├── rails-ui-patterns.md CSS component patterns
|
|
187
|
-
│ └── rails-mcp-tools.md tool reference
|
|
188
|
-
│
|
|
189
|
-
├── 🟠 GitHub Copilot
|
|
190
|
-
│ ├── .github/copilot-instructions.md ≤500 lines (compact)
|
|
191
|
-
│ └── .github/instructions/
|
|
192
|
-
│ ├── rails-context.instructions.md applyTo: **/*
|
|
193
|
-
│ ├── rails-models.instructions.md applyTo: app/models/**
|
|
194
|
-
│ ├── rails-controllers.instructions.md applyTo: app/controllers/**
|
|
195
|
-
│ ├── rails-ui-patterns.instructions.md applyTo: app/views/**
|
|
196
|
-
│ └── rails-mcp-tools.instructions.md applyTo: **/*
|
|
197
|
-
│
|
|
198
|
-
├── 📋 .ai-context.json full JSON (programmatic)
|
|
199
|
-
└── .mcp.json MCP auto-discovery
|
|
137
|
+
┌─────────────────────────────────────────────────────────┐
|
|
138
|
+
│ Your Rails App │
|
|
139
|
+
│ models + schema + routes + controllers + views + jobs │
|
|
140
|
+
└────────────────────────┬────────────────────────────────┘
|
|
141
|
+
│ introspects
|
|
142
|
+
▼
|
|
143
|
+
┌─────────────────────────────────────────────────────────┐
|
|
144
|
+
│ rails-ai-context (29 introspectors) │
|
|
145
|
+
│ Parses everything. Caches results. Zero config. │
|
|
146
|
+
└────────┬─────────────────────────────┬──────────────────┘
|
|
147
|
+
│ │
|
|
148
|
+
▼ ▼
|
|
149
|
+
┌────────────────────┐ ┌───────────────────────────────┐
|
|
150
|
+
│ Static Files │ │ Live MCP Server (25 tools) │
|
|
151
|
+
│ CLAUDE.md │ │ Real-time queries on demand │
|
|
152
|
+
│ .cursor/rules/ │ │ Schema, models, routes, etc. │
|
|
153
|
+
│ .github/instr... │ │ Trace, validate, analyze │
|
|
154
|
+
│ .windsurfrules │ │ Auto-discovered via .mcp.json │
|
|
155
|
+
└────────────────────┘ └───────────────────────────────┘
|
|
200
156
|
```
|
|
201
157
|
|
|
202
|
-
|
|
158
|
+
The install generator asks which AI tools you use and only generates files for those.
|
|
203
159
|
|
|
204
160
|
---
|
|
205
161
|
|
|
206
|
-
##
|
|
207
|
-
|
|
208
|
-
| Category | What's introspected |
|
|
209
|
-
|----------|-------------------|
|
|
210
|
-
| **Database** | Every table, column, index, foreign key, and migration |
|
|
211
|
-
| **Models** | Associations, validations, scopes, enums, callbacks, concerns, macros |
|
|
212
|
-
| **Routing** | Every route with HTTP verbs, paths, controller actions, API namespaces |
|
|
213
|
-
| **Controllers** | Actions, filters, strong params, concerns, API controllers |
|
|
214
|
-
| **Views** | Layouts, templates, partials, helpers, template engines, view components |
|
|
215
|
-
| **Frontend** | Stimulus controllers (targets, values, actions, outlets), Turbo Frames/Streams |
|
|
216
|
-
| **Background** | ActiveJob classes, mailers, Action Cable channels |
|
|
217
|
-
| **Gems** | 70+ notable gems categorized (Devise = auth, Sidekiq = jobs, Pundit = authorization) |
|
|
218
|
-
| **Auth** | Devise modules, Pundit policies, CanCanCan, has_secure_password, CORS, CSP |
|
|
219
|
-
| **API** | Serializers, GraphQL, versioning, rate limiting, API-only mode |
|
|
220
|
-
| **Testing** | Framework, factories/fixtures, CI config, coverage, system tests |
|
|
221
|
-
| **Config** | Cache store, session store, middleware, initializers, timezone |
|
|
222
|
-
| **DevOps** | Puma, Procfile, Docker, deployment tools, asset pipeline |
|
|
223
|
-
| **Architecture** | Service objects, STI, polymorphism, state machines, multi-tenancy, engines |
|
|
224
|
-
|
|
225
|
-
29 introspectors total. The `:full` preset runs 28 by default; use `:standard` for 13 core only (`database_stats` is opt-in, PostgreSQL only).
|
|
226
|
-
|
|
227
|
-
---
|
|
162
|
+
## Install
|
|
228
163
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
This server is also listed on the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.crisnahine/rails-ai-context`.
|
|
164
|
+
```bash
|
|
165
|
+
# Add to Gemfile
|
|
166
|
+
gem "rails-ai-context", group: :development
|
|
234
167
|
|
|
235
|
-
|
|
168
|
+
# Install (picks your AI tools, generates context)
|
|
169
|
+
rails generate rails_ai_context:install
|
|
236
170
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
|
|
241
|
-
|
|
242
|
-
```json
|
|
243
|
-
{
|
|
244
|
-
"mcpServers": {
|
|
245
|
-
"rails-ai-context": {
|
|
246
|
-
"command": "bundle",
|
|
247
|
-
"args": ["exec", "rails", "ai:serve"],
|
|
248
|
-
"cwd": "/path/to/your/rails/app"
|
|
249
|
-
}
|
|
250
|
-
}
|
|
251
|
-
}
|
|
171
|
+
# Or generate context directly
|
|
172
|
+
rails ai:context
|
|
252
173
|
```
|
|
253
|
-
</details>
|
|
254
|
-
|
|
255
|
-
<details>
|
|
256
|
-
<summary><strong>HTTP transport (for remote clients)</strong></summary>
|
|
257
174
|
|
|
258
|
-
|
|
259
|
-
rails ai:serve_http # Starts at http://127.0.0.1:6029/mcp
|
|
260
|
-
```
|
|
175
|
+
Both commands ask which AI tools you use (Claude, Cursor, Copilot, Windsurf, OpenCode) and only generate what you need.
|
|
261
176
|
|
|
262
|
-
|
|
177
|
+
MCP auto-discovery: `.mcp.json` is detected automatically by Claude Code and Cursor. No manual config.
|
|
263
178
|
|
|
264
|
-
|
|
265
|
-
RailsAiContext.configure do |config|
|
|
266
|
-
config.auto_mount = true
|
|
267
|
-
config.http_path = "/mcp"
|
|
268
|
-
end
|
|
269
|
-
```
|
|
270
|
-
</details>
|
|
179
|
+
> **[Full Guide →](docs/GUIDE.md)** — every command, parameter, and configuration option.
|
|
271
180
|
|
|
272
181
|
---
|
|
273
182
|
|
|
@@ -276,31 +185,17 @@ end
|
|
|
276
185
|
```ruby
|
|
277
186
|
# config/initializers/rails_ai_context.rb
|
|
278
187
|
RailsAiContext.configure do |config|
|
|
279
|
-
#
|
|
280
|
-
config.
|
|
188
|
+
# Which AI tools to generate context for (selected during install)
|
|
189
|
+
# config.ai_tools = %i[claude cursor]
|
|
281
190
|
|
|
282
|
-
#
|
|
283
|
-
# config.
|
|
284
|
-
|
|
285
|
-
# Context mode: :compact (≤150 lines, default) or :full (dump everything)
|
|
286
|
-
# config.context_mode = :compact
|
|
191
|
+
# Presets: :full (28 introspectors, default) or :standard (13 core)
|
|
192
|
+
# config.preset = :full
|
|
287
193
|
|
|
288
194
|
# Exclude models from introspection
|
|
289
|
-
config.excluded_models += %w[AdminUser
|
|
290
|
-
|
|
291
|
-
# Exclude paths from code search
|
|
292
|
-
config.excluded_paths += %w[vendor/bundle]
|
|
293
|
-
|
|
294
|
-
# Cache TTL for MCP tool responses (seconds)
|
|
295
|
-
config.cache_ttl = 60
|
|
296
|
-
|
|
297
|
-
# Live reload: auto-invalidate MCP caches on file changes
|
|
298
|
-
# :auto (default), true, or false
|
|
299
|
-
# config.live_reload = :auto
|
|
195
|
+
# config.excluded_models += %w[AdminUser]
|
|
300
196
|
|
|
301
|
-
# Skip
|
|
302
|
-
#
|
|
303
|
-
# config.generate_root_files = false
|
|
197
|
+
# Skip specific MCP tools
|
|
198
|
+
# config.skip_tools = %w[rails_security_scan]
|
|
304
199
|
end
|
|
305
200
|
```
|
|
306
201
|
|
|
@@ -316,121 +211,39 @@ end
|
|
|
316
211
|
| `context_mode` | `:compact` | `:compact` (≤150 lines) or `:full` (dump everything) |
|
|
317
212
|
| `claude_max_lines` | `150` | Max lines for CLAUDE.md in compact mode |
|
|
318
213
|
| `generate_root_files` | `true` | Generate root files (CLAUDE.md, etc.) — set `false` for split rules only |
|
|
319
|
-
| `
|
|
214
|
+
| `ai_tools` | `nil` (all) | AI tools to generate context for: `%i[claude cursor copilot windsurf opencode]` |
|
|
320
215
|
| **MCP Server** | | |
|
|
321
|
-
| `server_name` | `"rails-ai-context"` | MCP server name |
|
|
322
|
-
| `server_version` | gem version | MCP server version |
|
|
323
|
-
| `auto_mount` | `false` | Auto-mount HTTP MCP endpoint |
|
|
324
|
-
| `http_path` | `"/mcp"` | HTTP endpoint path |
|
|
325
|
-
| `http_port` | `6029` | HTTP server port |
|
|
326
|
-
| `http_bind` | `"127.0.0.1"` | HTTP server bind address |
|
|
327
216
|
| `cache_ttl` | `60` | Cache TTL in seconds |
|
|
328
217
|
| `max_tool_response_chars` | `200_000` | Safety cap for MCP tool responses |
|
|
329
218
|
| `live_reload` | `:auto` | `:auto`, `true`, or `false` — MCP live reload |
|
|
330
|
-
| `
|
|
331
|
-
| **Filtering & Exclusions** | | |
|
|
332
|
-
| `excluded_models` | internal Rails models | Models to skip during introspection |
|
|
333
|
-
| `excluded_paths` | `node_modules tmp log vendor .git` | Paths excluded from code search |
|
|
334
|
-
| `sensitive_patterns` | `.env .env.* config/master.key config/credentials.yml.enc config/credentials/*.yml.enc *.pem *.key` | File patterns blocked from search and read tools |
|
|
335
|
-
| `excluded_controllers` | `DeviseController` etc. | Controller classes hidden from listings |
|
|
336
|
-
| `excluded_route_prefixes` | `action_mailbox/ active_storage/ rails/` etc. | Route controller prefixes hidden with app_only |
|
|
337
|
-
| `excluded_concerns` | Rails/Devise/framework patterns | Regex patterns for concerns to hide |
|
|
338
|
-
| `excluded_filters` | `verify_authenticity_token` etc. | Framework filter names hidden from controller output |
|
|
339
|
-
| `excluded_middleware` | standard Rack/Rails middleware | Default middleware hidden from config output |
|
|
219
|
+
| `auto_mount` | `false` | Auto-mount HTTP MCP endpoint |
|
|
340
220
|
| **File Size Limits** | | |
|
|
341
|
-
| `max_file_size` | `5_000_000` | Per-file read limit
|
|
342
|
-
| `max_test_file_size` | `1_000_000` | Test file read limit (bytes) |
|
|
343
|
-
| `max_schema_file_size` | `10_000_000` | schema.rb / structure.sql parse limit (bytes) |
|
|
344
|
-
| `max_view_total_size` | `10_000_000` | Total aggregated view content for UI patterns (bytes) |
|
|
345
|
-
| `max_view_file_size` | `1_000_000` | Per-view file during aggregation (bytes) |
|
|
221
|
+
| `max_file_size` | `5_000_000` | Per-file read limit (bytes) |
|
|
346
222
|
| `max_search_results` | `200` | Max search results per call |
|
|
347
223
|
| `max_validate_files` | `50` | Max files per validate call |
|
|
348
|
-
| **Search & Discovery** | | |
|
|
349
|
-
| `search_extensions` | `rb js erb yml yaml json ts tsx vue svelte haml slim` | File extensions for Ruby fallback search |
|
|
350
|
-
| `concern_paths` | `app/models/concerns app/controllers/concerns` | Where to look for concern source files |
|
|
351
224
|
| **Extensibility** | | |
|
|
352
|
-
| `custom_tools` | `[]` | Additional MCP tool classes
|
|
353
|
-
| `skip_tools` | `[]` | Built-in tool names to exclude
|
|
225
|
+
| `custom_tools` | `[]` | Additional MCP tool classes |
|
|
226
|
+
| `skip_tools` | `[]` | Built-in tool names to exclude |
|
|
354
227
|
</details>
|
|
355
228
|
|
|
356
229
|
---
|
|
357
230
|
|
|
358
231
|
## Commands
|
|
359
232
|
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
| Command | Description |
|
|
233
|
+
| Command | What it does |
|
|
363
234
|
|---------|-------------|
|
|
364
|
-
| `rails ai:context` | Generate
|
|
365
|
-
| `rails ai:context:full` | Generate all files in full mode (dumps everything) |
|
|
366
|
-
| `rails ai:context:claude` | Generate Claude Code files only |
|
|
367
|
-
| `rails ai:context:opencode` | Generate OpenCode files only |
|
|
368
|
-
| `rails ai:context:cursor` | Generate Cursor files only |
|
|
369
|
-
| `rails ai:context:windsurf` | Generate Windsurf files only |
|
|
370
|
-
| `rails ai:context:copilot` | Generate Copilot files only |
|
|
371
|
-
| `rails ai:context:json` | Generate JSON context file only |
|
|
235
|
+
| `rails ai:context` | Generate context files for your AI tools |
|
|
372
236
|
| `rails ai:serve` | Start MCP server (stdio) |
|
|
373
|
-
| `rails ai:
|
|
374
|
-
| `rails ai:
|
|
375
|
-
| `rails ai:
|
|
376
|
-
| `rails ai:inspect` | Print introspection summary to stdout |
|
|
377
|
-
|
|
378
|
-
### Standalone CLI
|
|
379
|
-
|
|
380
|
-
The gem also ships a `rails-ai-context` executable — an alternative to rake tasks.
|
|
381
|
-
|
|
382
|
-
| Command | Equivalent rake task |
|
|
383
|
-
|---------|---------------------|
|
|
384
|
-
| `rails-ai-context serve` | `rails ai:serve` |
|
|
385
|
-
| `rails-ai-context serve --transport http` | `rails ai:serve_http` |
|
|
386
|
-
| `rails-ai-context context` | `rails ai:context` |
|
|
387
|
-
| `rails-ai-context context --format claude` | `rails ai:context:claude` |
|
|
388
|
-
| `rails-ai-context doctor` | `rails ai:doctor` |
|
|
389
|
-
| `rails-ai-context watch` | `rails ai:watch` |
|
|
390
|
-
| `rails-ai-context inspect` | `rails ai:inspect` |
|
|
391
|
-
| `rails-ai-context version` | — |
|
|
392
|
-
|
|
393
|
-
Run from your Rails app root. Use `rails-ai-context help` for all options.
|
|
394
|
-
|
|
395
|
-
---
|
|
396
|
-
|
|
397
|
-
## Stack Compatibility
|
|
398
|
-
|
|
399
|
-
Works with every Rails architecture — auto-detects what's relevant:
|
|
400
|
-
|
|
401
|
-
| Setup | Coverage | Notes |
|
|
402
|
-
|-------|----------|-------|
|
|
403
|
-
| Rails full-stack (ERB + Hotwire) | 29/29 | All introspectors relevant |
|
|
404
|
-
| Rails + Inertia.js (React/Vue) | ~22/29 | Views/Turbo partially useful, backend fully covered |
|
|
405
|
-
| Rails API + React/Next.js SPA | ~20/29 | Schema, models, routes, API, auth, jobs — all covered |
|
|
406
|
-
| Rails API + mobile app | ~20/29 | Same as SPA — backend introspection is identical |
|
|
407
|
-
| Rails engine (mountable gem) | ~15/29 | Core introspectors (schema, models, routes, gems) work |
|
|
408
|
-
|
|
409
|
-
Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — they report nothing when those features aren't present.
|
|
410
|
-
|
|
411
|
-
---
|
|
412
|
-
|
|
413
|
-
## Works Without a Database
|
|
414
|
-
|
|
415
|
-
The gem parses `db/schema.rb` as text when no database is connected. Works in CI, Docker build stages, and Claude Code sessions without a running DB.
|
|
237
|
+
| `rails ai:doctor` | Diagnostics + AI readiness score |
|
|
238
|
+
| `rails ai:watch` | Auto-regenerate on file changes |
|
|
239
|
+
| `rails ai:inspect` | Print introspection summary |
|
|
416
240
|
|
|
417
241
|
---
|
|
418
242
|
|
|
419
243
|
## Requirements
|
|
420
244
|
|
|
421
245
|
- Ruby >= 3.2, Rails >= 7.1
|
|
422
|
-
-
|
|
423
|
-
- Optional: `listen` gem for watch mode, `ripgrep` for fast code search
|
|
424
|
-
|
|
425
|
-
---
|
|
426
|
-
|
|
427
|
-
## vs. Other Ruby MCP Projects
|
|
428
|
-
|
|
429
|
-
| Project | Approach | rails-ai-context |
|
|
430
|
-
|---------|----------|-----------------|
|
|
431
|
-
| [Official Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk) | Low-level protocol library | We **use** this as our foundation |
|
|
432
|
-
| [fast-mcp](https://github.com/yjacquin/fast-mcp) | Generic MCP framework | We're a **product** — zero-config Rails introspection |
|
|
433
|
-
| [rails-mcp-server](https://github.com/maquina-app/rails-mcp-server) | Manual config (`projects.yml`) | We auto-discover everything |
|
|
246
|
+
- Optional: `brakeman` for security scanning, `listen` for watch mode, `ripgrep` for fast search
|
|
434
247
|
|
|
435
248
|
---
|
|
436
249
|
|
|
@@ -439,7 +252,7 @@ The gem parses `db/schema.rb` as text when no database is connected. Works in CI
|
|
|
439
252
|
```bash
|
|
440
253
|
git clone https://github.com/crisnahine/rails-ai-context.git
|
|
441
254
|
cd rails-ai-context && bundle install
|
|
442
|
-
bundle exec rspec #
|
|
255
|
+
bundle exec rspec # 575 examples
|
|
443
256
|
bundle exec rubocop # Lint
|
|
444
257
|
```
|
|
445
258
|
|
|
@@ -447,7 +260,7 @@ Bug reports and pull requests welcome at [github.com/crisnahine/rails-ai-context
|
|
|
447
260
|
|
|
448
261
|
## Sponsorship
|
|
449
262
|
|
|
450
|
-
If rails-ai-context
|
|
263
|
+
If rails-ai-context saves you time, consider [becoming a sponsor](https://github.com/sponsors/crisnahine).
|
|
451
264
|
|
|
452
265
|
## License
|
|
453
266
|
|