rails-mcp-server 1.1.4 → 1.2.1

data/lib/rails-mcp-server/resources/guide_loader_template.rb

@@ -0,0 +1,122 @@
+module RailsMcpServer
+  # Template module that provides complete guide loading implementation
+  # Eliminates the need to implement load_specific_guide in each resource
+  module GuideLoaderTemplate
+    def self.included(base)
+      # Ensure all required modules are included
+      base.include GuideFrameworkContract unless base.included_modules.include?(GuideFrameworkContract)
+      base.include GuideManifestOperations unless base.included_modules.include?(GuideManifestOperations)
+      base.include GuideFileFinder unless base.included_modules.include?(GuideFileFinder)
+      base.include GuideContentFormatter unless base.included_modules.include?(GuideContentFormatter)
+      base.include GuideErrorHandler unless base.included_modules.include?(GuideErrorHandler)
+    end
+
+    # Complete single guide content implementation
+    def content
+      guide_name = params[:guide_name]
+
+      begin
+        manifest = load_manifest
+      rescue => e
+        return handle_manifest_error(e)
+      end
+
+      if !guide_name.nil? && !guide_name.strip.empty?
+        log(:debug, "Loading #{framework_name} guide: #{guide_name}")
+        load_specific_guide(guide_name, manifest)
+      else
+        log(:debug, "Provide a name for a #{framework_name} guide")
+        "Provide a name for a #{framework_name} guide"
+      end
+    end
+
+    # Complete guides list implementation
+    def list_content
+      begin
+        manifest = load_manifest
+      rescue => e
+        return handle_manifest_error(e)
+      end
+
+      log(:debug, "Loading #{framework_name} guides...")
+      format_guides_index(manifest)
+    end
+
+    protected
+
+    # Template method for loading a specific guide
+    def load_specific_guide(guide_name, manifest)
+      normalized_guide_name = guide_name.gsub(/[^a-zA-Z0-9_\/.-]/, "")
+
+      begin
+        filename, guide_data = find_guide_file(normalized_guide_name, manifest)
+
+        if filename && guide_data
+          guides_path = File.dirname(File.join(config_dir, "resources", resource_directory, "manifest.yaml"))
+          guide_file_path = File.join(guides_path, filename)
+
+          if File.exist?(guide_file_path)
+            log(:debug, "Loading guide: #{filename}")
+            content = File.read(guide_file_path)
+
+            # Allow customization of display name
+            display_name = customize_display_name(guide_name, guide_data)
+            format_guide_content(content, display_name, guide_data, filename)
+          else
+            format_not_found_message(guide_name, manifest)
+          end
+        else
+          format_not_found_message(guide_name, manifest)
+        end
+      rescue => e
+        handle_guide_loading_error(guide_name, e)
+      end
+    end
+
+    # Template method for formatting guides index
+    def format_guides_index(manifest)
+      guides = []
+
+      guides << "# Available #{framework_name} Guides\n"
+      guides << "Use the `load_guide` tool with `guides: \"#{framework_name.downcase}\"` and `guide: \"guide_name\"` to load a specific guide.\n"
+
+      if supports_sections?
+        guides << "You can use either the full path (e.g., `handbook/01_introduction`) or just the filename (e.g., `01_introduction`).\n"
+      end
+
+      guide_files = get_guide_files(manifest)
+
+      if supports_sections?
+        guides.concat(format_sectioned_guides(guide_files))
+      else
+        guides.concat(format_flat_guides(guide_files))
+      end
+
+      # Add examples if this is a list resource
+      if respond_to?(:example_guides) && example_guides.any?
+        guides << format_usage_examples
+      end
+
+      guides.join("\n")
+    end
+
+    # Template method for not found messages
+    def format_not_found_message(guide_name, manifest)
+      guide_files = get_guide_files(manifest)
+      available_guides = guide_files.keys.map { |f| f.sub(".md", "") }
+
+      message = create_not_found_message(guide_name, available_guides)
+
+      # Allow framework-specific additions to not found message
+      message = customize_not_found_message(message, guide_name) if respond_to?(:customize_not_found_message, true)
+
+      log(:error, "Guide not found: #{guide_name}")
+      message
+    end
+
+    # Hook for customizing display name (override in resources if needed)
+    def customize_display_name(guide_name, guide_data)
+      guide_name
+    end
+  end
+end

data/lib/rails-mcp-server/resources/guide_manifest_operations.rb

