rails-ai-context 0.1.0

data/lib/rails_ai_context/tools/get_gems.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Tools
+    class GetGems < BaseTool
+      tool_name "rails_get_gems"
+      description "Analyze the app's Gemfile.lock to identify notable gems, their categories (auth, jobs, frontend, API, database, testing, deploy), and what they mean for the app's architecture."
+
+      input_schema(
+        properties: {
+          category: {
+            type: "string",
+            enum: %w[auth jobs frontend api database files testing deploy all],
+            description: "Filter by category. Default: all."
+          }
+        }
+      )
+
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+
+      def self.call(category: "all", server_context: nil)
+        gems = cached_context[:gems]
+        return text_response("Gem introspection failed: #{gems[:error]}") if gems[:error]
+
+        notable = gems[:notable_gems] || []
+        notable = notable.select { |g| g[:category] == category } unless category == "all"
+
+        lines = ["# Gem Analysis", ""]
+        lines << "Total gems: #{gems[:total_gems]}"
+        lines << ""
+
+        if notable.any?
+          current_cat = nil
+          notable.sort_by { |g| [g[:category], g[:name]] }.each do |g|
+            if g[:category] != current_cat
+              current_cat = g[:category]
+              lines << "" << "## #{current_cat.capitalize}"
+            end
+            lines << "- **#{g[:name]}** (#{g[:version]}): #{g[:note]}"
+          end
+        else
+          lines << "_No notable gems found#{" in category '#{category}'" unless category == 'all'}._"
+        end
+
+        text_response(lines.join("\n"))
+      end
+    end
+  end
+end

data/lib/rails_ai_context/tools/get_model_details.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Tools
+    class GetModelDetails < BaseTool
+      tool_name "rails_get_model_details"
+      description "Get detailed information about a specific ActiveRecord model including associations, validations, scopes, enums, callbacks, and concerns. If no model specified, lists all available models."
+
+      input_schema(
+        properties: {
+          model: {
+            type: "string",
+            description: "Model class name (e.g. 'User', 'Post'). Omit to list all models."
+          }
+        }
+      )
+
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+
+      def self.call(model: nil, server_context: nil)
+        models = cached_context[:models]
+        return text_response("Model introspection failed: #{models[:error]}") if models.is_a?(Hash) && models[:error]
+
+        unless model
+          model_list = models.keys.sort.map { |m| "- #{m}" }.join("\n")
+          return text_response("# Available models (#{models.size})\n\n#{model_list}")
+        end
+
+        # Support both "User" and "user" lookups
+        key = models.keys.find { |k| k.downcase == model.downcase } || model
+        data = models[key]
+        return text_response("Model '#{model}' not found. Available: #{models.keys.sort.join(', ')}") unless data
+        return text_response("Error inspecting #{key}: #{data[:error]}") if data[:error]
+
+        text_response(format_model(key, data))
+      end
+
+      private_class_method def self.format_model(name, data)
+        lines = ["# #{name}", ""]
+        lines << "**Table:** `#{data[:table_name]}`" if data[:table_name]
+
+        # Associations
+        if data[:associations]&.any?
+          lines << "" << "## Associations"
+          data[:associations].each do |a|
+            detail = "- `#{a[:type]}` **#{a[:name]}**"
+            detail += " (class: #{a[:class_name]})" if a[:class_name] && a[:class_name] != a[:name].to_s.classify
+            detail += " through: #{a[:through]}" if a[:through]
+            detail += " [polymorphic]" if a[:polymorphic]
+            detail += " dependent: #{a[:dependent]}" if a[:dependent]
+            lines << detail
+          end
+        end
+
+        # Validations
+        if data[:validations]&.any?
+          lines << "" << "## Validations"
+          data[:validations].each do |v|
+            attrs = v[:attributes].join(", ")
+            opts = v[:options]&.any? ? " (#{v[:options].map { |k, val| "#{k}: #{val}" }.join(', ')})" : ""
+            lines << "- `#{v[:kind]}` on #{attrs}#{opts}"
+          end
+        end
+
+        # Enums
+        if data[:enums]&.any?
+          lines << "" << "## Enums"
+          data[:enums].each do |attr, values|
+            lines << "- `#{attr}`: #{values.join(', ')}"
+          end
+        end
+
+        # Scopes
+        if data[:scopes]&.any?
+          lines << "" << "## Scopes"
+          lines << data[:scopes].map { |s| "- `#{s}`" }.join("\n")
+        end
+
+        # Callbacks
+        if data[:callbacks]&.any?
+          lines << "" << "## Callbacks"
+          data[:callbacks].each do |type, methods|
+            lines << "- `#{type}`: #{methods.join(', ')}"
+          end
+        end
+
+        # Concerns
+        if data[:concerns]&.any?
+          lines << "" << "## Concerns"
+          lines << data[:concerns].map { |c| "- #{c}" }.join("\n")
+        end
+
+        # Key instance methods
+        if data[:instance_methods]&.any?
+          lines << "" << "## Key instance methods"
+          lines << data[:instance_methods].first(15).map { |m| "- `#{m}`" }.join("\n")
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/rails_ai_context/tools/get_routes.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Tools
+    class GetRoutes < BaseTool
+      tool_name "rails_get_routes"
+      description "Get all routes for the Rails app, optionally filtered by controller. Shows HTTP verb, path, controller#action, and route name."
+
+      input_schema(
+        properties: {
+          controller: {
+            type: "string",
+            description: "Optional: filter routes by controller name (e.g. 'users', 'api/v1/posts')."
+          }
+        }
+      )
+
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+
+      def self.call(controller: nil, server_context: nil)
+        routes = cached_context[:routes]
+        return text_response("Route introspection failed: #{routes[:error]}") if routes[:error]
+
+        by_controller = routes[:by_controller]
+
+        if controller
+          filtered = by_controller.select { |k, _| k.include?(controller) }
+          return text_response("No routes found for '#{controller}'. Controllers: #{by_controller.keys.sort.join(', ')}") if filtered.empty?
+          by_controller = filtered
+        end
+
+        lines = ["# Routes (#{routes[:total_routes]} total)", ""]
+        lines << "| Verb | Path | Controller#Action | Name |"
+        lines << "|------|------|-------------------|------|"
+
+        by_controller.sort.each do |ctrl, actions|
+          actions.each do |r|
+            lines << "| #{r[:verb]} | `#{r[:path]}` | #{ctrl}##{r[:action]} | #{r[:name] || '-'} |"
+          end
+        end
+
+        if routes[:api_namespaces]&.any?
+          lines << "" << "## API namespaces: #{routes[:api_namespaces].join(', ')}"
+        end
+
+        text_response(lines.join("\n"))
+      end
+    end
+  end
+end

