rails-agent-kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4204d99ae173d2d33485290dabf6cd45f769bf718fee6d9abe5bc6de4783dbc4
+  data.tar.gz: 4b1697ce2c95405f50edfb4106ae145b8d6aa9c6957fa9be92c08749d1c591cf
+SHA512:
+  metadata.gz: b099152c12dc8939cdb776a0f582c2c6df5c36110a6e8c3af9607d42496505b1d6bba2d6492fcc060801add37c6e3bcbf53ab13d787ef8b8110deafbee3fa481
+  data.tar.gz: 7757d654bf17f8824a7d59168acbb9911fdf1086db0ab3ef1a85e3301da3a6727fa20b05345f81e966e57d2aa38754c15d34b7c27f357e52815fff64d64d9483

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-17
+
+### Added
+
+- An MCP stdio server (`rails-agent-kit`, built on the official `mcp` Ruby SDK) with two read-only tools:
+  - `rails_schema`: tables, columns, indexes and foreign keys. Parsed statically from `db/schema.rb` without
+    booting the app, with a best-effort fallback to `db/structure.sql`. Takes an optional `table` filter.
+  - `rails_routes`: verb, path, `controller#action` and name for each route, from `bin/rails routes --expanded`.
+    Takes an optional `filter`. Use `--routes-file` or `RAILS_AGENT_KIT_ROUTES_COMMAND` when the app can't boot
+    locally. If the routes command fails, the tool falls back to the raw `config/routes.rb`.
+- A Rails 8 conventions agent skill (`skills/rails-8-conventions/SKILL.md`) for Cursor and Claude Code.
+- `rails-agent-kit install-skills [--agent cursor|claude] [--force]`, which installs the bundled skills into an app.
+- CI on Ruby 3.2, 3.3 and 3.4.
+
+[Unreleased]: https://github.com/afurm/rails-agent-kit/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/afurm/rails-agent-kit/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrii Furmanets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,118 @@
+# rails-agent-kit
+
+A tiny [Model Context Protocol](https://modelcontextprotocol.io) server that gives coding agents
+(Cursor, Claude Code, …) **ground truth about your Rails app**: its database schema and its routes.
+
+> Status: early scaffold (v0.1.0). Not published to RubyGems yet — run it from source.
+
+## Why (the 30-second version)
+
+Agents writing Rails code constantly guess: *is it `user.full_name` or `user.name`? is the column nullable?
+is the helper `post_comments_path` or `comments_path`?* Wrong guesses become broken code and wasted review cycles.
+With rails-agent-kit the agent just asks:
+
+| Tool | What it returns | Boots the app? |
+| --- | --- | --- |
+| `rails_schema` | Tables, columns (type, null, default, limit, …), indexes, foreign keys. Optional `table` filter. | **No** — statically parses `db/schema.rb` (falls back to a best-effort `db/structure.sql` parse). |
+| `rails_routes` | Every route: name/prefix, verb, path, `controller#action`, source location. Optional `filter`. | Yes — runs `bin/rails routes --expanded` with the app's own bundle. If that fails or times out, it says why and returns the raw `config/routes.rb` instead. |
+
+Both tools are read-only. Output is JSON.
+
+## Install
+
+From source (today):
+
+```sh
+git clone https://github.com/afurm/rails-agent-kit
+cd rails-agent-kit
+bundle install
+# try it against an app:
+BUNDLE_GEMFILE=$PWD/Gemfile bundle exec rails-agent-kit --root /path/to/your/rails/app
+```
+
+Once released (not yet): `gem install rails-agent-kit`.
+
+Requires Ruby 3.2+. Runtime dependency: the official [`mcp`](https://github.com/modelcontextprotocol/ruby-sdk) Ruby SDK.
+
+## Usage
+
+```
+rails-agent-kit [--root PATH] [--routes-file FILE]
+
+  --root PATH          Rails app root (default: current directory)
+  --routes-file FILE   Use a saved `bin/rails routes --expanded` dump instead of booting the app
+```
+
+The server speaks MCP over stdio. Environment knobs:
+
+- `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. `"bundle exec rails routes --expanded"`
+  or `"docker compose exec -T web bin/rails routes --expanded"`. Runs in `--root`.
+
+If your app can't boot locally (needs a DB, secrets, Docker…), dump the routes once and point the server at the file:
+
+```sh
+bin/rails routes --expanded > tmp/routes.txt
+rails-agent-kit --root . --routes-file tmp/routes.txt
+```
+
+## MCP client config
+
+Replace the paths with absolute paths on your machine.
+
+**Cursor** — `.cursor/mcp.json` in your Rails app (or `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "rails-agent-kit": {
+      "command": "bundle",
+      "args": ["exec", "rails-agent-kit", "--root", "/path/to/your/rails/app"],
+      "env": { "BUNDLE_GEMFILE": "/path/to/rails-agent-kit/Gemfile" }
+    }
+  }
+}
+```
+
+**Claude Code**:
+
+```sh
+claude mcp add rails-agent-kit \
+  -e BUNDLE_GEMFILE=/path/to/rails-agent-kit/Gemfile \
+  -- bundle exec rails-agent-kit --root /path/to/your/rails/app
+```
+
+**Claude Desktop** — `claude_desktop_config.json` uses the same `mcpServers` block as Cursor above.
+
+`rails_routes` runs the app's `bin/rails` with Bundler's environment cleared, so your app uses its own Gemfile,
+not rails-agent-kit's.
+
+## Agent skill: Rails 8 conventions
+
+The gem bundles a [Cursor skill](https://cursor.com/docs/skills),
+[`skills/rails-8-conventions/SKILL.md`](skills/rails-8-conventions/SKILL.md). It tells the agent to check
+`rails_schema`, `rails_routes` and `Gemfile.lock` before it edits code, then follow 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. Install it into your app:
+
+```sh
+rails-agent-kit install-skills --root /path/to/your/rails/app                 # -> .cursor/skills/rails-8-conventions/SKILL.md
+rails-agent-kit install-skills --root /path/to/your/rails/app --agent claude  # -> .claude/skills/...
+```
+
+Running it again is safe. It won't overwrite a skill you've edited unless you pass `--force`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+Tests use small fixture apps in `test/fixtures` (a `schema.rb`, a `structure.sql`, captured `rails routes`
+output and a stand-in `bin/rails`), plus an end-to-end test that drives `exe/rails-agent-kit` over stdio JSON-RPC.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/exe/rails-agent-kit

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../lib/rails_agent_kit"
+
+if ARGV.first == "install-skills"
+  ARGV.shift
+  opts = { root: Dir.pwd, agent: "cursor", force: false }
+  skills_parser = OptionParser.new do |o|
+    o.banner = "Usage: rails-agent-kit install-skills [--root PATH] [--agent cursor|claude] [--force] [SKILL...]\n\n" \
+               "Copies the bundled agent skills into the app (e.g. .cursor/skills/<name>/SKILL.md)."
+    o.on("--root PATH", "Rails app root (default: current directory)") { |v| opts[:root] = v }
+    o.on("--agent AGENT", "cursor (default) or claude") { |v| opts[:agent] = v }
+    o.on("--force", "Overwrite skills you have edited locally") { opts[:force] = true }
+    o.on("-h", "--help", "Show this help") do
+      puts o
+      exit
+    end
+  end
+
+  begin
+    skills_parser.parse!(ARGV)
+    installer = RailsAgentKit::SkillInstaller.new(opts[:root], agent: opts[:agent], force: opts[:force])
+    results = ARGV.empty? ? installer.install : installer.install(ARGV)
+  rescue OptionParser::ParseError, RailsAgentKit::Error => e
+    warn "rails-agent-kit: #{e.message}"
+    exit 64
+  end
+  results.each do |r|
+    note = r.status == :skipped ? " (differs from bundled copy; use --force to overwrite)" : ""
+    puts "#{r.status.to_s.ljust(9)} #{r.path}#{note}"
+  end
+  exit 0
+end
+
+options = { root: Dir.pwd, routes_file: nil }
+parser = OptionParser.new do |o|
+  o.banner = "Usage: rails-agent-kit [--root PATH] [--routes-file FILE]\n" \
+             "       rails-agent-kit install-skills --help\n\n" \
+             "Starts an MCP server on stdio exposing the Rails app's schema and routes."
+  o.on("--root PATH", "Rails app root (default: current directory)") { |v| options[:root] = v }
+  o.on("--routes-file FILE", "Use a saved `bin/rails routes --expanded` dump instead of booting the app") { |v| options[:routes_file] = v }
+  o.on("-v", "--version", "Print version") do
+    puts RailsAgentKit::VERSION
+    exit
+  end
+  o.on("-h", "--help", "Show this help") do
+    puts o
+    exit
+  end
+end
+
+begin
+  parser.parse!(ARGV)
+rescue OptionParser::ParseError => e
+  warn e.message
+  warn parser
+  exit 64
+end
+
+root = File.expand_path(options[:root])
+unless File.directory?(root)
+  warn "rails-agent-kit: --root #{root} is not a directory"
+  exit 66
+end
+
+require_relative "../lib/rails_agent_kit/server"
+RailsAgentKit::Server.run_stdio(root: root, routes_file: options[:routes_file])

data/lib/rails_agent_kit/routes_inspector.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+require "shellwords"
+require "timeout"
+
+module RailsAgentKit
+  # Lists routes for the Rails app at `root`.
+  #
+  # Listing routes needs a booted app, so this shells out to
+  # `bin/rails routes --expanded` in the app's own bundle. When that is
+  # not possible (no bin/rails, boot error, timeout) it degrades gracefully:
+  # it says why and returns the raw config/routes.rb so the agent can still read it.
+  # A pre-generated routes dump can be supplied with `routes_file:` to skip booting.
+  class RoutesInspector
+    DEFAULT_TIMEOUT = 60
+
+    def initialize(root, routes_file: nil, timeout: nil, command: nil)
+      @root = File.expand_path(root)
+      @routes_file = routes_file && File.expand_path(routes_file, @root)
+      @timeout = (timeout || ENV.fetch("RAILS_AGENT_KIT_ROUTES_TIMEOUT", DEFAULT_TIMEOUT)).to_f
+      @command = command
+    end
+
+    def call(filter: nil)
+      output, source = fetch_output
+      routes = RoutesParser.parse(output)
+      if routes.empty?
+        return fallback("`#{source}` produced no parseable routes " \
+                        "(expected `bin/rails routes --expanded` output).")
+      end
+
+      matched = apply_filter(routes, filter)
+      { source: source, total: routes.size, count: matched.size, routes: matched }
+    rescue RoutesUnavailable => e
+      fallback(e.message)
+    end
+
+    class RoutesUnavailable < StandardError; end
+
+    private
+
+    def fetch_output
+      if @routes_file
+        raise RoutesUnavailable, "Routes file not found: #{@routes_file}" unless File.file?(@routes_file)
+
+        return [File.read(@routes_file), File.basename(@routes_file)]
+      end
+
+      cmd = @command || default_command
+      [run(cmd), cmd.join(" ")]
+    end
+
+    def default_command
+      custom = ENV.fetch("RAILS_AGENT_KIT_ROUTES_COMMAND", "").strip
+      return Shellwords.split(custom) unless custom.empty?
+
+      bin_rails = File.join(@root, "bin", "rails")
+      raise RoutesUnavailable, "No bin/rails found in #{@root}; cannot boot the app to list routes." unless File.file?(bin_rails)
+
+      [RbConfig.ruby, "bin/rails", "routes", "--expanded"]
+    end
+
+    def run(cmd)
+      with_app_env do
+        Open3.popen3(*cmd, chdir: @root, pgroup: true) do |stdin, stdout, stderr, wait|
+          stdin.close
+          out_reader = reader(stdout)
+          err_reader = reader(stderr)
+          unless wait.join(@timeout)
+            kill(wait.pid)
+            raise RoutesUnavailable, "`#{cmd.join(' ')}` timed out after #{@timeout.to_i}s while booting the app."
+          end
+          out = out_reader.value
+          err = err_reader.value
+          unless wait.value.success?
+            raise RoutesUnavailable, "`#{cmd.join(' ')}` failed (exit #{wait.value.exitstatus}): #{tail(err.empty? ? out : err)}"
+          end
+          out
+        end
+      end
+    rescue SystemCallError => e
+      raise RoutesUnavailable, "Could not run `#{cmd.join(' ')}`: #{e.message}"
+    end
+
+    # Run the app with its own Gemfile, not this gem's bundle.
+    def with_app_env(&block)
+      if defined?(Bundler) && Bundler.respond_to?(:with_unbundled_env)
+        Bundler.with_unbundled_env(&block)
+      else
+        yield
+      end
+    end
+
+    def reader(io)
+      Thread.new do
+        Thread.current.report_on_exception = false
+        io.read
+      rescue IOError
+        ""
+      end
+    end
+
+    # Kill the whole process group (bin/rails may spawn spring or other children).
+    def kill(pid)
+      Process.kill("TERM", -pid)
+      sleep 0.2
+      Process.kill("KILL", -pid)
+    rescue SystemCallError
+      nil
+    end
+
+    def tail(text, lines: 15)
+      text.to_s.lines.last(lines).join.strip
+    end
+
+    def apply_filter(routes, filter)
+      return routes if filter.nil? || filter.to_s.strip.empty?
+
+      needle = filter.to_s.downcase
+      routes.select do |r|
+        [r[:name], r[:path], r[:controller_action], r[:verb]].compact.any? { |v| v.downcase.include?(needle) }
+      end
+    end
+
+    def fallback(reason)
+      routes_rb = File.join(@root, "config", "routes.rb")
+      result = {
+        routes_unavailable: true,
+        message: "Could not list routes: #{reason} Falling back to the raw config/routes.rb " \
+                 "(no route expansion, helpers or engine routes). Tip: run " \
+                 "`bin/rails routes --expanded > tmp/routes.txt` and start the server with --routes-file tmp/routes.txt."
+      }
+      if File.file?(routes_rb)
+        result[:fallback_source] = "config/routes.rb"
+        result[:routes_rb] = File.read(routes_rb)
+      else
+        result[:message] += " config/routes.rb was not found either."
+      end
+      result
+    end
+  end
+end

