rails-mcp-server 1.1.4 → 1.2.1

data/lib/rails-mcp-server/helpers/resource_downloader.rb

@@ -0,0 +1,104 @@
+require "net/http"
+require "uri"
+require_relative "resource_base"
+
+module RailsMcpServer
+  class ResourceDownloader < ResourceBase
+    class DownloadError < StandardError; end
+
+    def initialize(resource_name, config_dir:, force: false, verbose: false)
+      super
+      load_config
+    end
+
+    def download
+      setup_directories
+      load_manifest
+
+      log "Downloading #{@resource_name} resources..."
+
+      results = {downloaded: 0, skipped: 0, failed: 0}
+
+      @config["files"].each do |file|
+        result = download_file(file)
+        results[result] += 1
+      end
+
+      save_manifest
+      results
+    end
+
+    def self.available_resources(config_dir)
+      config_file = File.join(File.dirname(__FILE__), "..", "..", "..", "config", "resources.yml")
+      return [] unless File.exist?(config_file)
+
+      YAML.load_file(config_file).keys
+    rescue => e
+      warn "Failed to load resource configuration: #{e.message}"
+      []
+    end
+
+    protected
+
+    def create_manifest
+      {
+        "resource" => @resource_name,
+        "base_url" => @config["base_url"],
+        "description" => @config["description"],
+        "version" => @config["version"],
+        "files" => {},
+        "created_at" => Time.now.to_s,
+        "updated_at" => Time.now.to_s
+      }
+    end
+
+    def timestamp_key
+      "downloaded_at"
+    end
+
+    private
+
+    def load_config
+      config_file = File.join(File.dirname(__FILE__), "..", "..", "..", "config", "resources.yml")
+
+      raise DownloadError, "Resource configuration file not found" unless File.exist?(config_file)
+
+      all_configs = YAML.load_file(config_file)
+      @config = all_configs[@resource_name]
+
+      raise DownloadError, "Unknown resource: #{@resource_name}" unless @config
+    end
+
+    def download_file(filename)
+      file_path = File.join(@resource_folder, filename)
+      url = "#{@config["base_url"]}/#{filename}"
+
+      # Skip if unchanged
+      if !@force && file_unchanged?(filename, file_path)
+        log "Skipping #{filename} (unchanged)"
+        return :skipped
+      end
+
+      log "Downloading #{filename}... ", newline: false
+
+      begin
+        uri = URI(url)
+        response = Net::HTTP.get_response(uri)
+
+        if response.code == "200"
+          FileUtils.mkdir_p(File.dirname(file_path))
+          File.write(file_path, response.body)
+          save_file_to_manifest(filename, file_path)
+          log "done"
+          :downloaded
+        else
+          log "failed (HTTP #{response.code})"
+          :failed
+        end
+      rescue => e
+        log "failed (#{e.message})"
+        :failed
+      end
+    end
+  end
+end

data/lib/rails-mcp-server/helpers/resource_importer.rb

