0.0
The project is in a healthy, maintained state
rails-agent-kit is a read-only Model Context Protocol (stdio) server for Rails apps. rails_schema returns tables, columns, indexes and foreign keys parsed statically from db/schema.rb (without booting the app); rails_routes returns every route from `bin/rails routes --expanded`. It also ships a Rails 8 conventions skill for Cursor and Claude Code, installed with `rails-agent-kit install-skills`.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

~> 1.8
 Project Readme

rails-agent-kit

Ground truth about your Rails app, for coding agents

A read-only MCP server that gives Cursor, Claude Code, Codex and other MCP clients your app's real schema and routes, plus a Rails 8 skill that tells the agent to check them before it writes code.

Documentation · Install · Connect your agent · Tools · Changelog · Roadmap

Gem Version Gem Downloads CI Ruby License: MIT

Note

rails-agent-kit is early (v0.3.0), and the API may change before 1.0. Using it? Tell us how it went in Discussions or open an issue.


Look it up instead of guessing

Agents writing Rails code guess all the time. Is it user.full_name or user.name? Is the column nullable? Is the helper post_comments_path or comments_path? Each wrong guess is broken code and another review round. rails-agent-kit lets the agent ask your app.

  • Stack: Rails and Ruby versions, database, test framework, auth, jobs, frontend and deploy tools in one small answer, read from Gemfile.lock and config files, so the agent uses what the app already uses.
  • Schema: tables, columns, indexes and foreign keys from db/schema.rb, parsed statically. It never boots the app or connects to a database. db/structure.sql gets a best-effort parse.
  • Schema overview and search: a compact overview by default, several tables in one call, and a name search across tables and columns, so large schemas don't flood the agent's context.
  • Routes: every route with its name, verb, path, controller#action and source line, from your app's own bin/rails routes --expanded. Engines and route concerns resolve exactly as Rails sees them.
  • The app's own Ruby: routes boot with the Ruby your app pins in .ruby-version, .tool-versions or mise.toml, found through mise, rbenv, asdf or chruby.
  • Routes without booting: point it at a saved routes dump, or run the routes command in Docker.
  • One-command setup: rails-agent-kit init connects Cursor, Claude Code, VS Code and Codex, and installs the skill.
  • Rails 8 conventions skill: an Agent Skill for Cursor and Claude Code, or a managed block in AGENTS.md (Codex and others), .github/copilot-instructions.md or GEMINI.md, installed with rails-agent-kit install-skills.
  • Read-only and local: a stdio server your client starts. It doesn't listen on a network port.

See what your agent sees

The agent calls the tools itself. These are real answers for the small blog app in test/fixtures/blog_app, pretty-printed (the server sends compact JSON).

// rails_schema {}  (the overview; trimmed)
{
  "source": "db/schema.rb",
  "table_count": 4,
  "tables": [
    { "name": "comments", "columns": 6, "references": ["posts", "users"] },
    { "name": "posts", "columns": 10, "references": ["users"] },
    { "name": "posts_tags", "columns": 2, "primary_key": false },
    { "name": "users", "columns": 7 }
  ]
}
// rails_schema { "search": "email" }  (trimmed)
{ "match_count": 1, "matches": [{ "table": "users", "columns": [{ "name": "email", "type": "string", "null": false }] }] }
// rails_schema { "table": "comments" }  (trimmed)
{
  "tables": [{
    "name": "comments",
    "columns": [
      { "name": "post_id", "type": "bigint", "null": false },
      { "name": "body", "type": "text", "null": false }
    ],
    "indexes": [{ "name": "index_comments_on_post_id", "columns": ["post_id"], "unique": false }]
  }],
  "foreign_keys": [{ "from_table": "comments", "to_table": "users", "column": "user_id", "on_delete": "cascade" }]
}
// rails_routes { "filter": "comments" }  (trimmed)
{
  "total": 7,
  "count": 2,
  "routes": [
    { "name": "post_comments", "verb": "POST", "path": "/posts/:post_id/comments(.:format)",
      "controller_action": "comments#create", "source_location": "config/routes.rb:3" }
  ]
}

Installation