data/lib/rails_agent_kit/routes_parser.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RailsAgentKit
+  # Parses the output of `bin/rails routes --expanded` (preferred) or the
+  # default table output of `bin/rails routes`.
+  class RoutesParser
+    HEADER = /\A--\[\s*Route\s+\d+\s*\]-*\s*\z/
+    FIELD  = /\A([^|]+?)\s*\|\s?(.*)\z/
+    KEYS = {
+      "Prefix" => :name,
+      "Verb" => :verb,
+      "URI" => :path,
+      "Controller#Action" => :action,
+      "Source Location" => :source_location
+    }.freeze
+
+    def self.parse(output)
+      new(output).parse
+    end
+
+    def initialize(output)
+      @output = output.to_s
+    end
+
+    TABLE_HEADER = /\A\s*Prefix\s+Verb\s+URI Pattern\s+Controller#Action/
+
+    def parse
+      lines = @output.lines.map(&:chomp)
+      header = lines.find { |l| TABLE_HEADER.match?(l) }
+      return parse_table(lines, header) if header && lines.none? { |l| HEADER.match?(l.strip) }
+
+      parse_expanded
+    end
+
+    private
+
+    def parse_table(lines, header)
+      verb_at = header.index("Verb")
+      uri_at = header.index("URI Pattern")
+      action_at = header.index("Controller#Action")
+      lines.drop(lines.index(header) + 1).filter_map do |line|
+        next if line.strip.empty? || line.length <= uri_at
+
+        # Long values can push later columns right, so split the tail on whitespace.
+        name = line[0...verb_at].strip
+        verb = line[verb_at...uri_at].strip
+        path, action = line[uri_at..].strip.split(/\s+/, 2)
+        next if path.nil? || !path.start_with?("/")
+
+        normalize({ name: name.empty? ? nil : name, verb: verb, path: path, action: action&.strip })
+      end
+    end
+
+    def parse_expanded
+      routes = []
+      current = nil
+      @output.each_line do |raw|
+        line = raw.chomp
+        if HEADER.match?(line.strip)
+          routes << current if current
+          current = {}
+        elsif current && (m = FIELD.match(line))
+          key = KEYS[m[1].strip] || m[1].strip.downcase.gsub(/\W+/, "_").to_sym
+          value = m[2].strip
+          current[key] = value.empty? ? nil : value
+        end
+      end
+      routes << current if current
+      routes.map { |r| normalize(r) }
+    end
+
+    def normalize(route)
+      route[:verb] = route[:verb].to_s.empty? ? nil : route[:verb]
+      if route[:action]&.include?("#")
+        controller, action = route[:action].split("#", 2)
+        route[:controller] = controller
+        route[:action] = action.split(/\s/).first
+        route[:controller_action] = "#{controller}##{route[:action]}"
+      end
+      route.compact
+    end
+  end
+end