@@ -0,0 +1,113 @@
+require_relative "resource_base"
+
+module RailsMcpServer
+  class ResourceImporter < ResourceBase
+    class ImportError < StandardError; end
+
+    def initialize(resource_name, config_dir:, source_path:, force: false, verbose: false)
+      @source_path = source_path
+      super(resource_name, config_dir: config_dir, force: force, verbose: verbose)
+      validate_source
+    end
+
+    def import
+      setup_directories
+      load_manifest
+
+      log "Importing custom files from #{@source_path}..."
+
+      results = {imported: 0, skipped: 0, failed: 0}
+      files = collect_files
+
+      if files.empty?
+        log "No markdown files found"
+        save_manifest
+        return results
+      end
+
+      files.each do |file_path|
+        result = import_file(file_path)
+        results[result] += 1
+      end
+
+      save_manifest
+      results
+    end
+
+    protected
+
+    def create_manifest
+      {
+        "resource" => @resource_name,
+        "base_url" => "local",
+        "description" => "Custom imported documentation",
+        "files" => {},
+        "created_at" => Time.now.to_s,
+        "updated_at" => Time.now.to_s
+      }
+    end
+
+    def timestamp_key
+      "imported_at"
+    end
+
+    private
+
+    def validate_source
+      raise ImportError, "Source not found: #{@source_path}" unless File.exist?(@source_path)
+      raise ImportError, "Source not readable: #{@source_path}" unless File.readable?(@source_path)
+    end
+
+    def collect_files
+      if File.file?(@source_path)
+        markdown?(@source_path) ? [@source_path] : []
+      elsif File.directory?(@source_path)
+        Dir.glob(File.join(@source_path, "*.md")).select { |f| File.file?(f) }.sort # rubocop:disable Performance/ChainArrayAllocation
+      else
+        []
+      end
+    end
+
+    def markdown?(file_path)
+      File.extname(file_path).casecmp(".md").zero?
+    end
+
+    def import_file(file_path)
+      original_filename = File.basename(file_path)
+      normalized_filename = normalize_filename(original_filename)
+      destination_path = File.join(@resource_folder, normalized_filename)
+
+      # Skip if unchanged
+      if !@force && file_unchanged?(normalized_filename, file_path)
+        log "Skipping #{original_filename} (unchanged)"
+        return :skipped
+      end
+
+      log "Importing #{original_filename} -> #{normalized_filename}... ", newline: false
+
+      begin
+        FileUtils.cp(file_path, destination_path)
+        save_file_to_manifest(normalized_filename, destination_path,
+          {"original_filename" => original_filename})
+        log "done"
+        :imported
+      rescue => e
+        log "failed (#{e.message})"
+        :failed
+      end
+    end
+
+    def normalize_filename(filename)
+      basename = File.basename(filename, ".md")
+      extension = File.extname(filename)
+
+      normalized = basename.downcase
+        .gsub(/[^a-z0-9_\-.]/, "_")
+        .squeeze("_")
+        .gsub(/^_+|_+$/, "")
+
+      normalized = "untitled" if normalized.empty?
+      "#{normalized}#{extension}"
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+module RailsMcpServer
+  class BaseResource < FastMcp::Resource
+    extend Forwardable
+
+    def_delegators :RailsMcpServer, :log, :config_dir
+  end
+end

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

