rails-ai-context 0.1.0

data/lib/rails_ai_context/introspectors/schema_introspector.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # Extracts database schema information including tables, columns,
+    # indexes, and foreign keys from the Rails application.
+    class SchemaIntrospector
+      attr_reader :app
+
+      def initialize(app)
+        @app = app
+      end
+
+      # @return [Hash] database schema context
+      def call
+        return static_schema_parse unless active_record_connected?
+
+        {
+          adapter: adapter_name,
+          tables: extract_tables,
+          total_tables: table_names.size,
+          schema_version: current_schema_version
+        }
+      end
+
+      private
+
+      def active_record_connected?
+        defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
+      rescue
+        false
+      end
+
+      def adapter_name
+        ActiveRecord::Base.connection.adapter_name
+      rescue
+        "unknown"
+      end
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+
+      def table_names
+        @table_names ||= connection.tables.reject { |t| t.start_with?("ar_internal_metadata", "schema_migrations") }
+      end
+
+      def extract_tables
+        table_names.each_with_object({}) do |table, hash|
+          hash[table] = {
+            columns: extract_columns(table),
+            indexes: extract_indexes(table),
+            foreign_keys: extract_foreign_keys(table),
+            primary_key: connection.primary_key(table)
+          }
+        end
+      end
+
+      def extract_columns(table)
+        connection.columns(table).map do |col|
+          {
+            name: col.name,
+            type: col.type.to_s,
+            null: col.null,
+            default: col.default,
+            limit: col.limit,
+            precision: col.precision,
+            scale: col.scale,
+            comment: col.comment
+          }.compact
+        end
+      end
+
+      def extract_indexes(table)
+        connection.indexes(table).map do |idx|
+          {
+            name: idx.name,
+            columns: idx.columns,
+            unique: idx.unique,
+            where: idx.where
+          }.compact
+        end
+      end
+
+      def extract_foreign_keys(table)
+        connection.foreign_keys(table).map do |fk|
+          {
+            from_table: fk.from_table,
+            to_table: fk.to_table,
+            column: fk.column,
+            primary_key: fk.primary_key,
+            on_delete: fk.on_delete,
+            on_update: fk.on_update
+          }.compact
+        end
+      rescue
+        [] # Some adapters don't support foreign_keys
+      end
+
+      def current_schema_version
+        if File.exist?(schema_file_path)
+          content = File.read(schema_file_path)
+          match = content.match(/version:\s*(\d+)_?\d*/)
+          match ? match[1] : nil
+        end
+      end
+
+      def schema_file_path
+        File.join(app.root, "db", "schema.rb")
+      end
+
+      # Fallback: parse db/schema.rb as text when DB isn't connected
+      # This enables introspection in CI, Claude Code, etc.
+      def static_schema_parse
+        path = schema_file_path
+        return { error: "No schema.rb found at #{path}" } unless File.exist?(path)
+
+        content = File.read(path)
+        tables = {}
+        current_table = nil
+
+        content.each_line do |line|
+          if (match = line.match(/create_table\s+"(\w+)"/))
+            current_table = match[1]
+            next if current_table.start_with?("ar_internal_metadata", "schema_migrations")
+            tables[current_table] = { columns: [], indexes: [], foreign_keys: [] }
+          elsif current_table && (match = line.match(/t\.(\w+)\s+"(\w+)"/))
+            tables[current_table][:columns] << { name: match[2], type: match[1] }
+          elsif (match = line.match(/add_index\s+"(\w+)",\s+\[?"(\w+)"/))
+            tables[match[1]]&.dig(:indexes)&.push({ columns: match[2] })
+          end
+        end
+
+        {
+          adapter: "static_parse",
+          tables: tables,
+          total_tables: tables.size,
+          note: "Parsed from db/schema.rb (no DB connection)"
+        }
+      end
+    end
+  end
+end

data/lib/rails_ai_context/serializers/context_file_serializer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Serializers
+    # Orchestrates writing context files to disk in various formats.
+    # Supports: CLAUDE.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md, JSON
+    class ContextFileSerializer
+      attr_reader :context, :format
+
+      FORMAT_MAP = {
+        claude:    "CLAUDE.md",
+        cursor:    ".cursorrules",
+        windsurf:  ".windsurfrules",
+        copilot:   ".github/copilot-instructions.md",
+        json:      ".ai-context.json"
+      }.freeze
+
+      def initialize(context, format: :all)
+        @context = context
+        @format  = format
+      end
+
+      # Write context files and return list of files written
+      # @return [Array<String>] file paths written
+      def call
+        formats = format == :all ? FORMAT_MAP.keys : Array(format)
+        output_dir = RailsAiContext.configuration.output_dir_for(Rails.application)
+        written = []
+
+        formats.each do |fmt|
+          filename = FORMAT_MAP[fmt]
+          next unless filename
+
+          filepath = File.join(output_dir, filename)
+
+          # Ensure subdirectory exists (e.g. .github/)
+          FileUtils.mkdir_p(File.dirname(filepath))
+
+          content = serialize(fmt)
+          File.write(filepath, content)
+          written << filepath
+        end
+
+        written
+      end
+
+      private
+
+      def serialize(fmt)
+        case fmt
+        when :json
+          JsonSerializer.new(context).call
+        else
+          # All markdown-based formats use the same content
+          MarkdownSerializer.new(context).call
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_context/serializers/json_serializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RailsAiContext
+  module Serializers
+    class JsonSerializer
+      attr_reader :context
+
+      def initialize(context)
+        @context = context
+      end
+
+      def call
+        JSON.pretty_generate(context)
+      end
+    end
+  end
+end

data/lib/rails_ai_context/serializers/markdown_serializer.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Serializers
+    # Generates AI-friendly markdown context files from introspection data.
+    # Outputs: CLAUDE.md (for Claude Code), .cursorrules, .windsurfrules, etc.
+    class MarkdownSerializer
+      attr_reader :context
+
+      def initialize(context)
+        @context = context
+      end
+
+      # @return [String] full markdown document
+      def call
+        sections = []
+        sections << header
+        sections << app_overview
+        sections << schema_section if context[:schema]
+        sections << models_section if context[:models]
+        sections << routes_section if context[:routes]
+        sections << jobs_section if context[:jobs]
+        sections << gems_section if context[:gems]
+        sections << conventions_section if context[:conventions]
+        sections << footer
+        sections.compact.join("\n\n")
+      end
+
+      private
+
+      def header
+        <<~MD
+          # #{context[:app_name]} — AI Context
+
+          > Auto-generated by rails-ai-context v#{RailsAiContext::VERSION}
+          > Generated: #{context[:generated_at]}
+          > Rails #{context[:rails_version]} | Ruby #{context[:ruby_version]}
+
+          This file gives AI assistants (Claude Code, Cursor, Copilot) deep context
+          about this Rails application's structure, patterns, and conventions.
+        MD
+      end
+
+      def app_overview
+        conv = context[:conventions] || {}
+        arch = conv[:architecture] || []
+        patterns = conv[:patterns] || []
+
+        lines = ["## Overview"]
+        lines << "- **Architecture:** #{arch.join(', ')}" if arch.any?
+        lines << "- **Patterns:** #{patterns.join(', ')}" if patterns.any?
+        lines.join("\n")
+      end
+
+      def schema_section
+        schema = context[:schema]
+        return if schema[:error]
+
+        lines = ["## Database Schema (#{schema[:total_tables]} tables)"]
+        schema[:tables]&.each do |name, data|
+          cols = (data[:columns] || []).map { |c| "`#{c[:name]}` (#{c[:type]})" }.join(", ")
+          lines << "### #{name}"
+          lines << cols
+        end
+        lines.join("\n\n")
+      end
+
+      def models_section
+        models = context[:models]
+        return if models.is_a?(Hash) && models[:error]
+
+        lines = ["## Models (#{models.size})"]
+        models.each do |name, data|
+          next if data[:error]
+          assocs = (data[:associations] || []).map { |a| "#{a[:type]} :#{a[:name]}" }.join(", ")
+          lines << "### #{name}"
+          lines << "- Table: `#{data[:table_name]}`" if data[:table_name]
+          lines << "- Associations: #{assocs}" if assocs.present?
+          if data[:validations]&.any?
+            vals = data[:validations].map { |v| "#{v[:kind]} on #{v[:attributes].join(', ')}" }.join("; ")
+            lines << "- Validations: #{vals}"
+          end
+          lines << "- Enums: #{data[:enums].keys.join(', ')}" if data[:enums]&.any?
+        end
+        lines.join("\n")
+      end
+
+      def routes_section
+        routes = context[:routes]
+        return if routes[:error]
+
+        lines = ["## Routes (#{routes[:total_routes]} total)"]
+        routes[:by_controller]&.sort&.each do |ctrl, actions|
+          lines << "### #{ctrl}"
+          actions.each do |r|
+            lines << "- `#{r[:verb]} #{r[:path]}` → #{r[:action]}"
+          end
+        end
+        lines.join("\n")
+      end
+
+      def jobs_section
+        jobs = context[:jobs]
+        parts = []
+
+        if jobs[:jobs]&.any?
+          parts << "## Background Jobs"
+          jobs[:jobs].each { |j| parts << "- `#{j[:name]}` (queue: #{j[:queue]})" }
+        end
+
+        if jobs[:mailers]&.any?
+          parts << "## Mailers"
+          jobs[:mailers].each { |m| parts << "- `#{m[:name]}`: #{m[:actions].join(', ')}" }
+        end
+
+        if jobs[:channels]&.any?
+          parts << "## Action Cable Channels"
+          jobs[:channels].each { |c| parts << "- `#{c[:name]}`" }
+        end
+
+        parts.join("\n") if parts.any?
+      end
+
+      def gems_section
+        gems = context[:gems]
+        return if gems[:error]
+
+        notable = gems[:notable_gems] || []
+        return if notable.empty?
+
+        lines = ["## Notable Gems"]
+        notable.group_by { |g| g[:category] }.sort.each do |cat, group|
+          lines << "### #{cat.capitalize}"
+          group.each { |g| lines << "- **#{g[:name]}** (#{g[:version]}): #{g[:note]}" }
+        end
+        lines.join("\n")
+      end
+
+      def conventions_section
+        conv = context[:conventions]
+        return unless conv[:directory_structure]&.any?
+
+        lines = ["## Project Structure"]
+        conv[:directory_structure].sort.each do |dir, count|
+          lines << "- `#{dir}/` — #{count} files"
+        end
+        lines.join("\n")
+      end
+
+      def footer
+        <<~MD
+          ---
+          _This context file is auto-generated. Run `rails ai:context` to regenerate._
+        MD
+      end
+    end
+  end
+end

data/lib/rails_ai_context/server.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module RailsAiContext
+  # Configures and starts an MCP server using the official Ruby SDK.
+  # Registers all introspection tools and handles transport selection.
+  class Server
+    attr_reader :app, :transport_type
+
+    TOOLS = [
+      Tools::GetSchema,
+      Tools::GetRoutes,
+      Tools::GetModelDetails,
+      Tools::GetGems,
+      Tools::SearchCode,
+      Tools::GetConventions
+    ].freeze
+
+    def initialize(app, transport: :stdio)
+      @app = app
+      @transport_type = transport
+    end
+
+    # Build and return the configured MCP::Server instance
+    def build
+      config = RailsAiContext.configuration
+
+      MCP::Server.new(
+        name: config.server_name,
+        version: config.server_version,
+        tools: TOOLS
+      )
+    end
+
+    # Start the MCP server with the configured transport
+    def start
+      server = build
+
+      case transport_type
+      when :stdio
+        start_stdio(server)
+      when :http, :streamable_http
+        start_http(server)
+      else
+        raise ConfigurationError, "Unknown transport: #{transport_type}. Use :stdio or :http"
+      end
+    end
+
+    private
+
+    def start_stdio(server)
+      transport = MCP::Server::Transports::StdioTransport.new(server)
+      # Log to stderr so we don't pollute the JSON-RPC channel on stdout
+      $stderr.puts "[rails-ai-context] MCP server started (stdio transport)"
+      $stderr.puts "[rails-ai-context] Tools: #{TOOLS.map { |t| t.tool_name }.join(', ')}"
+      transport.open
+    end
+
+    def start_http(server)
+      config = RailsAiContext.configuration
+      transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+
+      # Build a minimal Rack app that delegates to the MCP transport
+      rack_app = build_rack_app(transport, config.http_path)
+
+      $stderr.puts "[rails-ai-context] MCP server starting on #{config.http_bind}:#{config.http_port}#{config.http_path}"
+      $stderr.puts "[rails-ai-context] Tools: #{TOOLS.map { |t| t.tool_name }.join(', ')}"
+
+      require "rackup"
+      Rackup::Handler.default.run(rack_app, Host: config.http_bind, Port: config.http_port)
+    rescue LoadError
+      # Fallback for older rack without rackup gem
+      require "rack/handler"
+      Rack::Handler.default.run(rack_app, Host: config.http_bind, Port: config.http_port)
+    end
+
+    def build_rack_app(transport, path)
+      lambda do |env|
+        # Only handle requests at the configured MCP path
+        unless env["PATH_INFO"] == path || env["PATH_INFO"] == "#{path}/"
+          return [404, { "Content-Type" => "application/json" }, ['{"error":"Not found"}']]
+        end
+
+        request = Rack::Request.new(env)
+        transport.handle_request(request)
+      end
+    end
+  end
+end

data/lib/rails_ai_context/tasks/rails_ai_context.rake

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+namespace :ai do
+  desc "Generate AI context files (CLAUDE.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md)"
+  task context: :environment do
+    require "rails_ai_context"
+
+    puts "🔍 Introspecting #{Rails.application.class.module_parent_name}..."
+    context = RailsAiContext.introspect
+
+    puts "📝 Writing context files..."
+    files = RailsAiContext.generate_context(format: :all)
+
+    files.each { |f| puts "  ✅ #{f}" }
+    puts ""
+    puts "Done! Your AI assistants now understand your Rails app."
+    puts "Commit these files so your whole team benefits."
+  end
+
+  desc "Generate AI context in a specific format (claude, cursor, windsurf, copilot, json)"
+  task :context_for, [:format] => :environment do |_t, args|
+    require "rails_ai_context"
+
+    format = (args[:format] || "claude").to_sym
+    puts "🔍 Introspecting #{Rails.application.class.module_parent_name}..."
+    context = RailsAiContext.introspect
+
+    puts "📝 Writing #{format} context file..."
+    files = RailsAiContext.generate_context(format: format)
+
+    files.each { |f| puts "  ✅ #{f}" }
+  end
+
+  desc "Start the MCP server (stdio transport, for Claude Code / Cursor)"
+  task serve: :environment do
+    require "rails_ai_context"
+
+    RailsAiContext.start_mcp_server(transport: :stdio)
+  end
+
+  desc "Start the MCP server with HTTP transport"
+  task serve_http: :environment do
+    require "rails_ai_context"
+
+    RailsAiContext.start_mcp_server(transport: :http)
+  end
+
+  desc "Print introspection summary to stdout (useful for debugging)"
+  task inspect: :environment do
+    require "rails_ai_context"
+    require "json"
+
+    context = RailsAiContext.introspect
+
+    puts "=" * 60
+    puts " #{context[:app_name]} — AI Context Summary"
+    puts "=" * 60
+    puts ""
+    puts "Rails #{context[:rails_version]} | Ruby #{context[:ruby_version]}"
+    puts ""
+
+    if context[:schema] && !context[:schema][:error]
+      puts "📦 Database: #{context[:schema][:total_tables]} tables (#{context[:schema][:adapter]})"
+    end
+
+    if context[:models] && !context[:models].is_a?(Hash)
+      puts "🏗️  Models: #{context[:models].size}"
+    elsif context[:models].is_a?(Hash) && !context[:models][:error]
+      puts "🏗️  Models: #{context[:models].size}"
+    end
+
+    if context[:routes] && !context[:routes][:error]
+      puts "🛤️  Routes: #{context[:routes][:total_routes]}"
+    end
+
+    if context[:jobs]
+      puts "⚡ Jobs: #{context[:jobs][:jobs]&.size || 0}"
+      puts "📧 Mailers: #{context[:jobs][:mailers]&.size || 0}"
+    end
+
+    if context[:conventions]
+      arch = context[:conventions][:architecture] || []
+      puts "🏛️  Architecture: #{arch.join(', ')}" if arch.any?
+    end
+
+    puts ""
+    puts "Run `rails ai:context` to generate context files."
+  end
+end

data/lib/rails_ai_context/tools/base_tool.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module RailsAiContext
+  module Tools
+    # Base class for all MCP tools exposed by rails-ai-context.
+    # Inherits from the official MCP::Tool to get schema validation,
+    # annotations, and protocol compliance for free.
+    class BaseTool < MCP::Tool
+      class << self
+        # Convenience: access the Rails app and cached introspection
+        def rails_app
+          Rails.application
+        end
+
+        def config
+          RailsAiContext.configuration
+        end
+
+        # Cache introspection results for the lifetime of the server process
+        def cached_context
+          @cached_context ||= RailsAiContext.introspect
+        end
+
+        def reset_cache!
+          @cached_context = nil
+        end
+
+        # Helper: wrap text in an MCP::Tool::Response
+        def text_response(text)
+          MCP::Tool::Response.new([{ type: "text", text: text }])
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_context/tools/get_conventions.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Tools
+    class GetConventions < BaseTool
+      tool_name "rails_get_conventions"
+      description "Detect architectural patterns and conventions used in this Rails app. Returns info about architecture style (API-only, Hotwire, GraphQL), design patterns (service objects, STI, polymorphism), directory structure, and config files present."
+
+      input_schema(properties: {})
+
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+
+      def self.call(server_context: nil)
+        conventions = cached_context[:conventions]
+        return text_response("Convention detection failed: #{conventions[:error]}") if conventions.is_a?(Hash) && conventions[:error]
+
+        lines = ["# App Conventions & Architecture", ""]
+
+        # Architecture
+        if conventions[:architecture]&.any?
+          lines << "## Architecture"
+          conventions[:architecture].each { |a| lines << "- #{humanize_arch(a)}" }
+        end
+
+        # Patterns
+        if conventions[:patterns]&.any?
+          lines << "" << "## Detected patterns"
+          conventions[:patterns].each { |p| lines << "- #{humanize_pattern(p)}" }
+        end
+
+        # Directory structure
+        if conventions[:directory_structure]&.any?
+          lines << "" << "## Directory structure"
+          conventions[:directory_structure].sort_by { |k, _| k }.each do |dir, count|
+            lines << "- `#{dir}/` → #{count} files"
+          end
+        end
+
+        # Config files
+        if conventions[:config_files]&.any?
+          lines << "" << "## Config files present"
+          conventions[:config_files].each { |f| lines << "- `#{f}`" }
+        end
+
+        text_response(lines.join("\n"))
+      end
+
+      ARCH_LABELS = {
+        "api_only" => "API-only mode (no views/assets)",
+        "hotwire" => "Hotwire (Turbo + Stimulus)",
+        "graphql" => "GraphQL API (app/graphql/)",
+        "grape_api" => "Grape API framework (app/api/)",
+        "service_objects" => "Service objects pattern (app/services/)",
+        "form_objects" => "Form objects (app/forms/)",
+        "query_objects" => "Query objects (app/queries/)",
+        "presenters" => "Presenters/Decorators",
+        "view_components" => "ViewComponent (app/components/)",
+        "stimulus" => "Stimulus controllers (app/javascript/controllers/)",
+        "importmaps" => "Import maps (no JS bundler)",
+        "docker" => "Dockerized",
+        "kamal" => "Kamal deployment",
+        "ci_github_actions" => "GitHub Actions CI"
+      }.freeze
+
+      PATTERN_LABELS = {
+        "sti" => "Single Table Inheritance (STI)",
+        "polymorphic" => "Polymorphic associations",
+        "soft_delete" => "Soft deletes (paranoia/discard)",
+        "versioning" => "Model versioning/auditing",
+        "state_machine" => "State machines (AASM/workflow)",
+        "multi_tenancy" => "Multi-tenancy",
+        "searchable" => "Full-text search (Searchkick/pg_search/Ransack)",
+        "taggable" => "Tagging",
+        "sluggable" => "Friendly URLs/slugs",
+        "nested_set" => "Tree/nested set structures"
+      }.freeze
+
+      private_class_method def self.humanize_arch(key)
+        ARCH_LABELS[key] || key.humanize
+      end
+
+      private_class_method def self.humanize_pattern(key)
+        PATTERN_LABELS[key] || key.humanize
+      end
+    end
+  end
+end