data/lib/rails_agent_kit/schema_inspector.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RailsAgentKit
+  # Reads the schema of a Rails app at `root` without booting it.
+  # Prefers db/schema.rb, falls back to db/structure.sql.
+  class SchemaInspector
+    def initialize(root)
+      @root = File.expand_path(root)
+    end
+
+    # Returns a Hash with :source, :tables, ... or :error.
+    def call(table: nil)
+      schema_rb = File.join(@root, "db", "schema.rb")
+      structure_sql = File.join(@root, "db", "structure.sql")
+
+      result =
+        if File.file?(schema_rb)
+          SchemaParser.parse_file(schema_rb).to_h.merge(source: "db/schema.rb")
+        elsif File.file?(structure_sql)
+          StructureSqlParser.parse_file(structure_sql).merge(
+            source: "db/structure.sql",
+            note: "Parsed from db/structure.sql on a best-effort basis; column types are raw SQL and " \
+                  "foreign keys/constraints are not extracted. db/schema.rb gives more precise results."
+          )
+        else
+          return { error: "No db/schema.rb or db/structure.sql found under #{@root}. " \
+                          "Run `bin/rails db:schema:dump` in the app, or pass --root pointing at the Rails app." }
+        end
+
+      filter(result, table)
+    end
+
+    private
+
+    def filter(result, table)
+      return result if table.nil? || table.to_s.strip.empty?
+
+      tables = result[:tables].select { |t| t[:name] == table.to_s }
+      if tables.empty?
+        names = result[:tables].map { |t| t[:name] }
+        return { error: "Table #{table.inspect} not found in #{result[:source]}.", available_tables: names }
+      end
+
+      out = result.merge(tables: tables)
+      if out.key?(:foreign_keys)
+        out[:foreign_keys] = out[:foreign_keys].select { |fk| fk[:from_table] == table.to_s || fk[:to_table] == table.to_s }
+      end
+      out
+    end
+  end
+end

