rails-ai-context 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 994a7f4531e3c387086796826815f5b4489107ec50b47d8bd86e46fa208d59ee
+  data.tar.gz: 11dd7dae7425c70d1bff80a43a183b66b4a0863fffa72d2d227093f5d1928b30
+SHA512:
+  metadata.gz: 733527414a221eb42d66510eeeeead2d46ec69482998bd79c2b913c87cf34b37ec23160b0a44b22a07689aae7ae1f3bef37094e836c2a2a18b992d7d3620f294
+  data.tar.gz: 1c4dfeb48b4a521631ae339de511dfe62ce2119c19fc8b50bfcee6fa3e8112632652f053e6040b4aa46bbf7ef47db352a90e41ff8dcc882631cb308c1638fa34

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,23 @@
+require:
+  - rubocop-rails-omakase
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Exclude:
+    - "spec/fixtures/**/*"
+    - "vendor/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Initial release
+- Schema introspection (live DB + static schema.rb fallback)
+- Model introspection (associations, validations, scopes, enums, callbacks, concerns)
+- Route introspection (HTTP verbs, paths, controller actions, API namespaces)
+- Job introspection (ActiveJob, mailers, Action Cable channels)
+- Gem analysis (40+ notable gems mapped to categories with explanations)
+- Convention detection (architecture style, design patterns, directory structure)
+- 6 MCP tools: `rails_get_schema`, `rails_get_routes`, `rails_get_model_details`, `rails_get_gems`, `rails_search_code`, `rails_get_conventions`
+- Context file generation: CLAUDE.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md, JSON
+- Rails Engine with Railtie auto-setup
+- Install generator (`rails generate rails_ai_context:install`)
+- Rake tasks: `ai:context`, `ai:serve`, `ai:serve_http`, `ai:inspect`
+- CLI executable: `rails-ai-context serve|context|inspect`
+- Stdio + Streamable HTTP transport support via official mcp SDK
+- CI matrix: Ruby 3.2/3.3/3.4 × Rails 7.1/7.2/8.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Cris
+
+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,212 @@
+# rails-ai-context
+
+**Turn any Rails app into an AI-ready codebase — one gem install.**
+
+[![Gem Version](https://badge.fury.io/rb/rails-ai-context.svg)](https://rubygems.org/gems/rails-ai-context)
+[![CI](https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml/badge.svg)](https://github.com/crisnahine/rails-ai-context/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+`rails-ai-context` automatically introspects your Rails application and exposes your models, routes, schema, jobs, gems, and conventions to AI assistants through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
+
+**Your AI assistant instantly understands your entire Rails app. No configuration. No manual tool definitions. Just `bundle add` and go.**
+
+---
+
+## The Problem
+
+You open Claude Code, Cursor, or Copilot in your Rails project and ask: *"Add a draft status to posts with a scheduled publish date."*
+
+The AI doesn't know your schema. It doesn't know you use Devise for auth, Sidekiq for jobs, or that Post already has an `enum :status`. It generates generic code that doesn't match your app's patterns.
+
+## The Solution
+
+```bash
+bundle add rails-ai-context
+```
+
+That's it. Now your AI assistant knows:
+
+- 📦 **Every table, column, index, and foreign key** in your database
+- 🏗️ **Every model** with its associations, validations, scopes, enums, and callbacks
+- 🛤️ **Every route** with HTTP verbs, paths, and controller actions
+- ⚡ **Every background job**, mailer, and Action Cable channel
+- 💎 **Every notable gem** and what it means (Devise → auth, Sidekiq → jobs, Turbo → Hotwire)
+- 🏛️ **Your architecture patterns**: service objects, STI, polymorphism, state machines, multi-tenancy
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+bundle add rails-ai-context
+rails generate rails_ai_context:install
+```
+
+### 2. Generate Context Files
+
+```bash
+rails ai:context
+```
+
+This creates:
+- `CLAUDE.md` — for Claude Code
+- `.cursorrules` — for Cursor
+- `.windsurfrules` — for Windsurf
+- `.github/copilot-instructions.md` — for GitHub Copilot
+
+**Commit these files.** Your entire team gets smarter AI assistance.
+
+### 3. Start the MCP Server
+
+For Claude Code / Cursor / any MCP client:
+
+```bash
+rails ai:serve
+```
+
+Or add to your Claude Code config (`~/.claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "my-rails-app": {
+      "command": "bundle",
+      "args": ["exec", "rails", "ai:serve"],
+      "cwd": "/path/to/your/rails/app"
+    }
+  }
+}
+```
+
+---
+
+## MCP Tools
+
+The gem exposes 6 tools via MCP that AI clients can call:
+
+| Tool | Description | Annotations |
+|------|-------------|-------------|
+| `rails_get_schema` | Database schema: tables, columns, indexes, FKs | read-only, idempotent |
+| `rails_get_routes` | All routes with HTTP verbs and controller actions | read-only, idempotent |
+| `rails_get_model_details` | Model associations, validations, scopes, enums, callbacks | read-only, idempotent |
+| `rails_get_gems` | Notable gems categorized by function with explanations | read-only, idempotent |
+| `rails_search_code` | Ripgrep-powered code search across the codebase | read-only, idempotent |
+| `rails_get_conventions` | Architecture patterns, directory structure, config files | read-only, idempotent |
+
+All tools are **read-only** — they never modify your application or database.
+
+---
+
+## How It Works
+
+```
+┌─────────────────────────────────────────┐
+│            Your Rails App               │
+│                                         │
+│  models/  routes  schema  jobs  gems    │
+│     │        │       │      │     │     │
+│     └────────┴───────┴──────┴─────┘     │
+│                  │                       │
+│         ┌───────┴────────┐              │
+│         │  Introspector  │              │
+│         └───────┬────────┘              │
+│                 │                        │
+│    ┌────────────┼────────────┐          │
+│    ▼            ▼            ▼          │
+│  CLAUDE.md   MCP Server   .cursorrules  │
+│  (static)   (live tools)   (static)     │
+└─────────────────────────────────────────┘
+         │            │
+         ▼            ▼
+    Claude Code    Cursor / Windsurf /
+    (reads file)   any MCP client
+```
+
+**Two modes:**
+1. **Static files** (`rails ai:context`) — generates markdown files that AI tools read as project context. Zero runtime cost. Works everywhere.
+2. **MCP server** (`rails ai:serve`) — live introspection tools that AI clients call on-demand. Richer, always up-to-date.
+
+---
+
+## Configuration
+
+```ruby
+# config/initializers/rails_ai_context.rb
+RailsAiContext.configure do |config|
+  # Exclude internal models from introspection
+  config.excluded_models += %w[AdminUser InternalAuditLog]
+
+  # Exclude paths from code search
+  config.excluded_paths += %w[vendor/bundle]
+
+  # Auto-mount HTTP MCP endpoint (for remote AI clients)
+  config.auto_mount = true
+  config.http_path  = "/mcp"
+  config.http_port  = 6029
+end
+```
+
+---
+
+## Rake Tasks
+
+| Command | Description |
+|---------|-------------|
+| `rails ai:context` | Generate all context files (CLAUDE.md, .cursorrules, etc.) |
+| `rails ai:context_for[claude]` | Generate for a specific format |
+| `rails ai:serve` | Start MCP server (stdio, for Claude Code) |
+| `rails ai:serve_http` | Start MCP server (HTTP, for remote clients) |
+| `rails ai:inspect` | Print introspection summary to stdout |
+
+---
+
+## Works Without a Database
+
+The gem gracefully degrades when no database is connected — it parses `db/schema.rb` as text. This means it works in:
+
+- CI environments
+- Claude Code sessions (no DB running)
+- Docker build stages
+- Any environment where you have the source code but not a running database
+
+---
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 7.1
+- [mcp](https://github.com/modelcontextprotocol/ruby-sdk) (official MCP SDK, installed automatically)
+
+---
+
+## vs. Other Ruby MCP Projects
+
+| Project | What it does | How rails-ai-context differs |
+|---------|-------------|------------------------------|
+| [Official Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk) | Low-level MCP protocol library | We **use** this as our foundation |
+| [fast-mcp](https://github.com/yjacquin/fast-mcp) | Generic Ruby MCP framework | We're a **product**, not a framework — zero-config Rails introspection |
+| [rails-mcp-server](https://github.com/maquina-app/rails-mcp-server) | Rails MCP server with manual config | We auto-discover everything, no `projects.yml` needed |
+| [mcp_on_ruby](https://github.com/rubyonai/mcp_on_ruby) | MCP server with manual tool definitions | We auto-generate tools from your app's structure |
+
+**rails-ai-context is not another MCP SDK.** It's a product that gives your Rails app AI superpowers with one `bundle add`.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/crisnahine/rails-ai-context.git
+cd rails-ai-context
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests welcome at https://github.com/crisnahine/rails-ai-context.
+
+## License
+
+[MIT License](LICENSE)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/rails-ai-context

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "thor"
+
+module RailsAiContext
+  class CLI < Thor
+    desc "serve", "Start MCP server (stdio transport)"
+    option :transport, type: :string, default: "stdio", desc: "Transport: stdio or http"
+    option :port, type: :numeric, default: 6029, desc: "HTTP port (only for http transport)"
+    def serve
+      boot_rails!
+      require "rails_ai_context"
+
+      transport = options[:transport].to_sym
+      if transport == :http
+        RailsAiContext.configuration.http_port = options[:port]
+      end
+
+      RailsAiContext.start_mcp_server(transport: transport)
+    end
+
+    desc "context", "Generate AI context files"
+    option :format, type: :string, default: "all", desc: "Format: claude, cursor, windsurf, copilot, json, all"
+    def context
+      boot_rails!
+      require "rails_ai_context"
+
+      format = options[:format].to_sym
+      $stderr.puts "Introspecting Rails app..."
+      files = RailsAiContext.generate_context(format: format)
+      files.each { |f| $stderr.puts "  Written: #{f}" }
+    end
+
+    desc "inspect", "Print introspection summary"
+    def inspect_app
+      boot_rails!
+      require "rails_ai_context"
+      require "json"
+
+      context = RailsAiContext.introspect
+      puts JSON.pretty_generate(context)
+    end
+
+    desc "version", "Print version"
+    def version
+      require_relative "../rails_ai_context/version"
+      puts "rails-ai-context v#{RailsAiContext::VERSION}"
+    end
+
+    private
+
+    def boot_rails!
+      # Try to find and boot the Rails app
+      config_path = File.join(Dir.pwd, "config", "environment.rb")
+      if File.exist?(config_path)
+        require config_path
+      else
+        $stderr.puts "Error: No Rails app found in #{Dir.pwd}"
+        $stderr.puts "Run this command from your Rails app root directory."
+        exit 1
+      end
+    end
+  end
+end
+
+RailsAiContext::CLI.start(ARGV)

data/lib/generators/rails_ai_context/install/install_generator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install rails-ai-context: creates initializer and generates initial context files."
+
+      def create_initializer
+        create_file "config/initializers/rails_ai_context.rb", <<~RUBY
+          # frozen_string_literal: true
+
+          RailsAiContext.configure do |config|
+            # MCP server name (shown to AI clients)
+            # config.server_name = "rails-ai-context"
+
+            # Auto-mount HTTP MCP endpoint at /mcp
+            # Set to true if you want remote MCP clients to connect
+            # config.auto_mount = false
+            # config.http_path  = "/mcp"
+            # config.http_port  = 6029
+
+            # Models to exclude from introspection
+            # config.excluded_models += %w[AdminUser InternalThing]
+
+            # Paths to exclude from code search
+            # config.excluded_paths += %w[vendor/bundle]
+          end
+        RUBY
+
+        say "Created config/initializers/rails_ai_context.rb", :green
+      end
+
+      def add_to_gitignore
+        gitignore = Rails.root.join(".gitignore")
+        return unless File.exist?(gitignore)
+
+        content = File.read(gitignore)
+        append = []
+        append << ".ai-context.json" unless content.include?(".ai-context.json")
+
+        if append.any?
+          File.open(gitignore, "a") do |f|
+            f.puts ""
+            f.puts "# rails-ai-context (JSON cache — markdown files should be committed)"
+            append.each { |line| f.puts line }
+          end
+          say "Updated .gitignore", :green
+        end
+      end
+
+      def generate_context_files
+        say ""
+        say "Generating AI context files...", :yellow
+
+        if Rails.application
+          require "rails_ai_context"
+          context = RailsAiContext.introspect
+          files = RailsAiContext.generate_context(format: :all)
+          files.each { |f| say "  Created #{f}", :green }
+        else
+          say "  Skipped (Rails app not fully loaded). Run `rails ai:context` after install.", :yellow
+        end
+      end
+
+      def show_instructions
+        say ""
+        say "=" * 50, :cyan
+        say " rails-ai-context installed!", :cyan
+        say "=" * 50, :cyan
+        say ""
+        say "Quick start:", :yellow
+        say "  rails ai:context     # Regenerate context files"
+        say "  rails ai:serve       # Start MCP server (stdio)"
+        say "  rails ai:inspect     # Print introspection summary"
+        say ""
+        say "For Claude Code, add to your claude_desktop_config.json:", :yellow
+        say '  { "mcpServers": { "rails": { "command": "rails", "args": ["ai:serve"], "cwd": "/path/to/your/app" } } }'
+        say ""
+        say "Commit CLAUDE.md and .cursorrules so your team benefits!", :green
+      end
+    end
+  end
+end

data/lib/rails-ai-context.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires using the gem name (dashes).
+# Forward to the real entry point (underscores).
+require_relative "rails_ai_context"

data/lib/rails_ai_context/configuration.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  class Configuration
+    # MCP server settings
+    attr_accessor :server_name, :server_version
+
+    # Which introspectors to run (all by default)
+    attr_accessor :introspectors
+
+    # Paths to exclude from code search
+    attr_accessor :excluded_paths
+
+    # Whether to auto-mount the MCP HTTP endpoint
+    attr_accessor :auto_mount
+
+    # HTTP transport settings
+    attr_accessor :http_path, :http_bind, :http_port
+
+    # Output directory for generated context files
+    attr_accessor :output_dir
+
+    # Models/tables to exclude from introspection
+    attr_accessor :excluded_models
+
+    # Maximum depth for association traversal
+    attr_accessor :max_association_depth
+
+    def initialize
+      @server_name         = "rails-ai-context"
+      @server_version      = RailsAiContext::VERSION
+      @introspectors       = %i[schema models routes jobs gems conventions]
+      @excluded_paths      = %w[node_modules tmp log vendor .git]
+      @auto_mount          = false
+      @http_path           = "/mcp"
+      @http_bind           = "127.0.0.1"
+      @http_port           = 6029
+      @output_dir          = nil # defaults to Rails.root
+      @excluded_models     = %w[
+        ApplicationRecord
+        ActiveStorage::Blob ActiveStorage::Attachment ActiveStorage::VariantRecord
+        ActionText::RichText ActionText::EncryptedRichText
+        ActionMailbox::InboundEmail ActionMailbox::Record
+      ]
+      @max_association_depth = 2
+    end
+
+    def output_dir_for(app)
+      @output_dir || app.root.to_s
+    end
+  end
+end

data/lib/rails_ai_context/engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  class Engine < ::Rails::Engine
+    # Register the MCP server after Rails finishes loading
+    initializer "rails_ai_context.setup", after: :load_config_initializers do |_app|
+      # Make introspection available via Rails console
+      Rails.application.config.rails_ai_context = RailsAiContext.configuration
+    end
+
+    # Register Rake tasks
+    rake_tasks do
+      load File.expand_path("tasks/rails_ai_context.rake", __dir__)
+    end
+
+    # Register generators
+    generators do
+      require_relative "../generators/rails_ai_context/install/install_generator"
+    end
+  end
+end

data/lib/rails_ai_context/introspector.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # Orchestrates all sub-introspectors to build a complete
+  # picture of the Rails application for AI consumption.
+  class Introspector
+    attr_reader :app, :config
+
+    def initialize(app)
+      @app    = app
+      @config = RailsAiContext.configuration
+    end
+
+    # Run all configured introspectors and return unified context hash
+    #
+    # @return [Hash] complete application context
+    def call
+      context = {
+        app_name: app_name,
+        ruby_version: RUBY_VERSION,
+        rails_version: Rails.version,
+        environment: Rails.env,
+        generated_at: Time.current.iso8601,
+        generator: "rails-ai-context v#{RailsAiContext::VERSION}"
+      }
+
+      config.introspectors.each do |name|
+        introspector = resolve_introspector(name)
+        context[name] = introspector.call
+      rescue => e
+        context[name] = { error: e.message }
+        Rails.logger.warn "[rails-ai-context] #{name} introspection failed: #{e.message}"
+      end
+
+      context
+    end
+
+    private
+
+    def app_name
+      if app.class.respond_to?(:module_parent_name)
+        app.class.module_parent_name
+      else
+        app.class.name.deconstantize
+      end
+    end
+
+    def resolve_introspector(name)
+      case name
+      when :schema      then Introspectors::SchemaIntrospector.new(app)
+      when :models      then Introspectors::ModelIntrospector.new(app)
+      when :routes      then Introspectors::RouteIntrospector.new(app)
+      when :jobs        then Introspectors::JobIntrospector.new(app)
+      when :gems        then Introspectors::GemIntrospector.new(app)
+      when :conventions then Introspectors::ConventionDetector.new(app)
+      else
+        raise ConfigurationError, "Unknown introspector: #{name}"
+      end
+    end
+  end
+end