gem install rails-agent-kit

or, inside your Rails app:

bundle add rails-agent-kit --group development

Requires Ruby 3.2+.

Connect your agent

One command

From your app's root:

bundle add rails-agent-kit --group development
bundle exec rails-agent-kit init

init writes the MCP config for Cursor (.cursor/mcp.json), Claude Code (.mcp.json) and VS Code (.vscode/mcp.json), using project-relative paths so you can commit the files for your whole team. It adds rails-agent-kit next to the servers you already have, picks bundle exec or the installed gem for you, installs the Rails 8 skill for Cursor and Claude Code, adds it to AGENTS.md for Codex, and prints the snippet for Codex's global ~/.codex/config.toml. Running it again changes nothing. Preview with --dry-run, or pick clients with --agent cursor,claude.

By hand

Replace /path/to/your/rails/app with the absolute path to your app.

Cursor

.cursor/mcp.json in your app (or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "rails-agent-kit": {
      "command": "rails-agent-kit",
      "args": ["--root", "/path/to/your/rails/app"]
    }
  }
}
Claude Code
claude mcp add rails-agent-kit -- rails-agent-kit --root /path/to/your/rails/app
Codex
codex mcp add rails-agent-kit -- rails-agent-kit --root /path/to/your/rails/app

or in ~/.codex/config.toml:

[mcp_servers.rails-agent-kit]
command = "rails-agent-kit"
args = ["--root", "/path/to/your/rails/app"]
Claude Desktop and other MCP clients

Any client that launches stdio MCP servers works. Claude Desktop's claude_desktop_config.json takes the same mcpServers block as Cursor above.

Installed with bundle add instead of gem install?

Run it through the app's bundle:

{
  "mcpServers": {
    "rails-agent-kit": {
      "command": "bundle",
      "args": ["exec", "rails-agent-kit", "--root", "/path/to/your/rails/app"],
      "env": { "BUNDLE_GEMFILE": "/path/to/your/rails/app/Gemfile" }
    }
  }
}
claude mcp add rails-agent-kit -e BUNDLE_GEMFILE=/path/to/your/rails/app/Gemfile \
  -- bundle exec rails-agent-kit --root /path/to/your/rails/app

To also add the Rails 8 conventions skill (optional), see Agent skill:

rails-agent-kit install-skills --root /path/to/your/rails/app                  # Cursor
rails-agent-kit install-skills --root /path/to/your/rails/app --agent claude   # Claude Code
rails-agent-kit install-skills --root /path/to/your/rails/app --agent codex    # AGENTS.md
rails-agent-kit install-skills --root /path/to/your/rails/app --agent copilot  # GitHub Copilot
rails-agent-kit install-skills --root /path/to/your/rails/app --agent gemini   # Gemini CLI

Tools

All three tools are read-only and return JSON.