data/lib/rails_agent_kit/schema_parser.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module RailsAgentKit
+  # Parses db/schema.rb statically (no eval, no app boot) into tables, columns,
+  # indexes and foreign keys.
+  class SchemaParser
+    Result = Struct.new(:version, :extensions, :tables, :foreign_keys, keyword_init: true) do
+      def to_h
+        { version: version, extensions: extensions, tables: tables, foreign_keys: foreign_keys }
+      end
+    end
+
+    CREATE_TABLE = /\A\s*create_table\s+["']([^"']+)["'](?:\s*,\s*(.*?))?\s+do\s*\|(\w+)\|\s*\z/
+    COLUMN       = /\A\s*(\w+)\.(\w+)\s+["']([^"']+)["']\s*(?:,\s*(.*))?\z/
+    T_INDEX      = /\A\s*(\w+)\.index\s+(\[[^\]]*\]|["'][^"']*["'])\s*(?:,\s*(.*))?\z/
+    ADD_INDEX    = /\A\s*add_index\s+["']([^"']+)["']\s*,\s*(\[[^\]]*\]|["'][^"']*["'])\s*(?:,\s*(.*))?\z/
+    ADD_FK       = /\A\s*add_foreign_key\s+["']([^"']+)["']\s*,\s*["']([^"']+)["']\s*(?:,\s*(.*))?\z/
+    EXTENSION    = /\A\s*enable_extension\s+["']([^"']+)["']/
+    VERSION_RE   = /define\(\s*version:\s*([\d_]+)\s*\)/
+
+    def self.parse_file(path)
+      new(File.read(path)).parse
+    end
+
+    def initialize(source)
+      @source = source
+    end
+
+    def parse
+      tables = []
+      foreign_keys = []
+      extensions = []
+      version = @source[VERSION_RE, 1]&.delete("_")
+      current = nil
+      block_var = nil
+
+      @source.each_line do |raw|
+        line = strip_comment(raw).rstrip
+        next if line.strip.empty?
+
+        if current
+          if line.strip == "end"
+            tables << current
+            current = nil
+          elsif (m = T_INDEX.match(line)) && m[1] == block_var
+            current[:indexes] << build_index(current[:name], m[2], m[3])
+          elsif (m = COLUMN.match(line)) && m[1] == block_var
+            current[:columns] << build_column(m[2], m[3], m[4])
+          end
+          next
+        end
+
+        if (m = CREATE_TABLE.match(line))
+          opts = parse_options(m[2])
+          block_var = m[3]
+          current = { name: m[1], primary_key: primary_key_for(opts), columns: [], indexes: [] }
+          current[:comment] = opts[:comment] if opts[:comment]
+          if current[:primary_key]
+            current[:columns] << { name: current[:primary_key], type: id_type(opts), null: false, primary_key: true }
+          end
+        elsif (m = ADD_INDEX.match(line))
+          index = build_index(m[1], m[2], m[3])
+          table = tables.find { |t| t[:name] == m[1] }
+          table ? table[:indexes] << index : nil
+        elsif (m = ADD_FK.match(line))
+          opts = parse_options(m[3])
+          fk = { from_table: m[1], to_table: m[2] }
+          fk[:column] = opts[:column] || "#{singularize(m[2])}_id"
+          fk[:primary_key] = opts[:primary_key] if opts[:primary_key]
+          fk[:on_delete] = opts[:on_delete] if opts[:on_delete]
+          fk[:on_update] = opts[:on_update] if opts[:on_update]
+          fk[:name] = opts[:name] if opts[:name]
+          foreign_keys << fk
+        elsif (m = EXTENSION.match(line))
+          extensions << m[1]
+        end
+      end
+
+      Result.new(version: version, extensions: extensions, tables: tables, foreign_keys: foreign_keys)
+    end
+
+    private
+
+    def build_column(type, name, opts_src)
+      opts = parse_options(opts_src)
+      col = { name: name, type: type, null: opts.key?(:null) ? opts[:null] : true }
+      %i[default limit precision scale array comment].each { |k| col[k] = opts[k] if opts.key?(k) }
+      col
+    end
+
+    def build_index(table, cols_src, opts_src)
+      opts = parse_options(opts_src)
+      columns = parse_value(cols_src)
+      index = { table: table, name: opts[:name], columns: Array(columns), unique: opts[:unique] == true }
+      %i[where using order].each { |k| index[k] = opts[k] if opts.key?(k) }
+      index
+    end
+
+    def primary_key_for(opts)
+      return nil if opts[:id] == false
+      return nil if opts[:primary_key].is_a?(Array)
+
+      opts[:primary_key] || "id"
+    end
+
+    def id_type(opts)
+      case opts[:id]
+      when nil, true then "bigint"
+      else opts[:id].to_s
+      end
+    end
+
+    def singularize(word)
+      if word.end_with?("ies") then word[0..-4] + "y"
+      elsif word.end_with?("ses") then word[0..-3]
+      elsif word.end_with?("s") then word[0..-2]
+      else word
+      end
+    end
+
+    # Removes a trailing `# comment` that is not inside a string literal.
+    def strip_comment(line)
+      in_str = nil
+      line.each_char.with_index do |ch, i|
+        if in_str
+          in_str = nil if ch == in_str && line[i - 1] != "\\"
+        elsif ch == '"' || ch == "'"
+          in_str = ch
+        elsif ch == "#"
+          return line[0...i]
+        end
+      end
+      line
+    end
+
+    # Parses `key: value, key2: value2` into a symbol-keyed hash.
+    def parse_options(src)
+      return {} if src.nil? || src.strip.empty?
+
+      split_top_level(src).each_with_object({}) do |part, h|
+        if (m = part.match(/\A\s*(\w+):\s*(.*)\z/m))
+          h[m[1].to_sym] = parse_value(m[2].strip)
+        elsif (m = part.match(/\A\s*["'](\w+)["']\s*=>\s*(.*)\z/m))
+          h[m[1].to_sym] = parse_value(m[2].strip)
+        end
+      end
+    end
+
+    def parse_value(src)
+      s = src.strip
+      case s
+      when "true" then true
+      when "false" then false
+      when "nil" then nil
+      when /\A-?\d+\z/ then s.to_i
+      when /\A-?\d+\.\d+\z/ then s.to_f
+      when /\A"(.*)"\z/m then Regexp.last_match(1).gsub('\\"', '"')
+      when /\A'(.*)'\z/m then Regexp.last_match(1)
+      when /\A:(\w+)\z/ then Regexp.last_match(1)
+      when /\A\[(.*)\]\z/m then split_top_level(Regexp.last_match(1)).map { |v| parse_value(v) }
+      else s # lambdas (-> { "now()" }), constants, etc. are kept verbatim
+      end
+    end
+
+    def split_top_level(src)
+      parts = []
+      depth = 0
+      in_str = nil
+      buf = +""
+      src.each_char.with_index do |ch, i|
+        if in_str
+          in_str = nil if ch == in_str && src[i - 1] != "\\"
+          buf << ch
+          next
+        end
+        case ch
+        when '"', "'" then in_str = ch
+        when "[", "{", "(" then depth += 1
+        when "]", "}", ")" then depth -= 1
+        when ","
+          if depth.zero?
+            parts << buf
+            buf = +""
+            next
+          end
+        end
+        buf << ch
+      end
+      parts << buf unless buf.strip.empty?
+      parts.map(&:strip)
+    end
+  end
+end

data/lib/rails_agent_kit/server.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require "mcp"
+
+module RailsAgentKit
+  # Builds the MCP server (official `mcp` Ruby SDK) exposing the app's schema and routes.
+  module Server
+    module_function
+
+    def build(root:, routes_file: nil)
+      context = { root: File.expand_path(root), routes_file: routes_file }
+      MCP::Server.new(
+        name: "rails-agent-kit",
+        version: RailsAgentKit::VERSION,
+        instructions: "Ground truth about the Rails app at #{context[:root]}: use rails_schema for tables/columns/indexes " \
+                      "and rails_routes for HTTP routes before guessing model attributes or URL helpers.",
+        tools: [Tools::RailsSchema, Tools::RailsRoutes],
+        server_context: context
+      )
+    end
+
+    def run_stdio(root:, routes_file: nil)
+      server = build(root: root, routes_file: routes_file)
+      MCP::Server::Transports::StdioTransport.new(server).open
+    end
+  end
+
+  module Tools
+    # Shared helpers for tool classes.
+    module Helpers
+      def context_value(server_context, key)
+        server_context.respond_to?(:[]) ? server_context[key] : nil
+      end
+
+      def json_response(data, error: false)
+        MCP::Tool::Response.new([{ type: "text", text: JSON.pretty_generate(data) }], error: error)
+      end
+    end
+
+    class RailsSchema < MCP::Tool
+      extend Helpers
+
+      tool_name "rails_schema"
+      description "Database schema of the Rails app (tables, columns with types/null/default, indexes, foreign keys), " \
+                  "parsed from db/schema.rb (or db/structure.sql) without booting the app."
+      input_schema(
+        properties: {
+          table: { type: "string", description: "Only return this table (exact name). Omit for all tables." }
+        }
+      )
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+
+      def self.call(server_context:, table: nil)
+        root = context_value(server_context, :root) || Dir.pwd
+        result = SchemaInspector.new(root).call(table: table)
+        json_response(result, error: result.key?(:error))
+      end
+    end
+
+    class RailsRoutes < MCP::Tool
+      extend Helpers
+
+      tool_name "rails_routes"
+      description "HTTP routes of the Rails app (verb, path, controller#action, route name). Runs " \
+                  "`bin/rails routes --expanded` (boots the app); if that fails it explains why and returns config/routes.rb."
+      input_schema(
+        properties: {
+          filter: { type: "string", description: "Case-insensitive substring matched against name, path, verb and controller#action." }
+        }
+      )
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+
+      def self.call(server_context:, filter: nil)
+        root = context_value(server_context, :root) || Dir.pwd
+        routes_file = context_value(server_context, :routes_file)
+        json_response(RoutesInspector.new(root, routes_file: routes_file).call(filter: filter))
+      end
+    end
+  end
+end

data/lib/rails_agent_kit/skill_installer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RailsAgentKit
+  # Copies the agent skills bundled with the gem (skills/<name>/SKILL.md) into a Rails app,
+  # e.g. <root>/.cursor/skills/<name>/SKILL.md for Cursor.
+  class SkillInstaller
+    SKILLS_DIR = File.expand_path("../../skills", __dir__)
+    TARGETS = {
+      "cursor" => ".cursor/skills",
+      "claude" => ".claude/skills"
+    }.freeze
+
+    Result = Struct.new(:skill, :path, :status, keyword_init: true)
+
+    def self.available_skills
+      Dir.glob(File.join(SKILLS_DIR, "*", "SKILL.md")).map { |f| File.basename(File.dirname(f)) }.sort
+    end
+
+    def initialize(root, agent: "cursor", force: false)
+      @root = File.expand_path(root)
+      @agent = agent.to_s
+      @force = force
+      raise Error, "unknown agent #{@agent.inspect} (supported: #{TARGETS.keys.join(', ')})" unless TARGETS.key?(@agent)
+    end
+
+    # Installs the named skills (default: all bundled skills). Existing files that differ are left
+    # untouched unless force: true. Returns one Result per skill with status :created, :updated,
+    # :unchanged or :skipped.
+    def install(skills = self.class.available_skills)
+      skills.map do |name|
+        source = File.join(SKILLS_DIR, name, "SKILL.md")
+        raise Error, "unknown skill #{name.inspect} (available: #{self.class.available_skills.join(', ')})" unless File.file?(source)
+
+        install_one(name, source)
+      end
+    end
+
+    private
+
+    def install_one(name, source)
+      dest = File.join(@root, TARGETS.fetch(@agent), name, "SKILL.md")
+      content = File.read(source)
+      status =
+        if !File.exist?(dest) then :created
+        elsif File.read(dest) == content then :unchanged
+        elsif @force then :updated
+        else :skipped
+        end
+
+      if %i[created updated].include?(status)
+        FileUtils.mkdir_p(File.dirname(dest))
+        File.write(dest, content)
+      end
+      Result.new(skill: name, path: dest, status: status)
+    end
+  end
+end

data/lib/rails_agent_kit/structure_sql_parser.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RailsAgentKit
+  # Best-effort parser for db/structure.sql (CREATE TABLE / CREATE INDEX).
+  # SQL dumps vary a lot between adapters, so results are approximate.
+  class StructureSqlParser
+    CREATE_TABLE = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?((?:[\w"`]+\.)?[\w"`]+)\s*\((.*?)\)\s*;/mi
+    CREATE_INDEX = /CREATE\s+(UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?([\w"`]+)\s+ON\s+((?:[\w"`]+\.)?[\w"`]+)(?:\s+USING\s+\w+)?\s*\((.*?)\)\s*(?:WHERE\s+(.*?))?;/mi
+    CONSTRAINT_WORDS = /\A(CONSTRAINT|PRIMARY|FOREIGN|UNIQUE|CHECK|KEY|INDEX|EXCLUDE)\b/i
+
+    def self.parse_file(path)
+      new(File.read(path)).parse
+    end
+
+    def initialize(source)
+      @source = source.gsub(/--[^\n]*/, "")
+    end
+
+    def parse
+      tables = @source.scan(CREATE_TABLE).map do |name, body|
+        columns = split_columns(body).filter_map do |defn|
+          next if defn.match?(CONSTRAINT_WORDS)
+
+          m = defn.match(/\A([\w"`]+)\s+(.+)\z/m) or next
+          rest = m[2]
+          type = rest.sub(/\s+(NOT\s+NULL|NULL|DEFAULT|PRIMARY|REFERENCES|UNIQUE|CHECK|COLLATE|GENERATED|CONSTRAINT|AUTO_INCREMENT)\b.*\z/mi, "").strip
+          {
+            name: unquote(m[1]),
+            type: type,
+            null: !rest.match?(/NOT\s+NULL/i) && !rest.match?(/PRIMARY\s+KEY/i),
+            primary_key: rest.match?(/PRIMARY\s+KEY/i) || nil
+          }.compact
+        end
+        { name: unquote(name.split(".").last), columns: columns, indexes: [] }
+      end
+
+      @source.scan(CREATE_INDEX).each do |unique, idx_name, table, cols, where|
+        t = tables.find { |tt| tt[:name] == unquote(table.split(".").last) }
+        next unless t
+
+        idx = { table: t[:name], name: unquote(idx_name), columns: cols.split(",").map { |c| unquote(c.strip.split(/\s+/).first) }, unique: !unique.nil? }
+        idx[:where] = where.strip if where
+        t[:indexes] << idx
+      end
+
+      { tables: tables }
+    end
+
+    private
+
+    def unquote(s)
+      s.to_s.delete('"`')
+    end
+
+    def split_columns(body)
+      parts = []
+      depth = 0
+      buf = +""
+      body.each_char do |ch|
+        depth += 1 if ch == "("
+        depth -= 1 if ch == ")"
+        if ch == "," && depth.zero?
+          parts << buf.strip
+          buf = +""
+        else
+          buf << ch
+        end
+      end
+      parts << buf.strip unless buf.strip.empty?
+      parts
+    end
+  end
+end

data/lib/rails_agent_kit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsAgentKit
+  VERSION = "0.1.0"
+end

data/lib/rails_agent_kit.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "rails_agent_kit/version"
+require_relative "rails_agent_kit/schema_parser"
+require_relative "rails_agent_kit/structure_sql_parser"
+require_relative "rails_agent_kit/schema_inspector"
+require_relative "rails_agent_kit/routes_parser"
+require_relative "rails_agent_kit/routes_inspector"
+require_relative "rails_agent_kit/skill_installer"
+
+# Gives coding agents ground truth about a Rails app (schema, routes) over MCP.
+module RailsAgentKit
+  class Error < StandardError; end
+
+  # The MCP server is loaded lazily so the parsers can be used without the `mcp` gem.
+  def self.server(root: Dir.pwd)
+    require_relative "rails_agent_kit/server"
+    Server.build(root: root)
+  end
+end

data/skills/rails-8-conventions/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: rails-8-conventions
+description: Rails 8 conventions and a ground-truth-first workflow. Use when adding or changing models, migrations, controllers, routes, views, jobs, mailers or tests in a Rails 8 app, so changes follow the app's actual schema, routes and stack instead of guesses.
+paths:
+  - "app/**"
+  - "config/**"
+  - "db/**"
+  - "lib/**"
+  - "test/**"
+  - "spec/**"
+  - "Gemfile"
+metadata:
+  source: rails-agent-kit
+---
+
+# Rails 8 conventions
+
+Follow the app as it is, not Rails as you remember it. Check the facts first, then
+change the code the way this app already does things.
+
+## 1. Check the facts before you edit
+
+- **Schema:** call the `rails_schema` MCP tool (pass `table:` to get one table) before
+  you write a model attribute, query, validation, fixture or migration. Without the
+  tool, read `db/schema.rb` (or `db/structure.sql`). Never guess a column name, type,
+  nullability or default.
+- **Routes:** call the `rails_routes` MCP tool (pass `filter:`) before you use a
+  `*_path`/`*_url` helper, link, form `url:` or redirect. Without it, read
+  `config/routes.rb` or run `bin/rails routes -g <term>`.
+- **Stack:** read `Gemfile.lock` before you pick a library. Use what the app already
+  uses (RSpec or Minitest, Sidekiq or Solid Queue, Pundit, Devise or the built-in
+  auth generator, importmap or jsbundling). Don't add a gem when the app or Rails
+  already covers it.
+- **Local patterns:** before you add a model, controller or job, open one or two
+  nearby files and copy their structure: concerns, base classes, naming, and how
+  they render and respond.
+
+## 2. Rails 8 defaults (unless the Gemfile says otherwise)
+
+- **Strong params:** use `params.expect(post: [:title, :body])` (Rails 8). It returns
+  400 on a malformed payload instead of raising a 500. Use
+  `params.require(...).permit(...)` only if the codebase still uses it.
+- **Authentication:** `bin/rails generate authentication` gives you the `Session`
+  model, the `Authentication` concern, `Current.user`, `allow_unauthenticated_access`
+  and `require_authentication`. Use these when they're present. Don't add Devise
+  alongside them.
+- **Rate limiting:** `rate_limit to: 10, within: 3.minutes, only: :create` in the
+  controller. You don't need Rack::Attack for simple cases.
+- **Models:** `enum :status, { draft: 0, published: 1 }` (keyword-arg form),
+  `normalizes :email, with: ->(e) { e.strip.downcase }`, `generates_token_for`,
+  `has_secure_password`. Put validations in the model *and* constraints in the DB:
+  `null: false`, unique indexes, foreign keys.
+- **Background jobs:** Solid Queue is the default (`config/queue.yml`). Recurring
+  work goes in `config/recurring.yml`, not cron. Inherit from `ApplicationJob`, pass
+  records or ids (GlobalID), and make `perform` idempotent. Use `perform_later`.
+  Call `perform_now` only in tests or consoles.
+- **Cache and Cable:** Solid Cache and Solid Cable are database-backed and may use
+  their own databases (`db/cache_schema.rb`, `db/queue_schema.rb`,
+  `db/cable_schema.rb`). Don't move them to Redis on your own.
+- **Frontend:** Hotwire is the default. Use Turbo Frames/Streams for partial updates
+  and Stimulus controllers in `app/javascript/controllers`. Assets go through
+  Propshaft, and JS through importmap (`bin/importmap pin <pkg>`) unless the app uses
+  jsbundling. Don't add a SPA framework into `app/`.
+- **Deploy:** Kamal 2 (`config/deploy.yml`) and Thruster. Secrets live in
+  `config/credentials` or `.kamal/secrets`, never in code.
+
+## 3. Migrations
+
+- Generate them: `bin/rails generate migration AddPublishedAtToPosts published_at:datetime:index`.
+  Never hand-pick a timestamp.
+- Make them reversible (`change`, or `up`/`down`), and add indexes and foreign keys
+  (`t.references :user, null: false, foreign_key: true`).
+- Never edit a migration that has already run on a shared branch. Add a new one.
+- Run `bin/rails db:migrate` and commit the updated `db/schema.rb` (or
+  `structure.sql`) with the migration. After that, `rails_schema` is the source of
+  truth.
+
+## 4. Controllers, routes and views
+
+- Prefer RESTful `resources` with the seven standard actions. When you need a custom
+  action, add a nested resource or a new controller instead
+  (`resource :publication, only: :create`).
+- Keep controllers thin: load, authorize, call the model, respond. Make
+  `before_action :set_post` match the existing style.
+- Respond to `format.html` and `format.turbo_stream` when the app uses Turbo. On a
+  failed form submit, render with `status: :unprocessable_entity`. Use
+  `redirect_to ..., status: :see_other` after a destroy.
+- Use the route helpers confirmed in step 1. Don't hard-code a URL string.
+
+## 5. Tests
+
+- Use the existing framework: `test/` (Minitest, fixtures) or `spec/` (RSpec,
+  factories). Don't add a second one.
+- Add or update a test with every behaviour change: model tests for validations and
+  scopes, request/integration tests for endpoints, job tests for jobs.
+- Run the narrowest test first (`bin/rails test test/models/post_test.rb`), then the
+  suite (`bin/rails test`, or `bin/rails test:all` with system tests). Run
+  `bin/rubocop` if it exists.
+
+## 6. Paired Next.js frontend (if there is one)
+
+If the Rails app is an API for a separate Next.js app (`config.api_only = true`, JSON
+controllers, a sibling `web/` or `frontend/` directory):
+
+- Treat JSON responses as a contract. Add fields rather than rename or remove them,
+  and update the Next.js types and fetchers in the same change.
+- Check `rails_routes` for the exact path and verb before you write a fetch call
+  on the frontend.
+- Keep CORS (`config/initializers/cors.rb`) and auth (cookie vs token) consistent
+  with what the frontend already does.
+
+## Before you finish
+
+- [ ] Every column, table and route helper you used is confirmed by `rails_schema` or `rails_routes` (or the files behind them).
+- [ ] Migrations are reversible and `db/schema.rb` is updated.
+- [ ] Tests were added or updated, and they pass.
+- [ ] You added no new gem or framework that the app's existing stack already covers.

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: rails-agent-kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrii Furmanets
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: rails-agent-kit is a small Model Context Protocol (stdio) server. It
+  exposes a Rails app's database schema (parsed from db/schema.rb without booting
+  the app) and its routes to coding agents such as Cursor and Claude Code, and ships
+  a Rails 8 conventions skill for Cursor/Claude (installed with `rails-agent-kit install-skills`).
+executables:
+- rails-agent-kit
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/rails-agent-kit
+- lib/rails_agent_kit.rb
+- lib/rails_agent_kit/routes_inspector.rb
+- lib/rails_agent_kit/routes_parser.rb
+- lib/rails_agent_kit/schema_inspector.rb
+- lib/rails_agent_kit/schema_parser.rb
+- lib/rails_agent_kit/server.rb
+- lib/rails_agent_kit/skill_installer.rb
+- lib/rails_agent_kit/structure_sql_parser.rb
+- lib/rails_agent_kit/version.rb
+- skills/rails-8-conventions/SKILL.md
+homepage: https://github.com/afurm/rails-agent-kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/afurm/rails-agent-kit
+  source_code_uri: https://github.com/afurm/rails-agent-kit
+  changelog_uri: https://github.com/afurm/rails-agent-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/afurm/rails-agent-kit/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: MCP server and agent skills that give coding agents ground truth about a
+  Rails app's schema and routes.
+test_files: []