data/lib/rails_ai_context/tools/get_schema.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Tools
+    class GetSchema < BaseTool
+      tool_name "rails_get_schema"
+      description "Get the database schema for the Rails app including tables, columns, indexes, and foreign keys. Optionally filter by table name."
+
+      input_schema(
+        properties: {
+          table: {
+            type: "string",
+            description: "Optional: specific table name to inspect. Omit for full schema."
+          },
+          format: {
+            type: "string",
+            enum: %w[json markdown],
+            description: "Output format. Default: markdown."
+          }
+        }
+      )
+
+      annotations(
+        read_only_hint: true,
+        destructive_hint: false,
+        idempotent_hint: true,
+        open_world_hint: false
+      )
+
+      def self.call(table: nil, format: "markdown", server_context: nil)
+        schema = cached_context[:schema]
+        return text_response("Schema introspection not available: #{schema[:error]}") if schema[:error]
+
+        if table
+          table_data = schema.dig(:tables, table)
+          return text_response("Table '#{table}' not found. Available: #{schema[:tables].keys.join(', ')}") unless table_data
+
+          output = format == "json" ? table_data.to_json : format_table_markdown(table, table_data)
+        else
+          output = format == "json" ? schema.to_json : format_schema_markdown(schema)
+        end
+
+        text_response(output)
+      end
+
+      private_class_method def self.format_table_markdown(name, data)
+        lines = ["## Table: #{name}", ""]
+        lines << "| Column | Type | Nullable | Default |"
+        lines << "|--------|------|----------|---------|"
+
+        data[:columns].each do |col|
+          lines << "| #{col[:name]} | #{col[:type]} | #{col[:null] ? 'yes' : 'no'} | #{col[:default] || '-'} |"
+        end
+
+        if data[:indexes]&.any?
+          lines << "" << "### Indexes"
+          data[:indexes].each do |idx|
+            unique = idx[:unique] ? " (unique)" : ""
+            lines << "- `#{idx[:name]}` on (#{Array(idx[:columns]).join(', ')})#{unique}"
+          end
+        end
+
+        if data[:foreign_keys]&.any?
+          lines << "" << "### Foreign keys"
+          data[:foreign_keys].each do |fk|
+            lines << "- `#{fk[:column]}` → `#{fk[:to_table]}.#{fk[:primary_key]}`"
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      private_class_method def self.format_schema_markdown(schema)
+        lines = [
+          "# Database Schema",
+          "",
+          "- Adapter: #{schema[:adapter]}",
+          "- Tables: #{schema[:total_tables]}",
+          ""
+        ]
+
+        schema[:tables].each do |name, data|
+          cols = data[:columns].map { |c| "#{c[:name]}:#{c[:type]}" }.join(", ")
+          lines << "### #{name}"
+          lines << cols
+          lines << ""
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/rails_ai_context/tools/search_code.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Tools
+    class SearchCode < BaseTool
+      tool_name "rails_search_code"
+      description "Search the Rails codebase for a pattern using ripgrep (rg) or Ruby fallback. Returns matching lines with file paths and line numbers. Useful for finding usages, implementations, and patterns."
+
+      input_schema(
+        properties: {
+          pattern: {
+            type: "string",
+            description: "Search pattern (regex supported)."
+          },
+          path: {
+            type: "string",
+            description: "Subdirectory to search in (e.g. 'app/models', 'config'). Default: entire app."
+          },
+          file_type: {
+            type: "string",
+            description: "Filter by file extension (e.g. 'rb', 'js', 'erb'). Default: all files."
+          },
+          max_results: {
+            type: "integer",
+            description: "Maximum number of results. Default: 30."
+          }
+        },
+        required: ["pattern"]
+      )
+
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+
+      def self.call(pattern:, path: nil, file_type: nil, max_results: 30, server_context: nil)
+        root = Rails.root.to_s
+        search_path = path ? File.join(root, path) : root
+
+        unless Dir.exist?(search_path)
+          return text_response("Path not found: #{path}")
+        end
+
+        results = if ripgrep_available?
+                    search_with_ripgrep(pattern, search_path, file_type, max_results, root)
+                  else
+                    search_with_ruby(pattern, search_path, file_type, max_results, root)
+                  end
+
+        if results.empty?
+          return text_response("No results found for '#{pattern}' in #{path || 'app'}.")
+        end
+
+        output = results.map { |r| "#{r[:file]}:#{r[:line_number]}: #{r[:content].strip}" }.join("\n")
+        header = "# Search: `#{pattern}`\n**#{results.size} results**#{" in #{path}" if path}\n\n```\n"
+        footer = "\n```"
+
+        text_response("#{header}#{output}#{footer}")
+      end
+
+      private_class_method def self.ripgrep_available?
+        @rg_available ||= system("which rg > /dev/null 2>&1")
+      end
+
+      private_class_method def self.search_with_ripgrep(pattern, search_path, file_type, max_results, root)
+        excluded = RailsAiContext.configuration.excluded_paths.map { |p| "--glob=!#{p}" }.join(" ")
+        type_flag = file_type ? "--type-add 'custom:*.#{file_type}' --type custom" : ""
+
+        cmd = "rg --no-heading --line-number --max-count #{max_results} #{excluded} #{type_flag} #{Shellwords.escape(pattern)} #{Shellwords.escape(search_path)} 2>/dev/null"
+
+        output = `#{cmd}`
+        parse_rg_output(output, root)
+      rescue => e
+        [{ file: "error", line_number: 0, content: e.message }]
+      end
+
+      private_class_method def self.search_with_ruby(pattern, search_path, file_type, max_results, root)
+        results = []
+        regex = Regexp.new(pattern, Regexp::IGNORECASE)
+        glob = file_type ? "**/*.#{file_type}" : "**/*.{rb,js,erb,yml,yaml,json}"
+        excluded = RailsAiContext.configuration.excluded_paths
+
+        Dir.glob(File.join(search_path, glob)).each do |file|
+          relative = file.sub("#{root}/", "")
+          next if excluded.any? { |ex| relative.start_with?(ex) }
+
+          File.readlines(file).each_with_index do |line, idx|
+            if line.match?(regex)
+              results << { file: relative, line_number: idx + 1, content: line }
+              return results if results.size >= max_results
+            end
+          end
+        rescue => _e
+          next # Skip binary/unreadable files
+        end
+
+        results
+      end
+
+      private_class_method def self.parse_rg_output(output, root)
+        output.lines.filter_map do |line|
+          match = line.match(/^(.+?):(\d+):(.*)$/)
+          next unless match
+
+          {
+            file: match[1].sub("#{root}/", ""),
+            line_number: match[2].to_i,
+            content: match[3]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_context/version.rb

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

data/lib/rails_ai_context.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "rails_ai_context/version"
+
+module RailsAiContext
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class IntrospectionError < Error; end
+
+  class << self
+    # Global configuration
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    # Quick access to introspect the current Rails app
+    # Returns a hash of all discovered context
+    def introspect(app = nil)
+      app ||= Rails.application
+      Introspector.new(app).call
+    end
+
+    # Generate context files (CLAUDE.md, .cursorrules, etc.)
+    def generate_context(app = nil, format: :all)
+      app ||= Rails.application
+      context = introspect(app)
+      Serializers::ContextFileSerializer.new(context, format: format).call
+    end
+
+    # Start the MCP server programmatically
+    def start_mcp_server(app = nil, transport: :stdio)
+      app ||= Rails.application
+      Server.new(app, transport: transport).start
+    end
+  end
+end
+
+# Configuration
+require_relative "rails_ai_context/configuration"
+
+# Core introspection
+require_relative "rails_ai_context/introspector"
+require_relative "rails_ai_context/introspectors/schema_introspector"
+require_relative "rails_ai_context/introspectors/model_introspector"
+require_relative "rails_ai_context/introspectors/route_introspector"
+require_relative "rails_ai_context/introspectors/job_introspector"
+require_relative "rails_ai_context/introspectors/gem_introspector"
+require_relative "rails_ai_context/introspectors/convention_detector"
+
+# MCP Tools
+require_relative "rails_ai_context/tools/base_tool"
+require_relative "rails_ai_context/tools/get_schema"
+require_relative "rails_ai_context/tools/get_routes"
+require_relative "rails_ai_context/tools/get_model_details"
+require_relative "rails_ai_context/tools/get_gems"
+require_relative "rails_ai_context/tools/search_code"
+require_relative "rails_ai_context/tools/get_conventions"
+
+# Serializers
+require_relative "rails_ai_context/serializers/context_file_serializer"
+require_relative "rails_ai_context/serializers/markdown_serializer"
+require_relative "rails_ai_context/serializers/json_serializer"
+
+# MCP Server
+require_relative "rails_ai_context/server"
+
+# Rails integration — loaded by Bundler.require after Rails is booted
+require_relative "rails_ai_context/engine" if defined?(Rails::Engine)

data/rails-ai-context.gemspec

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "lib/rails_ai_context/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "rails-ai-context"
+  spec.version       = RailsAiContext::VERSION
+  spec.authors       = ["crisnahine"]
+  spec.email         = ["crisjosephnahine@gmail.com"]
+
+  spec.summary       = "Turn any Rails app into an AI-ready codebase — one gem install."
+  spec.description   = <<~DESC
+    rails-ai-context automatically introspects your Rails application and exposes
+    models, routes, schema, jobs, mailers, and conventions through the Model Context
+    Protocol (MCP). Works with Claude Code, Cursor, Windsurf, GitHub Copilot, and
+    any MCP-compatible AI tool. Zero configuration required.
+  DESC
+
+  spec.homepage      = "https://github.com/crisnahine/rails-ai-context"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Core dependencies
+  spec.add_dependency "mcp", "~> 0.8"             # Official MCP Ruby SDK
+  spec.add_dependency "railties", ">= 7.1", "< 9.0"
+  spec.add_dependency "thor", ">= 1.0", "< 3.0"
+
+  # Dev dependencies
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.65"
+  spec.add_development_dependency "rubocop-rails-omakase", "~> 1.0"
+  spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "combustion", "~> 1.4" # Test Rails engines in isolation
+end