@@ -0,0 +1,52 @@
+module RailsMcpServer
+  # Module for handling guide manifest operations
+  module GuideManifestOperations
+    protected
+
+    # Load and validate manifest file
+    def load_manifest
+      manifest_file = File.join(config_dir, "resources", resource_directory, "manifest.yaml")
+
+      unless File.exist?(manifest_file)
+        error_message = "No #{framework_name} guides found. Run '#{download_command}' first."
+        log(:error, error_message)
+        raise StandardError, error_message
+      end
+
+      YAML.load_file(manifest_file)
+    end
+
+    # Extract guide metadata from manifest entry
+    def extract_guide_metadata(filename, file_data)
+      {
+        filename: filename,
+        guide_name: filename.sub(".md", ""),
+        title: file_data["title"] || generate_title_from_filename(filename),
+        description: file_data["description"] || "",
+        original_filename: file_data["original_filename"] # For custom guides
+      }
+    end
+
+    # Generate title from filename if not in manifest
+    def generate_title_from_filename(filename)
+      base_name = filename.sub(".md", "").split("/").last
+      base_name.gsub(/[_-]/, " ").split.map(&:capitalize).join(" ")
+    end
+
+    # Get all guide files from manifest
+    def get_guide_files(manifest)
+      manifest["files"].select { |filename, _| filename.end_with?(".md") }
+    end
+
+    # Get guide files organized by sections
+    def get_sectioned_guide_files(manifest)
+      guide_files = get_guide_files(manifest)
+
+      {
+        handbook: guide_files.select { |filename, _| filename.start_with?("handbook/") },
+        reference: guide_files.select { |filename, _| filename.start_with?("reference/") },
+        other: guide_files.reject { |filename, _| filename.start_with?("handbook/", "reference/") }
+      }
+    end
+  end
+end

data/lib/rails-mcp-server/resources/kamal_guides_resource.rb

@@ -0,0 +1,80 @@
+module RailsMcpServer
+  class KamalGuidesResource < BaseResource
+    include GuideLoaderTemplate
+
+    uri "kamal://guides/{guide_name}"
+    resource_name "Kamal Guides"
+    description "Access to specific Kamal deployment documentation"
+    mime_type "text/markdown"
+
+    protected
+
+    def framework_name
+      "Kamal"
+    end
+
+    def resource_directory
+      "kamal"
+    end
+
+    def download_command
+      "rails-mcp-server-download-resources kamal"
+    end
+
+    # Kamal guides have subdirectories but not handbook/reference sections
+    def supports_sections?
+      false
+    end
+
+    # Override for Kamal's directory structure
+    def framework_specific_filenames(normalized_guide_name)
+      possible_files = []
+
+      if normalized_guide_name.include?("/")
+        possible_files << normalized_guide_name
+        possible_files << "#{normalized_guide_name}.md"
+      else
+        %w[installation configuration commands hooks upgrading].each do |section|
+          possible_files << "#{section}/#{normalized_guide_name}.md"
+          possible_files << "#{section}/index.md" if normalized_guide_name == section
+        end
+        possible_files << "#{normalized_guide_name}/index.md"
+      end
+
+      possible_files
+    end
+
+    # Override for Kamal's section detection
+    def framework_specific_section(filename)
+      case filename
+      when /^installation\// then "Installation"
+      when /^configuration\// then "Configuration"
+      when /^commands\// then "Commands"
+      when /^hooks\// then "Hooks"
+      when /^upgrading\// then "Upgrading"
+      else; "Documentation"
+      end
+    end
+
+    # Enhanced fuzzy matching for hierarchical structure
+    def fuzzy_match_files(normalized_guide_name, manifest)
+      search_term = normalized_guide_name.downcase
+
+      manifest["files"].select do |file, _|
+        next false unless file.end_with?(".md")
+
+        file_path = file.downcase
+        file_name_base = file.sub(".md", "").split("/").last.downcase
+        file_full_path = file.sub(".md", "").downcase
+
+        file_path.include?(search_term) ||
+          file_name_base.include?(search_term) ||
+          search_term.include?(file_name_base) ||
+          file_full_path.include?(search_term) ||
+          search_term.include?(file_full_path) ||
+          file_name_base.gsub(/[_-]/, "").include?(search_term.gsub(/[_-]/, "")) ||
+          search_term.gsub(/[_-]/, "").include?(file_name_base.gsub(/[_-]/, ""))
+      end.to_a
+    end
+  end
+end

data/lib/rails-mcp-server/resources/kamal_guides_resources.rb