Tool Parameters Returns Boots the app?
rails_project_info None Rails, Ruby and load_defaults versions, api_only, database adapter and databases, test framework and data, auth, authorization, jobs/cache/cable backends, frontend, serializers, lint and deploy tools, mounted engines, notable gems and key paths. Unknown values are null No. Reads Gemfile.lock and config files
rails_schema All optional. table: one exact name, an array or a comma-separated list. search: case-insensitive part of a table or column name. detail: overview or full With no arguments, a compact overview (each table's column count, non-default primary key and foreign key targets). With table, full columns (type, null, default, limit, …), indexes and foreign keys. With search, the matching tables and columns No. Parses db/schema.rb statically, with a best-effort fallback to db/structure.sql
rails_routes filter (optional, case-insensitive substring of name, path, verb or controller#action) Each route's name, verb, path, controller#action and source location Yes. Runs bin/rails routes --expanded. If that fails or times out, it explains why and returns the raw config/routes.rb

Responses are compact (single-line) JSON. Agents call rails_project_info first (about 1 KB), then usually rails_schema with no arguments, so that answer stays small even on large apps: a generated 300-table schema gives about 23 KB, where the full dump is over 1 MB. Any rails_schema answer over 60 KB comes back as the overview plus a note on how to narrow the request (truncated: true).

CLI reference

rails-agent-kit [--root PATH] [--routes-file FILE]       # start the MCP server on stdio
rails-agent-kit init [--root PATH] [--agent LIST] [--dry-run] [--force] [--no-skills]
rails-agent-kit install-skills [--root PATH] [--agent AGENT] [--force] [SKILL...]
rails-agent-kit --version
Option / env var Purpose
--root PATH Rails app root (default: the current directory)
--routes-file FILE Use a saved bin/rails routes --expanded dump instead of booting the app
RAILS_AGENT_KIT_ROUTES_TIMEOUT Seconds to wait for bin/rails routes (default 60)
RAILS_AGENT_KIT_ROUTES_COMMAND Override the routes command, e.g. "docker compose exec -T web bin/rails routes --expanded". Runs in --root

If your app can't boot locally (it needs a DB, secrets or Docker), dump the routes once and point the server at the file:

bin/rails routes --expanded > tmp/routes.txt
rails-agent-kit --root . --routes-file tmp/routes.txt

How it works

  • Transport: a stdio MCP server built on the official mcp Ruby SDK. Your agent client starts it and talks JSON-RPC over stdin/stdout. Nothing listens on a network port.
  • Schema: read from db/schema.rb with a static parser. It never loads your app or connects to a database, so it's fast and safe on any checkout. Apps that use db/structure.sql get a best-effort SQL parse.
  • Routes: generated by your app itself (bin/rails routes --expanded), so engines and route concerns resolve exactly as Rails sees them. It runs with the app's pinned Ruby and with Bundler's environment cleared, so the app uses its own Ruby and Gemfile.
  • Skill: a Markdown Agent Skill copied into your app. It tells the agent to call these tools before it writes model attributes, queries, URL helpers or migrations.

Agent skill: Rails 8 conventions

skills/rails-8-conventions/SKILL.md makes the agent check rails_project_info, rails_schema and rails_routes before it edits code. It then follows the Rails 8 defaults: params.expect, the built-in authentication generator, rate_limit, Solid Queue/Cache/Cable, Hotwire with importmap/Propshaft, reversible migrations, and tests in the framework the app already uses. It also covers a paired Next.js frontend.

There's one source for every agent. install-skills installs it where each agent looks:

--agent Writes Read by
cursor (default) .cursor/skills/<name>/SKILL.md Cursor
claude .claude/skills/<name>/SKILL.md Claude Code (and Cursor, Copilot)
codex A managed block in AGENTS.md Codex, Cursor, GitHub Copilot, Windsurf, Zed and other AGENTS.md readers
copilot A managed block in .github/copilot-instructions.md GitHub Copilot
gemini A managed block in GEMINI.md Gemini CLI

Running it again is safe. It never overwrites a skill file you've edited unless you pass --force. In AGENTS.md, copilot-instructions.md and GEMINI.md it only touches the text between <!-- rails-agent-kit:start --> and <!-- rails-agent-kit:end -->, appending the block if it isn't there yet, so the rest of your file stays yours.

Compatibility

Versions Status
Ruby 3.2, 3.3, 3.4, 4.0 Tested in CI (ruby-head runs too, allowed to fail)
Rails (db/schema.rb format) 8.0 Covered by test fixtures
Rails 7.2, 8.1 Expected to work, but not yet covered by CI (planned)
MCP clients Cursor, Claude Code, Codex, Claude Desktop, or any stdio MCP client Configuration shown above

The bundled skill targets Rails 8 conventions. On Rails 7.x, the tools work the same, but some skill advice (e.g. params.expect and Solid Queue defaults) won't apply.

Documentation

The full guide lives at afurm.github.io/rails-agent-kit: getting started, a page per tool with example output, the CLI reference, the agent skill and compatibility.

Connect your agent · Tools · CLI reference · Changelog · Roadmap · Releasing · Security

Community

Everyone taking part follows the Code of Conduct.

Contributing

Pull requests are welcome. Read CONTRIBUTING.md, then:

gh repo fork afurm/rails-agent-kit --clone && cd rails-agent-kit
bundle install
bundle exec rake test

License

MIT © Andrii Furmanets