@@ -0,0 +1,54 @@
+module RailsMcpServer
+  class CustomGuidesResource < BaseResource
+    include GuideLoaderTemplate
+
+    uri "custom://guides/{guide_name}"
+    resource_name "Custom Guides"
+    description "Access to specific custom imported documentation"
+    mime_type "text/markdown"
+
+    protected
+
+    def framework_name
+      "Custom"
+    end
+
+    def resource_directory
+      "custom"
+    end
+
+    def download_command
+      "rails-mcp-server-download-resources --file /path/to/files"
+    end
+
+    # Custom guides don't use handbook/reference sections (flat structure like Rails)
+    def supports_sections?
+      false
+    end
+
+    # Custom display name to show original filename
+    def customize_display_name(guide_name, guide_data)
+      guide_data["original_filename"] || guide_name
+    end
+
+    # Custom error message for imports
+    def customize_not_found_message(message, guide_name)
+      message + "\n**Note:** Make sure you've imported your custom guides with `#{download_command}`\n"
+    end
+
+    # Custom manifest error handling
+    def handle_manifest_error(error)
+      case error.message
+      when /No Custom guides found/
+        format_error_message(
+          "No custom guides found. Import guides with:\n" \
+          "`rails-mcp-server-download-resources --file /path/to/guide.md`\n" \
+          "or\n" \
+          "`rails-mcp-server-download-resources --file /path/to/guides/`"
+        )
+      else
+        super
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+module RailsMcpServer
+  class CustomGuidesResources < BaseResource
+    include GuideLoaderTemplate
+
+    uri "custom://guides"
+    resource_name "Custom Guides"
+    description "Access to available custom imported guides"
+    mime_type "text/markdown"
+
+    protected
+
+    def framework_name
+      "Custom"
+    end
+
+    def resource_directory
+      "custom"
+    end
+
+    def download_command
+      "rails-mcp-server-download-resources --file /path/to/files"
+    end
+
+    def example_guides
+      [
+        {guide: "api_documentation", comment: "Load API documentation"},
+        {guide: "setup_guide", comment: "Load setup instructions"},
+        {guide: "user_manual", comment: "Load user manual"}
+      ]
+    end
+
+    # Custom guides don't use handbook/reference sections (flat structure like Rails)
+    def supports_sections?
+      false
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+module RailsMcpServer
+  # Module for formatting guide content and messages
+  module GuideContentFormatter
+    protected
+
+    # Format the guide content with appropriate headers
+    def format_guide_content(content, guide_name, guide_data, filename)
+      title = guide_data["title"] || generate_title_from_filename(filename)
+
+      header = if supports_sections?
+        section = determine_section(filename)
+        <<~HEADER
+          # #{title}
+
+          **Source:** #{framework_name} #{section}
+          **Guide:** #{guide_name}
+          **File:** #{filename}
+
+          ---
+
+        HEADER
+      else
+        <<~HEADER
+          # #{title}
+
+          **Source:** #{framework_name} Guides
+          **Guide:** #{guide_name}
+
+          ---
+
+        HEADER
+      end
+
+      header + content
+    end
+
+    # Format individual guide entry for listings
+    def format_guide_entry(title, short_name, full_name, description)
+      if supports_sections? && short_name != full_name
+        <<~GUIDE
+          ### #{title}
+          **Guide name:** `#{short_name}` or `#{full_name}`
+          #{description.empty? ? "" : "**Description:** #{description}"}
+        GUIDE
+      else
+        <<~GUIDE
+          ## #{title}
+          **Guide name:** `#{short_name}`
+          #{description.empty? ? "" : "**Description:** #{description}"}
+        GUIDE
+      end
+    end
+
+    # Format usage examples section
+    def format_usage_examples
+      examples = example_guides
+
+      usage = "\n## Example Usage:\n"
+      usage += "```\n"
+
+      examples.each do |example|
+        usage += "load_guide guides: \"#{framework_name.downcase}\", guide: \"#{example[:guide]}\"#{example[:comment] ? " # " + example[:comment] : ""}\n"
+      end
+
+      usage += "```\n"
+      usage
+    end
+
+    # Determine section from filename (handbook/reference/etc)
+    def determine_section(filename)
+      return "Handbook" if filename.start_with?("handbook/")
+      return "Reference" if filename.start_with?("reference/")
+
+      # Framework-specific section detection can be overridden
+      framework_specific_section(filename) if respond_to?(:framework_specific_section, true)
+
+      "Documentation"
+    end
+
+    # Format guides organized by sections (handbook/reference)
+    def format_sectioned_guides(guide_files)
+      sectioned = get_sectioned_guide_files(guide_files.keys.zip(guide_files.values).to_h)
+      guides = []
+
+      # Add handbook section
+      if sectioned[:handbook].any?
+        guides << "\n## Handbook (Main Documentation)\n"
+        sectioned[:handbook].each do |filename, file_data|
+          metadata = extract_guide_metadata(filename, file_data)
+          short_name = metadata[:guide_name].sub("handbook/", "")
+          guides << format_guide_entry(metadata[:title], short_name, metadata[:guide_name], metadata[:description])
+        end
+      end
+
+      # Add reference section
+      if sectioned[:reference].any?
+        guides << "\n## Reference (API Documentation)\n"
+        sectioned[:reference].each do |filename, file_data|
+          metadata = extract_guide_metadata(filename, file_data)
+          short_name = metadata[:guide_name].sub("reference/", "")
+          guides << format_guide_entry(metadata[:title], short_name, metadata[:guide_name], metadata[:description])
+        end
+      end
+
+      # Add other sections
+      if sectioned[:other].any?
+        guides << "\n## Other Guides\n"
+        sectioned[:other].each do |filename, file_data|
+          metadata = extract_guide_metadata(filename, file_data)
+          guides << format_guide_entry(metadata[:title], metadata[:guide_name], metadata[:guide_name], metadata[:description])
+        end
+      end
+
+      guides
+    end
+
+    # Format guides in a flat structure (no sections)
+    def format_flat_guides(guide_files)
+      guides = []
+
+      guide_files.each do |filename, file_data|
+        log(:debug, "Processing guide: #{filename}")
+        metadata = extract_guide_metadata(filename, file_data)
+        guides << format_guide_entry(metadata[:title], metadata[:guide_name], metadata[:guide_name], metadata[:description])
+      end
+
+      guides
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+module RailsMcpServer
+  # Module for handling guide-related errors and messages
+  module GuideErrorHandler
+    protected
+
+    # Format error messages consistently
+    def format_error_message(message)
+      "# Error\n\n#{message}"
+    end
+
+    # Create standardized not found message
+    def create_not_found_message(guide_name, available_guides)
+      normalized_guide_name = guide_name.gsub(/[^a-zA-Z0-9_\/.-]/, "").downcase
+      suggestions = find_suggestions(normalized_guide_name, available_guides)
+
+      message = "# Guide Not Found\n\n"
+      message += "Guide '#{guide_name}' not found in #{framework_name} guides.\n\n"
+
+      if suggestions.any?
+        message += "## Did you mean one of these?\n\n"
+        suggestions.each { |suggestion| message += "- #{suggestion}\n" }
+        message += "\n**Try:** `load_guide guides: \"#{framework_name.downcase}\", guide: \"#{suggestions.first}\"`\n"
+      else
+        message += format_available_guides_section(available_guides)
+        message += "Use `load_guide guides: \"#{framework_name.downcase}\"` to see all available guides with descriptions.\n"
+      end
+
+      message
+    end
+
+    # Format available guides section for error messages
+    def format_available_guides_section(available_guides)
+      return "\n" unless supports_sections?
+
+      handbook_guides = available_guides.select { |g| g.start_with?("handbook/") }
+      reference_guides = available_guides.select { |g| g.start_with?("reference/") }
+
+      message = "## Available #{framework_name} Guides:\n\n"
+
+      if handbook_guides.any?
+        message += "### Handbook:\n"
+        handbook_guides.each { |guide| message += "- #{guide.sub("handbook/", "")}\n" }
+        message += "\n"
+      end
+
+      if reference_guides.any?
+        message += "### Reference:\n"
+        reference_guides.each { |guide| message += "- #{guide.sub("reference/", "")}\n" }
+        message += "\n"
+      end
+
+      message
+    end
+
+    # Handle manifest loading errors with user-friendly messages
+    def handle_manifest_error(error)
+      case error.message
+      when /No .* guides found/
+        error.message
+      when /Permission denied/
+        format_error_message("Permission denied accessing guides. Check file permissions.")
+      when /No such file/
+        format_error_message("Guide files not found. Run '#{download_command}' to download guides.")
+      else
+        format_error_message("Error loading guides: #{error.message}")
+      end
+    end
+
+    # Handle guide loading errors
+    def handle_guide_loading_error(guide_name, error)
+      log(:error, "Error loading guide #{guide_name}: #{error.message}")
+
+      case error.message
+      when /Multiple guides found/
+        format_error_message(error.message)
+      when /Permission denied/
+        format_error_message("Permission denied reading guide '#{guide_name}'.")
+      when /No such file/
+        format_error_message("Guide file for '#{guide_name}' not found on disk.")
+      else
+        format_error_message("Error loading guide '#{guide_name}': #{error.message}")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+module RailsMcpServer
+  # Module for finding and matching guide files
+  module GuideFileFinder
+    protected
+
+    # Find guide file with exact and fuzzy matching
+    def find_guide_file(normalized_guide_name, manifest)
+      # Try exact matches first
+      possible_filenames = generate_possible_filenames(normalized_guide_name)
+
+      possible_filenames.each do |possible_filename|
+        if manifest["files"][possible_filename]
+          return [possible_filename, manifest["files"][possible_filename]]
+        end
+      end
+
+      # If not found, try fuzzy matching
+      matching_files = fuzzy_match_files(normalized_guide_name, manifest)
+
+      case matching_files.size
+      when 1
+        matching_files.first
+      when 0
+        [nil, nil]
+      else
+        matches = matching_files.map(&:first).map { |f| f.sub(".md", "") }.join(", ") # rubocop:disable Performance/ChainArrayAllocation
+        raise StandardError, "Multiple guides found matching '#{normalized_guide_name}': #{matches}. Please be more specific."
+      end
+    end
+
+    # Generate possible filename variations for exact matching
+    def generate_possible_filenames(normalized_guide_name)
+      possible_files = ["#{normalized_guide_name}.md"]
+
+      # Add section prefixes for frameworks that support them
+      if supports_sections?
+        possible_files += [
+          "handbook/#{normalized_guide_name}.md",
+          "reference/#{normalized_guide_name}.md"
+        ]
+      end
+
+      # Framework-specific filename generation can be overridden
+      possible_files += framework_specific_filenames(normalized_guide_name) if respond_to?(:framework_specific_filenames, true)
+
+      possible_files.uniq
+    end
+
+    # Perform fuzzy matching on guide files
+    def fuzzy_match_files(normalized_guide_name, manifest)
+      search_terms = generate_search_terms(normalized_guide_name)
+
+      manifest["files"].select do |file, _|
+        next false unless file.end_with?(".md")
+
+        file_matches_any_search_term?(file, search_terms)
+      end.to_a
+    end
+
+    # Generate search terms for fuzzy matching
+    def generate_search_terms(normalized_guide_name)
+      base_term = normalized_guide_name.split("/").last.downcase
+
+      [
+        base_term,
+        base_term.gsub(/[_-]/, ""),
+        base_term.gsub(/[_-]/, "_"),
+        base_term.gsub(/[_-]/, "-")
+      ].uniq
+    end
+
+    # Check if file matches any search term
+    def file_matches_any_search_term?(file, search_terms)
+      file_name_base = file.sub(".md", "").split("/").last.downcase
+      file_name_normalized = file_name_base.gsub(/[_-]/, "")
+
+      search_terms.any? do |term|
+        term_normalized = term.gsub(/[_-]/, "")
+
+        file_name_base.include?(term) ||
+          term.include?(file_name_base) ||
+          file_name_normalized.include?(term_normalized) ||
+          term_normalized.include?(file_name_normalized)
+      end
+    end
+
+    # Generate suggestions for similar guide names
+    def find_suggestions(normalized_guide_name, available_guides)
+      search_base = normalized_guide_name.split("/").last.downcase
+
+      available_guides.select do |guide|
+        guide_base = guide.split("/").last.downcase
+
+        guide_base.include?(search_base) ||
+          search_base.include?(guide_base) ||
+          guide_base.gsub(/[_-]/, "").include?(search_base.gsub(/[_-]/, ""))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module RailsMcpServer
+  # Module defining the contract that guide resources must implement
+  module GuideFrameworkContract
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Validate that required methods are implemented
+      def validate_contract!
+        required_methods = [:framework_name, :resource_directory, :download_command]
+
+        required_methods.each do |method|
+          unless method_defined?(method)
+            raise NotImplementedError, "#{self} must implement ##{method}"
+          end
+        end
+      end
+    end
+
+    protected
+
+    # Abstract methods that must be implemented by including classes
+    def framework_name
+      raise NotImplementedError, "#{self.class} must implement #framework_name"
+    end
+
+    def resource_directory
+      raise NotImplementedError, "#{self.class} must implement #resource_directory"
+    end
+
+    def download_command
+      raise NotImplementedError, "#{self.class} must implement #download_command"
+    end
+
+    # Optional methods with default implementations
+    def supports_sections?
+      false
+    end
+
+    # Optional method for list resources
+    def example_guides
+      []
+    end
+
+    # Optional framework-specific methods (can be overridden)
+    def framework_specific_filenames(normalized_guide_name)
+      []
+    end
+
+    def framework_specific_section(filename)
+      "Documentation"
+    end
+
+    # Utility method to check if this is a list resource
+    def list_resource?
+      respond_to?(:example_guides)
+    end
+
+    # Utility method to check if this is a single guide resource
+    def single_guide_resource?
+      respond_to?(:params) && params.key?(:guide_name)
+    end
+  end
+end