@@ -0,0 +1,110 @@
+module RailsMcpServer
+  class KamalGuidesResources < BaseResource
+    include GuideLoaderTemplate
+
+    uri "kamal://guides"
+    resource_name "Kamal Guides"
+    description "Access to available Kamal deployment guides"
+    mime_type "text/markdown"
+
+    protected
+
+    def framework_name
+      "Kamal"
+    end
+
+    def resource_directory
+      "kamal"
+    end
+
+    def download_command
+      "rails-mcp-server-download-resources kamal"
+    end
+
+    def example_guides
+      [
+        {guide: "installation/index", comment: "Load installation guide"},
+        {guide: "configuration/environment-variables", comment: "Load environment variables configuration"},
+        {guide: "commands/deploy", comment: "Load deploy command guide"},
+        {guide: "hooks/overview", comment: "Load hooks overview"},
+        {guide: "upgrading/overview", comment: "Load upgrading overview"}
+      ]
+    end
+
+    # Kamal guides have subdirectories but not handbook/reference sections
+    def supports_sections?
+      false
+    end
+
+    # Override to format guides organized by Kamal's directory structure
+    def format_flat_guides(manifest)
+      guides = []
+
+      # Group guides by their directory structure
+      sections = {
+        "installation" => [],
+        "configuration" => [],
+        "commands" => [],
+        "hooks" => [],
+        "upgrading" => []
+      }
+
+      other_guides = []
+
+      manifest["files"].each do |filename, file_data|
+        next unless filename.end_with?(".md")
+
+        log(:debug, "Processing guide: #{filename}")
+
+        guide_name = filename.sub(".md", "")
+        title = file_data["title"] || guide_name.split("/").last.gsub(/[_-]/, " ").split.map(&:capitalize).join(" ")
+        description = file_data["description"] || ""
+
+        # Categorize by directory
+        case filename
+        when /^installation\//
+          sections["installation"] << {name: guide_name, title: title, description: description}
+        when /^configuration\//
+          sections["configuration"] << {name: guide_name, title: title, description: description}
+        when /^commands\//
+          sections["commands"] << {name: guide_name, title: title, description: description}
+        when /^hooks\//
+          sections["hooks"] << {name: guide_name, title: title, description: description}
+        when /^upgrading\//
+          sections["upgrading"] << {name: guide_name, title: title, description: description}
+        else
+          other_guides << {name: guide_name, title: title, description: description}
+        end
+      end
+
+      # Format each section
+      sections.each do |section_name, section_guides|
+        next if section_guides.empty?
+
+        guides << "\n## #{section_name.capitalize}\n"
+        section_guides.each do |guide|
+          guides << format_guide_entry(guide[:title], guide[:name], guide[:name], guide[:description])
+        end
+      end
+
+      # Add any other guides that don't fit the standard structure
+      if other_guides.any?
+        guides << "\n## Other\n"
+        other_guides.each do |guide|
+          guides << format_guide_entry(guide[:title], guide[:name], guide[:name], guide[:description])
+        end
+      end
+
+      guides
+    end
+
+    # Format individual guide entry
+    def format_guide_entry(title, short_name, full_name, description)
+      <<~GUIDE
+        ### #{title}
+        **Guide name:** `#{short_name}`
+        #{description.empty? ? "" : "**Description:** #{description}"}
+      GUIDE
+    end
+  end
+end

data/lib/rails-mcp-server/resources/rails_guides_resource.rb

@@ -0,0 +1,29 @@
+module RailsMcpServer
+  class RailsGuidesResource < BaseResource
+    include GuideLoaderTemplate
+
+    uri "rails://guides/{guide_name}"
+    resource_name "Rails Guides"
+    description "Access to specific Rails documentation"
+    mime_type "text/markdown"
+
+    protected
+
+    def framework_name
+      "Rails"
+    end
+
+    def resource_directory
+      "rails"
+    end
+
+    def download_command
+      "rails-mcp-server-download-resources rails"
+    end
+
+    # Rails guides don't use handbook/reference sections
+    def supports_sections?
+      false
+    end
+  end
+end

data/lib/rails-mcp-server/resources/rails_guides_resources.rb

