rails-ai-context 5.34.1 → 5.35.0
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 +54 -0
- data/CONTEXT.md +20 -0
- data/README.md +193 -149
- data/docs/CLI.md +53 -5
- data/docs/COMPATIBILITY.md +7 -0
- data/docs/CONFIGURATION.md +1 -0
- data/docs/FAQ.md +12 -3
- data/docs/GUIDE.md +52 -23
- data/docs/PROMPTS.md +394 -0
- data/docs/QUICKSTART.md +17 -5
- data/docs/RELEASING.md +15 -6
- data/docs/SETUP.md +59 -39
- data/docs/STANDALONE.md +9 -3
- data/docs/TROUBLESHOOTING.md +23 -4
- data/docs/adr/0007-every-install-question-has-a-flag.md +25 -0
- data/docs/index.md +1 -0
- data/exe/rails-ai-context +148 -25
- data/lib/generators/rails_ai_context/install/install_generator.rb +71 -22
- data/lib/rails_ai_context/install/ai_tool.rb +13 -1
- data/lib/rails_ai_context/install/cleanup.rb +34 -2
- data/lib/rails_ai_context/install/program.rb +221 -43
- data/lib/rails_ai_context/install/uninstall.rb +105 -0
- data/lib/rails_ai_context/install/validation_hook.rb +48 -0
- data/lib/rails_ai_context/legacy_cleanup.rb +8 -5
- data/lib/rails_ai_context/mcp_config_generator.rb +14 -4
- data/lib/rails_ai_context/version.rb +1 -1
- data/server.json +1 -1
- metadata +4 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 63645c29cd90be888f3a5417ecdc022404033905ec0ecef3d8da431602060931
|
|
4
|
+
data.tar.gz: 82365666d69092f451df32c00345ac88adac5b975987ecf3da1e55141ca06088
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 5e04445f7c8580e3e963d4c013a8dfe001162e4966144e8b9989786e3e21f962c188ff2c12352282684584dfb72c05d2dcf52fa2bc9548c17c944c91c0e6e96c
|
|
7
|
+
data.tar.gz: c3f2708a684212fede795c107421c1b6491d9705c23d9a06f2ec5e190f24dd1f87394ee61d2fc4cda4205c0ade2321a9a7ec17f446d159d6fa15399fd3cbe9cd
|
data/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,60 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [5.35.0] - 2026-10-12
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **Copy-paste prompts.** `docs/PROMPTS.md` holds a prompt for every way
|
|
13
|
+
to set the gem up, change it, upgrade it, fix it and remove it, plus
|
|
14
|
+
prompts for daily work. Paste one into Claude Code, Cursor, GitHub
|
|
15
|
+
Copilot, OpenCode or Codex CLI and it runs the install in its own shell.
|
|
16
|
+
Prompts cover the Gemfile and standalone installs, the three setups, a
|
|
17
|
+
team, a folder of apps, a private setup, a try-out, HTTP, Ruby in Docker
|
|
18
|
+
and MCP clients the gem writes no config for.
|
|
19
|
+
- **Every install question has a flag.** `init` and the install generator
|
|
20
|
+
take `--tools claude,cursor` (or `all`), `--mcp`, `--cli`, `--prune`, and `init`
|
|
21
|
+
takes `--defaults` too; the generator also takes `--hook`. With them an AI
|
|
22
|
+
tool or a script runs the install to the end with nobody at the keyboard.
|
|
23
|
+
A flag the install cannot read, such as a tool name it does not know,
|
|
24
|
+
`--cli` with `--mcp-only`, or a flag the generator does not have, stops it
|
|
25
|
+
with exit status 1 before anything is written. Only `--prune` removes
|
|
26
|
+
files: a dropped tool's, the gem's MCP entries on a switch to the CLI
|
|
27
|
+
setup, the generated context files on a switch to the MCP-only setup, and
|
|
28
|
+
legacy files.
|
|
29
|
+
ADR-0007 records the design.
|
|
30
|
+
- **`rails-ai-context uninstall`.** It removes each AI tool's context files
|
|
31
|
+
and MCP entries, `.rails-ai-context.yml`, `.ai-context.json`, the
|
|
32
|
+
initializer, the `.gitignore` lines and the pre-commit hook it installed,
|
|
33
|
+
and keeps what you wrote: your lines in a shared `CLAUDE.md`, other
|
|
34
|
+
servers in an MCP config, a hook you changed. It names a
|
|
35
|
+
`mount RailsAiContext::Engine` line instead of editing routes, works in a
|
|
36
|
+
folder of apps, and needs no boot.
|
|
37
|
+
- **`rails-ai-context mcp-entry`.** It prints a server entry for an MCP
|
|
38
|
+
client the gem writes no config for (Claude Desktop, Windsurf, Zed, a
|
|
39
|
+
JetBrains IDE), with the Ruby binary, the executable and the app by their
|
|
40
|
+
full paths and the gem environment beside them, so it starts from
|
|
41
|
+
whatever folder the client uses.
|
|
42
|
+
|
|
43
|
+
### Changed
|
|
44
|
+
|
|
45
|
+
- **A re-run's default is what the app has.** An empty answer, or
|
|
46
|
+
`--defaults`, on a re-run keeps the recorded AI tools and setup. It used
|
|
47
|
+
to take all five tools and the MCP setup, so running the install again to
|
|
48
|
+
repair a CLI or MCP-only install switched it. A first install's defaults
|
|
49
|
+
are unchanged, and `--mcp` names the MCP setup outright. In a folder of
|
|
50
|
+
apps that recorded different setups, `--defaults` asks for a setup flag
|
|
51
|
+
instead of picking one.
|
|
52
|
+
- **Switching to the MCP-only setup offers to remove the generated context
|
|
53
|
+
files.** Nothing refreshes them once the install writes none, so they
|
|
54
|
+
went stale; the question lists them, `--prune` answers yes, and the lines
|
|
55
|
+
you wrote stay.
|
|
56
|
+
- **The install summary names each AI tool's next step.** It said the MCP
|
|
57
|
+
config was "auto-detected on project open" with "no manual config
|
|
58
|
+
needed", but every tool holds a project's server back until you approve
|
|
59
|
+
it (Claude Code), turn it on (Cursor), trust the folder (VS Code, Codex
|
|
60
|
+
CLI) or restart (OpenCode). The summary now says which, per tool.
|
|
61
|
+
|
|
8
62
|
## [5.34.1] - 2026-10-12
|
|
9
63
|
|
|
10
64
|
### Changed
|
data/CONTEXT.md
CHANGED
|
@@ -190,3 +190,23 @@ A folder an editor or agent is opened at that is no app and has no app above it,
|
|
|
190
190
|
**Server name** - the key an entry has in a config. An app's own config calls its server `rails-ai-context`; a workspace's calls each one `rails-ai-context-<app folder>` (`Install::Workspace.server_names`), with the whole path where two apps share a folder name, and a hash where the name would be too long for the tools. `McpConfigGenerator::OWN_SERVER_NAME` matches every form, and `own_entry?` claims the ones that run the gem's server, so removal never leaves one behind and never takes an entry somebody else named that way. Not the **announced name**, which the running server gives the tool (`config.server_name`, or, in place of its default, `RAILS_AI_CONTEXT_SERVER_NAME` for one process): a workspace server announces its app first, because VS Code names tools after that and keeps 13 characters of it.
|
|
191
191
|
|
|
192
192
|
**Workspace entry** - the server entry itself: `--app-path` relative to the workspace, because the file may be committed; spelled from the tool's own name for its config's folder (`${workspaceFolder}`) where it has one, bare where the tool starts servers in the folder it was launched in. For an in-Gemfile app it adds `BUNDLE_GEMFILE` naming the Gemfile the app's bundle reads (its own, else the shared one its `config/boot.rb` names, else the one `bundle exec` run inside the app would find), because `bundle exec` started in the workspace would never find it. ADR-0005 records the per-tool facts this rests on.
|
|
193
|
+
|
|
194
|
+
## Setup
|
|
195
|
+
|
|
196
|
+
What an install writes, one of three. Qualify it; "mode" alone names only one of its two parts.
|
|
197
|
+
|
|
198
|
+
**MCP setup** - the MCP config for each AI tool plus its context files. The default.
|
|
199
|
+
|
|
200
|
+
**CLI setup** - the context files and no MCP config (`tool_mode: cli`). The AI tool runs the tools as shell commands, and the context files tell it how.
|
|
201
|
+
|
|
202
|
+
**MCP-only setup** - the MCP config and no context files (`context_files: false`). For a user who keeps their own `CLAUDE.md` and `AGENTS.md`.
|
|
203
|
+
|
|
204
|
+
`tool_mode` is one axis (mcp or cli) and `context_files` the other, so the MCP-only setup is the mcp tool mode without context files, not a third tool mode. `Install::Program::Setup` holds the pair.
|
|
205
|
+
|
|
206
|
+
## Unattended install
|
|
207
|
+
|
|
208
|
+
An install with every question answered on the command line, the way an AI tool runs it from an **install prompt** or a script runs it in CI. A flag answers its question (`--tools`, `--mcp`, `--cli` or `--mcp-only`, `--prune`, `--hook`), `--defaults` answers the rest with their defaults, and a flag the install cannot read stops it before anything is asked or written. A default is what the app has: the recorded tools and **setup** on a re-run, all five tools and the MCP setup on a first install. A default never removes a file; only `--prune` does. ADR-0007 records why.
|
|
209
|
+
|
|
210
|
+
## Install prompt
|
|
211
|
+
|
|
212
|
+
A message a user pastes into their AI tool so the AI tool installs, changes, removes or starts using the gem in their app. `docs/PROMPTS.md` holds them. Each names its commands outright and runs an **unattended install**, since an AI tool's shell has no one at the keyboard to answer a question.
|
data/README.md
CHANGED
|
@@ -2,178 +2,170 @@
|
|
|
2
2
|
|
|
3
3
|
# rails-ai-context
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
### Your AI coding assistant, reading your real Rails app instead of guessing it.
|
|
6
6
|
|
|
7
7
|
[](https://rubygems.org/gems/rails-ai-context)
|
|
8
8
|
[](https://rubygems.org/gems/rails-ai-context)
|
|
9
9
|
[](https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml)
|
|
10
10
|
[](https://registry.modelcontextprotocol.io)
|
|
11
|
-
[](
|
|
12
|
-
[](
|
|
11
|
+
[](docs/COMPATIBILITY.md)
|
|
12
|
+
[](docs/COMPATIBILITY.md)
|
|
13
13
|
[](LICENSE)
|
|
14
14
|
|
|
15
|
-
[](
|
|
16
|
-
[](
|
|
17
|
-
[](
|
|
18
|
-
[](
|
|
19
|
-
[](
|
|
15
|
+
[](docs/SETUP.md#claude-code)
|
|
16
|
+
[](docs/SETUP.md#cursor)
|
|
17
|
+
[](docs/SETUP.md#github-copilot)
|
|
18
|
+
[](docs/SETUP.md#opencode)
|
|
19
|
+
[](docs/SETUP.md#codex-cli)
|
|
20
20
|
[](docs/CLI.md)
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
[Why](#why) • [Features](#features) • [Getting started](#getting-started) • [Usage](#usage) • [Tools](#tools) • [Configuration](#configuration) • [Documentation](#documentation)
|
|
22
|
+
**[Install in one paste](#install-in-one-paste)** · [Why](#why) · [What you get](#what-you-get) · [Tools](#tools) · [Commands](#commands) · [Docs](#documentation)
|
|
25
23
|
|
|
26
24
|
|
|
27
25
|
|
|
28
26
|
</div>
|
|
29
27
|
|
|
30
|
-
**rails-ai-context**
|
|
31
|
-
|
|
32
|
-
> [!TIP]
|
|
33
|
-
> Nothing to add to your Gemfile if you don't want to. `gem install rails-ai-context`, then `rails-ai-context init` inside any Rails app, or in a folder of apps to set them all up with one MCP server each. It also works on an app that won't boot: pass `--no-boot` and the tools answer from the source files. The two that need a live app, `query` and `runtime_info`, say so.
|
|
34
|
-
|
|
35
|
-
## Why
|
|
28
|
+
**rails-ai-context** makes your Rails app the source of truth for your AI coding assistant. The assistant stops guessing your schema, associations, routes and conventions from training data and asks your app instead: **45 read-only tools** over [MCP](https://modelcontextprotocol.io) or the command line, plus context files written for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI.
|
|
36
29
|
|
|
37
|
-
|
|
30
|
+
## Install in one paste
|
|
38
31
|
|
|
39
|
-
|
|
40
|
-
- Call `user.posts` when the association is `user.articles`.
|
|
41
|
-
- Scaffold tests with FactoryBot in a fixture-based suite.
|
|
42
|
-
- Miss a `before_action` inherited from a parent controller, then wonder why auth fails.
|
|
43
|
-
- Add a gem you already have, or call an API from one you don't.
|
|
44
|
-
- Invent a method that isn't in the codebase.
|
|
32
|
+
Open your AI tool at the root of your Rails app and paste this. It installs the gem, sets up the AI tool you're in, checks the result and tells you the one step left.
|
|
45
33
|
|
|
46
|
-
|
|
34
|
+
<!-- BEGIN install-prompt: kept identical to "Install (recommended)" in docs/PROMPTS.md by spec -->
|
|
35
|
+
```text
|
|
36
|
+
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.
|
|
47
37
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
<div align="center">
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
</div>
|
|
62
|
-
|
|
63
|
-
## Features
|
|
64
|
-
|
|
65
|
-
- **45 read-only tools** for schema, models, controllers, routes, views, Stimulus, Turbo, jobs, services, mailers, i18n, gems, config, tests, security, performance and more. Every answer comes from your app.
|
|
66
|
-
- **Prism AST parsing** for model introspection. A model heading and each scope carry `[VERIFIED]` or `[INFERRED]` (`[STATIC]` without a boot) so the assistant knows what is ground truth and what needs a runtime check.
|
|
67
|
-
- **Three ways in**: MCP over stdio, MCP mounted inside your Rails app over HTTP, or plain CLI in any terminal.
|
|
68
|
-
- **Generated context files** for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI, with the MCP config each tool auto-detects on project open.
|
|
69
|
-
- **Live resources**: `rails://` and `rails-ai-context://` URIs that introspect fresh on every read.
|
|
70
|
-
- **Anti-hallucination rules** shipped in each AI tool's main context file, in compact and full mode, on by default.
|
|
71
|
-
- **Static tier**: when the app can't boot, tools answer from `config/routes.rb`, `db/schema.rb`, migrations and source files, and say so.
|
|
72
|
-
- **Works with real app shapes**: packwerk packs, in-repo engines, multi-database schema dumps, Mongoid, API-only apps.
|
|
73
|
-
- **Custom tools**: register your own `MCP::Tool` classes next to the built-in ones and test them with the bundled `TestHelper`.
|
|
38
|
+
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.
|
|
39
|
+
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.
|
|
40
|
+
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.
|
|
41
|
+
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.
|
|
42
|
+
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.
|
|
43
|
+
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.
|
|
44
|
+
```
|
|
45
|
+
<!-- END install-prompt -->
|
|
74
46
|
|
|
75
|
-
|
|
47
|
+
### Something else in mind? There's a prompt for it
|
|
76
48
|
|
|
77
|
-
|
|
49
|
+
| | |
|
|
50
|
+
|:---|:---|
|
|
51
|
+
| [**No Gemfile change**](docs/PROMPTS.md#install-without-touching-the-gemfile) | The gem lives in your Ruby, the app's bundle stays as it is |
|
|
52
|
+
| [**CLI only**](docs/PROMPTS.md#cli-only-no-mcp-server) | No MCP server. The assistant runs the tools as shell commands |
|
|
53
|
+
| [**MCP only**](docs/PROMPTS.md#mcp-only-keep-my-own-context-files) | The server and nothing else. Your `CLAUDE.md` and `AGENTS.md` stay untouched |
|
|
54
|
+
| [**A whole team**](docs/PROMPTS.md#for-a-whole-team-every-ai-tool) | All five AI tools, so everyone who opens the repo gets it |
|
|
55
|
+
| [**A folder of apps**](docs/PROMPTS.md#a-folder-of-apps) | One editor window, several apps, one MCP server each |
|
|
56
|
+
| [**Nothing committed**](docs/PROMPTS.md#private-setup-nothing-committed) | Works on your machine, `git status` stays clean |
|
|
57
|
+
| [**Just looking**](docs/PROMPTS.md#try-it-without-installing) | See what your assistant would get. Writes nothing |
|
|
58
|
+
| [**MCP over HTTP**](docs/PROMPTS.md#mcp-over-http) | Mounted inside the running app, for clients that connect by URL |
|
|
59
|
+
| [**Ruby in Docker**](docs/PROMPTS.md#ruby-runs-in-docker) | The server runs in your container, your AI tool on your machine |
|
|
60
|
+
| [**Another MCP client**](docs/PROMPTS.md#another-mcp-client) | Claude Desktop, Windsurf, Zed, JetBrains: an entry that starts from any folder |
|
|
61
|
+
|
|
62
|
+
Already installed? Prompts to [change the setup](docs/PROMPTS.md#change-the-setup), [switch install type](docs/PROMPTS.md#switch-between-gemfile-and-standalone), [upgrade](docs/PROMPTS.md#upgrade), [fix it](docs/PROMPTS.md#fix-it), [uninstall](docs/PROMPTS.md#uninstall), and [put it to work](docs/PROMPTS.md#prompts-for-daily-work). Every one gives each install answer as a flag, so it never stalls on a question in the AI tool's terminal.
|
|
63
|
+
|
|
64
|
+
<details>
|
|
65
|
+
<summary><b>Rather type it yourself?</b></summary>
|
|
78
66
|
|
|
79
|
-
|
|
80
|
-
- Rails 7.0 or newer
|
|
81
|
-
- Linux, macOS or Windows (see [Operating systems](docs/COMPATIBILITY.md#operating-systems))
|
|
82
|
-
- Optional: `brakeman` for `security_scan`, `listen` for `watch`, `ripgrep` for faster `search_code`
|
|
67
|
+
<br>
|
|
83
68
|
|
|
84
|
-
|
|
69
|
+
In the Gemfile:
|
|
85
70
|
|
|
86
71
|
```bash
|
|
87
72
|
bundle add rails-ai-context --group development
|
|
88
|
-
rails generate rails_ai_context:install
|
|
73
|
+
bin/rails generate rails_ai_context:install # asks which AI tools and what to write
|
|
74
|
+
bin/rails generate rails_ai_context:install --tools claude --defaults # asks nothing
|
|
89
75
|
```
|
|
90
76
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
Keeping your own `CLAUDE.md` and `AGENTS.md`? `rails generate rails_ai_context:install --mcp-only` writes the MCP config and leaves every context file alone.
|
|
94
|
-
|
|
95
|
-
### Install standalone
|
|
77
|
+
Standalone, with no Gemfile change:
|
|
96
78
|
|
|
97
79
|
```bash
|
|
98
80
|
gem install rails-ai-context
|
|
99
|
-
|
|
100
|
-
rails-ai-context init
|
|
101
|
-
rails-ai-context serve
|
|
81
|
+
rails-ai-context init # or: rails-ai-context init --tools claude --defaults
|
|
102
82
|
```
|
|
103
83
|
|
|
104
|
-
|
|
84
|
+
`--tools` takes `claude`, `cursor`, `copilot`, `opencode`, `codex` or `all`. Add `--cli` for context files only, or `--mcp-only` for the MCP config only. Re-running is safe: with `--defaults` it keeps your recorded tools and setup, keeps what you have and adds what is missing, and in a `CLAUDE.md` you wrote it only touches the block between its `<!-- BEGIN/END rails-ai-context -->` markers. Every step is in [What the install generator does](docs/GUIDE.md#what-the-install-generator-does).
|
|
105
85
|
|
|
106
|
-
|
|
86
|
+
Needs Ruby 3.1+ and Rails 7.0+, on Linux, macOS or Windows. Optional: `brakeman` for `security_scan`, `listen` for `watch`, `ripgrep` for faster `search_code`.
|
|
107
87
|
|
|
108
|
-
|
|
109
|
-
rails ai:doctor # in-Gemfile: readiness score + diagnostics
|
|
110
|
-
rails-ai-context doctor # standalone
|
|
111
|
-
|
|
112
|
-
rails 'ai:tool[schema]' table=users
|
|
113
|
-
rails 'ai:tool[model_details]' model=User
|
|
114
|
-
rails 'ai:tool[search_code]' pattern=publishable? match_type=trace
|
|
115
|
-
```
|
|
88
|
+
</details>
|
|
116
89
|
|
|
117
|
-
Then
|
|
90
|
+
### Then one step in your AI tool
|
|
118
91
|
|
|
119
|
-
|
|
120
|
-
> The CLI commands above are for you. When MCP is connected the assistant calls the same tools itself; you never type them.
|
|
92
|
+
Every AI tool holds a new project MCP server back until you say yes. The install prints the step for each tool you picked:
|
|
121
93
|
|
|
122
|
-
|
|
94
|
+
| Claude Code | Cursor | GitHub Copilot | OpenCode | Codex CLI |
|
|
95
|
+
|:---|:---|:---|:---|:---|
|
|
96
|
+
| New session in the app's folder, approve `rails-ai-context`. Check with `/mcp` | Restart, turn it on under MCP in Customize | Trust the workspace, send a chat message. Check with "MCP: List Servers" | Restart in the app's folder. Check with `opencode mcp list` | Trust the project, start a new session. Check with `/mcp` |
|
|
123
97
|
|
|
124
|
-
|
|
98
|
+
Then ask something only your app knows, such as *"what columns does the users table have?"*, and watch it call `rails_get_schema` instead of guessing.
|
|
125
99
|
|
|
126
|
-
|
|
100
|
+
## Why
|
|
127
101
|
|
|
128
|
-
|
|
129
|
-
bundle exec rails-ai-context serve # in-Gemfile
|
|
130
|
-
rails-ai-context serve # standalone
|
|
131
|
-
```
|
|
102
|
+
You have seen your assistant do these:
|
|
132
103
|
|
|
133
|
-
|
|
104
|
+
- Write a migration for a column that already exists.
|
|
105
|
+
- Call `user.posts` when the association is `user.articles`.
|
|
106
|
+
- Scaffold tests with FactoryBot in a fixture-based suite.
|
|
107
|
+
- Miss a `before_action` inherited from a parent controller, then wonder why auth fails.
|
|
108
|
+
- Add a gem you already have, or call an API from one you don't.
|
|
109
|
+
- Invent a method that isn't in the codebase.
|
|
134
110
|
|
|
135
|
-
|
|
111
|
+
You catch it, fix it, re-prompt, and something next to it breaks. The tokens are cheap, but the correction loop costs you the afternoon. This gem removes the guess at the source.
|
|
136
112
|
|
|
137
|
-
|
|
113
|
+
| You ask the AI to... | Without | With |
|
|
114
|
+
|:---|:---|:---|
|
|
115
|
+
| Add a `subscription_tier` column to users | Writes the migration, duplicates an existing column | Reads the live schema, sees `subscription_status`, asks before migrating |
|
|
116
|
+
| Call `user.posts` in a controller | Guesses; `NoMethodError` at runtime | Resolves the real association from the model |
|
|
117
|
+
| Write tests for a new model | Scaffolds with FactoryBot | Detects your fixture-based suite and matches it |
|
|
118
|
+
| Fix a failing create action | Misses the inherited `authenticate_user!` | Gets parent-controller filters inline with the action source |
|
|
119
|
+
| Build a dashboard page | Invents Tailwind classes from memory | Gets your real button, card and alert patterns |
|
|
120
|
+
| Trace where `publishable?` is used | Reads 6 files in sequence, still misses callers | One call: definition, source, every caller, tests |
|
|
138
121
|
|
|
139
|
-
|
|
140
|
-
# config/routes.rb
|
|
141
|
-
mount RailsAiContext::Engine, at: "/mcp" if defined?(RailsAiContext::Engine)
|
|
142
|
-
```
|
|
122
|
+
<div align="center">
|
|
143
123
|
|
|
144
|
-
|
|
124
|
+
|
|
145
125
|
|
|
146
|
-
|
|
126
|
+
</div>
|
|
147
127
|
|
|
148
|
-
|
|
128
|
+
## What you get
|
|
149
129
|
|
|
150
|
-
|
|
130
|
+
| | |
|
|
131
|
+
|:---|:---|
|
|
132
|
+
| **45 read-only tools** | Schema, models, controllers, routes, views, Stimulus, Turbo, jobs, services, mailers, i18n, gems, config, tests, security, performance and more. Every answer comes from your app. |
|
|
133
|
+
| **Answers it can trust** | Models are read with the Prism parser. A model and each scope carry `[VERIFIED]` or `[INFERRED]` (`[STATIC]` without a boot), so the assistant knows what still needs a runtime check. |
|
|
134
|
+
| **Three ways in** | MCP over stdio, MCP mounted in your app over HTTP, or plain CLI in any terminal. |
|
|
135
|
+
| **Context files per AI tool** | `CLAUDE.md`, Cursor rules, Copilot instructions, `AGENTS.md`, each with the MCP config its tool picks up, and six anti-hallucination rules up top. |
|
|
136
|
+
| **Works on apps that won't boot** | Missing ENV vars, no database, a broken initializer: the tools answer from `config/routes.rb`, the schema dump and the source files, and say so. |
|
|
137
|
+
| **Real app shapes** | Packwerk packs, in-repo engines, multi-database dumps, Mongoid, API-only apps, a folder holding several apps. |
|
|
138
|
+
| **Read-only and careful** | SQL runs read-only with a timeout, a row limit and column redaction. Logs are redacted before they leave the process. Secrets files are never served. |
|
|
139
|
+
| **Yours to extend** | Register your own `MCP::Tool` classes beside the built-in ones and test them with the bundled `TestHelper`. |
|
|
151
140
|
|
|
152
|
-
###
|
|
141
|
+
### Pick a setup
|
|
153
142
|
|
|
154
|
-
|
|
143
|
+
| Setup | Writes | Flag | Good for |
|
|
144
|
+
|:---|:---|:---|:---|
|
|
145
|
+
| **MCP + context files** | MCP config and context files | `--mcp` (the default) | Most apps |
|
|
146
|
+
| **CLI only** | Context files that name shell commands | `--cli` | Tools without MCP, or no server to approve |
|
|
147
|
+
| **MCP only** | MCP config only | `--mcp-only` | Teams that keep their own `CLAUDE.md` / `AGENTS.md` |
|
|
155
148
|
|
|
156
|
-
|
|
157
|
-
rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
|
|
158
|
-
rails-ai-context tool schema --table users --detail full
|
|
159
|
-
```
|
|
149
|
+
Switch any time with the [change the setup](docs/PROMPTS.md#change-the-setup) prompt, or run the install again with the new flag and `--prune`.
|
|
160
150
|
|
|
161
|
-
|
|
151
|
+
## How it works
|
|
162
152
|
|
|
163
|
-
|
|
153
|
+
```mermaid
|
|
154
|
+
graph TD
|
|
155
|
+
A["Your Rails app\nmodels + schema + routes + controllers + views + jobs"] -->|"40 introspectors"| B
|
|
156
|
+
B["rails-ai-context\nPrism AST · cached · confidence-tagged\nstatic tier when the app can't boot"]
|
|
157
|
+
B --> C["MCP server\nstdio / HTTP\n45 tools · 5 templates · 9 resources"]
|
|
158
|
+
B --> D["CLI\nrake / Thor\nsame 45 tools"]
|
|
159
|
+
B --> E["Context files\nCLAUDE.md · .cursor/rules/ · .github/instructions/ · AGENTS.md"]
|
|
164
160
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
| `rails ai:context` | `rails-ai-context context` | Generate context files |
|
|
172
|
-
| `rails ai:doctor` | `rails-ai-context doctor` | Diagnostics and readiness score |
|
|
173
|
-
| `rails ai:watch` | `rails-ai-context watch` | Regenerate on file change |
|
|
174
|
-
| `rails 'ai:preset[NAME]'` | `rails-ai-context preset NAME` | Run a multi-tool preset (`architecture`, `debugging`, `migration`) |
|
|
161
|
+
style A fill:#4a9eff,stroke:#2d7ad4,color:#fff
|
|
162
|
+
style B fill:#2d2d2d,stroke:#555,color:#fff
|
|
163
|
+
style C fill:#0984e3,stroke:#0770c2,color:#fff
|
|
164
|
+
style D fill:#00cec9,stroke:#00b5b0,color:#fff
|
|
165
|
+
style E fill:#a29bfe,stroke:#8c83f0,color:#fff
|
|
166
|
+
```
|
|
175
167
|
|
|
176
|
-
|
|
168
|
+
Internals are in [Architecture](docs/ARCHITECTURE.md) and [Introspectors](docs/INTROSPECTORS.md).
|
|
177
169
|
|
|
178
170
|
## Tools
|
|
179
171
|
|
|
@@ -190,16 +182,19 @@ Every tool is read-only and answers from your app.
|
|
|
190
182
|
| App config and services | `get_api`, `get_conventions`, `get_config`, `get_gems`, `get_env`, `get_helper_methods`, `get_service_pattern`, `get_job_pattern`, `get_component_catalog`, `get_i18n`, `get_mailers`, `get_engines`, `get_autoload`, `get_active_support`, `get_env_config` |
|
|
191
183
|
| Data and debugging | `dependency_graph`, `migration_advisor`, `search_docs`, `query`, `read_logs`, `diagnose`, `review_changes`, `runtime_info`, `session_context` |
|
|
192
184
|
|
|
193
|
-
|
|
185
|
+
Four worth knowing on day one:
|
|
194
186
|
|
|
195
|
-
-
|
|
196
|
-
-
|
|
197
|
-
-
|
|
198
|
-
-
|
|
187
|
+
- **`search_code` with `match_type=trace`** returns the definition, the source, every caller grouped by file and labelled by type, and the tests, in one call. That replaces 4 to 5 file reads.
|
|
188
|
+
- **`get_controllers`** returns the action source with inherited filters, strong params and the render map.
|
|
189
|
+
- **`get_model_details`** returns associations, validations, scopes, enums and macros from the AST, tagged `[VERIFIED]` or `[INFERRED]`.
|
|
190
|
+
- **`query`** runs read-only SQL with a timeout, a row limit and column redaction.
|
|
199
191
|
|
|
200
|
-
Parameters for all 45 are in the [tools reference](docs/TOOLS.md); worked examples in [recipes](docs/RECIPES.md).
|
|
192
|
+
Over MCP each name gets a `rails_` prefix (`rails_get_schema`). From the CLI the short name works: `schema`, `get_schema` and `rails_get_schema` all resolve. Parameters for all 45 are in the [tools reference](docs/TOOLS.md); worked examples in [recipes](docs/RECIPES.md).
|
|
201
193
|
|
|
202
|
-
|
|
194
|
+
<details>
|
|
195
|
+
<summary><b>Live resources</b></summary>
|
|
196
|
+
|
|
197
|
+
<br>
|
|
203
198
|
|
|
204
199
|
MCP clients can also read structured data as resources. Templates introspect fresh on every request:
|
|
205
200
|
|
|
@@ -211,13 +206,16 @@ MCP clients can also read structured data as resources. Templates introspect fre
|
|
|
211
206
|
| `rails-ai-context://views/{path}` | View template content (path traversal blocked) |
|
|
212
207
|
| `rails-ai-context://routes/{controller}` | Live route map for one controller |
|
|
213
208
|
|
|
214
|
-
The legacy `rails://models/{name}` form is still accepted.
|
|
209
|
+
The legacy `rails://models/{name}` form is still accepted. Plus 9 static resources: `rails://schema`, `routes`, `conventions`, `gems`, `controllers`, `config`, `tests`, `migrations`, `engines`.
|
|
215
210
|
|
|
216
|
-
|
|
211
|
+
</details>
|
|
217
212
|
|
|
218
|
-
|
|
213
|
+
<details>
|
|
214
|
+
<summary><b>The six anti-hallucination rules</b></summary>
|
|
215
|
+
|
|
216
|
+
<br>
|
|
219
217
|
|
|
220
|
-
Each AI tool's main context file (`CLAUDE.md`, `AGENTS.md` for OpenCode and Codex, `.cursorrules` and `.cursor/rules/rails-mcp-tools.mdc` for Cursor, `.github/copilot-instructions.md`)
|
|
218
|
+
Each AI tool's main context file (`CLAUDE.md`, `AGENTS.md` for OpenCode and Codex, `.cursorrules` and `.cursor/rules/rails-mcp-tools.mdc` for Cursor, `.github/copilot-instructions.md`) starts with six rules the assistant reads before writing code, in compact and full mode alike. With `generate_root_files` off, `.claude/rules/rails-mcp-tools.md` and `.github/instructions/rails-mcp-tools.instructions.md` carry them instead:
|
|
221
219
|
|
|
222
220
|
1. Verify before you write. Never reference a column, association, route, helper, method, class, partial or gem that a tool call in this turn did not confirm.
|
|
223
221
|
2. Mark every assumption with `[ASSUMPTION]`. "I'd need to check X first" is a good answer.
|
|
@@ -226,15 +224,58 @@ Each AI tool's main context file (`CLAUDE.md`, `AGENTS.md` for OpenCode and Code
|
|
|
226
224
|
5. Empty tool output is information. "0 callers found" means investigate, it does not mean proceed.
|
|
227
225
|
6. Stale context lies. Re-query after writes.
|
|
228
226
|
|
|
229
|
-
On by default. Turn off with `config.anti_hallucination_rules = false` if you prefer your own.
|
|
227
|
+
On by default. Turn off with `config.anti_hallucination_rules = false` if you prefer your own. In an MCP-only or CLI setup, the [ground rules prompt](docs/PROMPTS.md#ground-rules-for-this-session) gives the assistant the same rules for one session.
|
|
228
|
+
|
|
229
|
+
</details>
|
|
230
|
+
|
|
231
|
+
## Three ways to connect
|
|
232
|
+
|
|
233
|
+
**MCP over stdio** is the default. Each AI tool gets its own config file (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml`) that starts `bundle exec rails-ai-context serve`, or `rails-ai-context serve` standalone. On Windows each starts it through `cmd /c`, since a gem's executables there are batch files.
|
|
234
|
+
|
|
235
|
+
**MCP over HTTP** mounts the server inside your app, where it inherits your routing, auth and middleware:
|
|
236
|
+
|
|
237
|
+
```ruby
|
|
238
|
+
# config/routes.rb
|
|
239
|
+
mount RailsAiContext::Engine, at: "/mcp" if defined?(RailsAiContext::Engine)
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
The `if` keeps the routes file loading where the gem is not installed, as in production, where Bundler skips the development group. Outside development and test the endpoint refuses every request with a 403 unless you set `config.allow_http_in_production = true`, since it has no authentication of its own ([Security](docs/SECURITY.md#mcp-http-transport)). There is also a standalone HTTP process: `rails-ai-context serve --transport http --port 6029`.
|
|
243
|
+
|
|
244
|
+
**CLI** runs the same 45 tools with no server, in any terminal:
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
bin/rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
|
|
248
|
+
rails-ai-context tool schema --table users --detail full
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
About half the tools take `detail=summary|standard|full`.
|
|
230
252
|
|
|
231
253
|
## When the app can't boot
|
|
232
254
|
|
|
233
|
-
|
|
255
|
+
The app-reading commands try a full boot for live reflection. When boot fails (missing ENV vars, an unreachable service, a broken initializer) they fall back to the static tier instead of dying: routes from `config/routes.rb`, schema from `db/schema.rb`, `db/structure.sql` or migrations, models and controllers from their source. Every response carries a banner naming the degradation, static data is tagged `[STATIC]`, and a section that needs a booted app says `[UNAVAILABLE]` with the reason. `--no-boot` skips the attempt outright. `doctor` still needs a bootable app, since diagnosing the boot is its job.
|
|
256
|
+
|
|
257
|
+
Code is found in the conventional layout, in packwerk packs (`packs/*/app/*`), in in-repo engines (`engines/*/app/*`), and in any `extra_app_paths` from `.rails-ai-context.yml`. Details in [Compatibility](docs/COMPATIBILITY.md).
|
|
234
258
|
|
|
235
|
-
|
|
259
|
+
## Commands
|
|
260
|
+
|
|
261
|
+
| In the Gemfile | Standalone | What it does |
|
|
262
|
+
|:---|:---|:---|
|
|
263
|
+
| `bin/rails generate rails_ai_context:install` | `rails-ai-context init` | Set up (both take `--tools`, `--mcp`, `--cli`, `--mcp-only`, `--prune`, `--defaults`) |
|
|
264
|
+
| `bin/rails ai:serve` | `rails-ai-context serve` | Start the MCP server (stdio) |
|
|
265
|
+
| `bin/rails ai:serve_http` | `rails-ai-context serve --transport http` | Start the MCP server (HTTP) |
|
|
266
|
+
| `bin/rails 'ai:tool[NAME]'` | `rails-ai-context tool NAME` | Run one tool |
|
|
267
|
+
| `bin/rails ai:tool` | `rails-ai-context tool --list` | List the tools |
|
|
268
|
+
| `bin/rails ai:context` | `rails-ai-context context` | Regenerate the context files |
|
|
269
|
+
| `bin/rails ai:doctor` | `rails-ai-context doctor` | Diagnostics and a readiness score |
|
|
270
|
+
| `bin/rails ai:watch` | `rails-ai-context watch` | Regenerate on file change |
|
|
271
|
+
| `bin/rails 'ai:preset[NAME]'` | `rails-ai-context preset NAME` | Run a multi-tool preset (`architecture`, `debugging`, `migration`) |
|
|
272
|
+
| `bundle exec rails-ai-context uninstall` | `rails-ai-context uninstall` | Remove what the gem wrote, keep what you wrote |
|
|
273
|
+
| `bundle exec rails-ai-context mcp-entry` | `rails-ai-context mcp-entry` | Print an MCP entry for Claude Desktop, Windsurf, Zed and other clients |
|
|
274
|
+
|
|
275
|
+
The binary finds the app the way `bin/rails` does, so it runs from any subdirectory. Flags shared by the app-reading commands: `--app-path PATH` to target another directory, `--environment ENV` to set `RAILS_ENV`, and `--no-boot` to answer from source. Full list in the [CLI reference](docs/CLI.md).
|
|
236
276
|
|
|
237
|
-
|
|
277
|
+
> [!NOTE]
|
|
278
|
+
> These commands are for you. With MCP connected the assistant calls the same tools itself.
|
|
238
279
|
|
|
239
280
|
## Configuration
|
|
240
281
|
|
|
@@ -251,7 +292,10 @@ end
|
|
|
251
292
|
|
|
252
293
|
Standalone installs use the same keys in `.rails-ai-context.yml`. All options with defaults are in [Configuration](docs/CONFIGURATION.md).
|
|
253
294
|
|
|
254
|
-
|
|
295
|
+
<details>
|
|
296
|
+
<summary><b>Custom tools</b></summary>
|
|
297
|
+
|
|
298
|
+
<br>
|
|
255
299
|
|
|
256
300
|
Register your own tools next to the built-in ones:
|
|
257
301
|
|
|
@@ -282,7 +326,12 @@ assert_tool_response_includes(response, "Users")
|
|
|
282
326
|
|
|
283
327
|
See [Custom tools](docs/CUSTOM_TOOLS.md).
|
|
284
328
|
|
|
285
|
-
|
|
329
|
+
</details>
|
|
330
|
+
|
|
331
|
+
<details>
|
|
332
|
+
<summary><b>Observability</b></summary>
|
|
333
|
+
|
|
334
|
+
<br>
|
|
286
335
|
|
|
287
336
|
Every MCP call fires an `ActiveSupport::Notifications` event:
|
|
288
337
|
|
|
@@ -293,34 +342,27 @@ ActiveSupport::Notifications.subscribe("rails_ai_context.tools.call") do |event|
|
|
|
293
342
|
end
|
|
294
343
|
```
|
|
295
344
|
|
|
296
|
-
|
|
345
|
+
</details>
|
|
297
346
|
|
|
298
|
-
|
|
299
|
-
graph TD
|
|
300
|
-
A["Your Rails app\nmodels + schema + routes + controllers + views + jobs"] -->|"40 introspectors"| B
|
|
301
|
-
B["rails-ai-context\nPrism AST · cached · confidence-tagged\nstatic tier when the app can't boot"]
|
|
302
|
-
B --> C["MCP server\nstdio / HTTP\n45 tools · 5 templates · 9 resources"]
|
|
303
|
-
B --> D["CLI\nrake / Thor\nsame 45 tools"]
|
|
304
|
-
B --> E["Context files\nCLAUDE.md · .cursor/rules/ · .github/instructions/ · AGENTS.md"]
|
|
347
|
+
## Uninstall
|
|
305
348
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
style D fill:#00cec9,stroke:#00b5b0,color:#fff
|
|
310
|
-
style E fill:#a29bfe,stroke:#8c83f0,color:#fff
|
|
349
|
+
```bash
|
|
350
|
+
bundle exec rails-ai-context uninstall && bundle remove rails-ai-context # in the Gemfile
|
|
351
|
+
rails-ai-context uninstall # standalone
|
|
311
352
|
```
|
|
312
353
|
|
|
313
|
-
|
|
354
|
+
It removes the context files, the MCP entries, its config, its `.gitignore` lines and its pre-commit hook, and keeps what you wrote: your lines in `CLAUDE.md`, other servers in an MCP config, a hook you edited. Or paste the [uninstall prompt](docs/PROMPTS.md#uninstall).
|
|
314
355
|
|
|
315
356
|
## Documentation
|
|
316
357
|
|
|
317
358
|
| | |
|
|
318
359
|
|:---|:---|
|
|
360
|
+
| [Copy-paste prompts](docs/PROMPTS.md) | Let your AI tool install, change, remove or use the gem |
|
|
319
361
|
| [Quickstart](docs/QUICKSTART.md) | Up and running in 5 minutes |
|
|
362
|
+
| [AI tool setup](docs/SETUP.md) | Claude Code, Cursor, Copilot, OpenCode, Codex CLI, HTTP transport |
|
|
320
363
|
| [Guide](docs/GUIDE.md) | Every command, parameter and option |
|
|
321
364
|
| [Tools reference](docs/TOOLS.md) | All 45 tools with every parameter |
|
|
322
365
|
| [Recipes](docs/RECIPES.md) | Real workflows, end to end |
|
|
323
|
-
| [AI tool setup](docs/SETUP.md) | Claude Code, Cursor, Copilot, OpenCode, Codex CLI, HTTP transport |
|
|
324
366
|
| [CLI reference](docs/CLI.md) | Commands, flags and argument syntax |
|
|
325
367
|
| [Standalone](docs/STANDALONE.md) | Use without a Gemfile entry |
|
|
326
368
|
| [Configuration](docs/CONFIGURATION.md) | Every option with its default |
|
|
@@ -335,6 +377,8 @@ Internals, the introspector list and the AST engine are in [Architecture](docs/A
|
|
|
335
377
|
<div align="center">
|
|
336
378
|
<br>
|
|
337
379
|
|
|
380
|
+
**If it saves you a correction loop, [star it on GitHub](https://github.com/crisnahine/rails-ai-context).**
|
|
381
|
+
|
|
338
382
|
Built by a Rails developer with 10+ years in production. If it saves you time, consider [sponsoring the project](https://github.com/sponsors/crisnahine).
|
|
339
383
|
|
|
340
384
|
</div>
|