@@ -0,0 +1,37 @@
+module RailsMcpServer
+  class RailsGuidesResources < BaseResource
+    include GuideLoaderTemplate
+
+    uri "rails://guides"
+    resource_name "Rails Guides List"
+    description "Access to available Rails guides"
+    mime_type "text/markdown"
+
+    protected
+
+    def framework_name
+      "Rails"
+    end
+
+    def resource_directory
+      "rails"
+    end
+
+    def download_command
+      "rails-mcp-server-download-resources rails"
+    end
+
+    def example_guides
+      [
+        {guide: "active_record_validations", comment: "Load validations guide"},
+        {guide: "getting_started", comment: "Load getting started guide"},
+        {guide: "routing", comment: "Load routing guide"}
+      ]
+    end
+
+    # Rails guides don't use handbook/reference sections
+    def supports_sections?
+      false
+    end
+  end
+end

data/lib/rails-mcp-server/resources/stimulus_guides_resource.rb

@@ -0,0 +1,29 @@
+module RailsMcpServer
+  class StimulusGuidesResource < BaseResource
+    include GuideLoaderTemplate
+
+    uri "stimulus://guides/{guide_name}"
+    resource_name "Stimulus Guides"
+    description "Access to specific Stimulus documentation"
+    mime_type "text/markdown"
+
+    protected
+
+    def framework_name
+      "Stimulus"
+    end
+
+    def resource_directory
+      "stimulus"
+    end
+
+    def download_command
+      "rails-mcp-server-download-resources stimulus"
+    end
+
+    # Stimulus guides use handbook/reference sections
+    def supports_sections?
+      true
+    end
+  end
+end

data/lib/rails-mcp-server/resources/stimulus_guides_resources.rb

@@ -0,0 +1,37 @@
+module RailsMcpServer
+  class StimulusGuidesResources < BaseResource
+    include GuideLoaderTemplate
+
+    uri "stimulus://guides"
+    resource_name "Stimulus Guides"
+    description "Access to available Stimulus guides"
+    mime_type "text/markdown"
+
+    protected
+
+    def framework_name
+      "Stimulus"
+    end
+
+    def resource_directory
+      "stimulus"
+    end
+
+    def download_command
+      "rails-mcp-server-download-resources stimulus"
+    end
+
+    def example_guides
+      [
+        {guide: "actions", comment: "Load actions reference"},
+        {guide: "01_introduction", comment: "Load introduction"},
+        {guide: "reference/targets", comment: "Load targets with full path"}
+      ]
+    end
+
+    # Stimulus guides use handbook/reference sections
+    def supports_sections?
+      true
+    end
+  end
+end

data/lib/rails-mcp-server/resources/turbo_guides_resource.rb

@@ -0,0 +1,29 @@
+module RailsMcpServer
+  class TurboGuidesResource < BaseResource
+    include GuideLoaderTemplate
+
+    uri "turbo://guides/{guide_name}"
+    resource_name "Turbo Guides"
+    description "Access to specific Turbo documentation"
+    mime_type "text/markdown"
+
+    protected
+
+    def framework_name
+      "Turbo"
+    end
+
+    def resource_directory
+      "turbo"
+    end
+
+    def download_command
+      "rails-mcp-server-download-resources turbo"
+    end
+
+    # Turbo guides use handbook/reference sections
+    def supports_sections?
+      true
+    end
+  end
+end

data/lib/rails-mcp-server/resources/turbo_guides_resources.rb

@@ -0,0 +1,37 @@
+module RailsMcpServer
+  class TurboGuidesResources < BaseResource
+    include GuideLoaderTemplate
+
+    uri "turbo://guides"
+    resource_name "Turbo Guides"
+    description "Access to available Turbo guides"
+    mime_type "text/markdown"
+
+    protected
+
+    def framework_name
+      "Turbo"
+    end
+
+    def resource_directory
+      "turbo"
+    end
+
+    def download_command
+      "rails-mcp-server-download-resources turbo"
+    end
+
+    def example_guides
+      [
+        {guide: "drive", comment: "Load drive reference"},
+        {guide: "02_drive", comment: "Load drive handbook"},
+        {guide: "reference/frames", comment: "Load frames with full path"}
+      ]
+    end
+
+    # Turbo guides use handbook/reference sections
+    def supports_sections?
+      true
+    end
+  end
+end

data/lib/rails-mcp-server/tools/analyze_models.rb

@@ -1,6 +1,6 @@
 module RailsMcpServer
   class AnalyzeModels < BaseTool
-    tool_name "analize_models"
+    tool_name "analyze_models"
 
     description "Retrieve detailed information about Active Record models in the project. When called without parameters, lists all model files. When a specific model is specified, returns its schema, associations (has_many, belongs_to, has_one), and complete source code."