rails-mcp-server 1.1.4 → 1.2.1

data/config/resources.yml

@@ -0,0 +1,203 @@
+rails:
+  base_url: "https://raw.githubusercontent.com/rails/rails/v8.0.2/guides/source"
+  description: "Official Ruby on Rails documentation guides"
+  version: "8.0.2"
+  files:
+    # Getting Started
+    - getting_started.md
+    - install_ruby_on_rails.md
+    - getting_started_with_devcontainer.md
+
+    # Core Components
+    - active_record_basics.md
+    - active_record_migrations.md
+    - active_record_validations.md
+    - active_record_callbacks.md
+    - active_record_querying.md
+    - active_record_encryption.md
+    - active_record_multiple_databases.md
+    - active_record_postgresql.md
+    - active_record_composite_primary_keys.md
+    - association_basics.md
+
+    # Action Pack
+    - action_controller_overview.md
+    - action_controller_advanced_topics.md
+    - action_view_overview.md
+    - action_view_helpers.md
+    - layouts_and_rendering.md
+    - form_helpers.md
+    - routing.md
+
+    # Other Action Components
+    - action_mailer_basics.md
+    - action_cable_overview.md
+    - action_text_overview.md
+    - action_mailbox_basics.md
+    - active_job_basics.md
+    - active_storage_overview.md
+
+    # Active Support
+    - active_support_core_extensions.md
+    - active_support_instrumentation.md
+    - active_model_basics.md
+
+    # Configuration and Setup
+    - configuring.md
+    - command_line.md
+    - asset_pipeline.md
+    - working_with_javascript_in_rails.md
+    - autoloading_and_reloading_constants.md
+    - initialization.md
+    - rails_on_rack.md
+
+    # Advanced Topics
+    - engines.md
+    - threading_and_code_execution.md
+    - api_app.md
+    - generators.md
+    - plugins.md
+    - caching_with_rails.md
+
+    # Development and Testing
+    - testing.md
+    - debugging_rails_applications.md
+    - development_dependencies_install.md
+    - error_reporting.md
+
+    # Deployment and Performance
+    - tuning_performance_for_deployment.md
+    - upgrading_ruby_on_rails.md
+
+    # Security and Internationalization
+    - security.md
+    - i18n.md
+
+    # Contributing
+    - contributing_to_ruby_on_rails.md
+    - api_documentation_guidelines.md
+    - ruby_on_rails_guides_guidelines.md
+    - maintenance_policy.md
+
+# Stimulus JavaScript Framework Documentation
+stimulus:
+  base_url: "https://raw.githubusercontent.com/hotwired/stimulus/refs/heads/main/docs"
+  description: "Stimulus JavaScript framework documentation"
+  version: "latest"
+  files:
+    # Handbook - Main Documentation
+    - handbook/00_the_origin_of_stimulus.md
+    - handbook/01_introduction.md
+    - handbook/02_hello_stimulus.md
+    - handbook/03_building_something_real.md
+    - handbook/04_designing_for_resilience.md
+    - handbook/05_managing_state.md
+    - handbook/06_working_with_external_resources.md
+    - handbook/07_installing_stimulus.md
+
+    # Reference - API Documentation
+    - reference/actions.md
+    - reference/controllers.md
+    - reference/css_classes.md
+    - reference/lifecycle_callbacks.md
+    - reference/outlets.md
+    - reference/targets.md
+    - reference/using_typescript.md
+    - reference/values.md
+
+# Turbo Hotwire Framework Documentation
+turbo:
+  base_url: "https://raw.githubusercontent.com/hotwired/turbo-site/refs/heads/main/_source"
+  description: "Turbo Hotwire framework documentation"
+  version: "latest"
+  files:
+    # Handbook - Main Documentation
+    - handbook/01_introduction.md
+    - handbook/02_drive.md
+    - handbook/03_page_refreshes.md
+    - handbook/04_frames.md
+    - handbook/05_streams.md
+    - handbook/06_native.md
+    - handbook/07_building.md
+    - handbook/08_installing.md
+
+    # Reference - API Documentation
+    - reference/attributes.md
+    - reference/drive.md
+    - reference/events.md
+    - reference/frames.md
+    - reference/streams.md
+
+# Kamal Deploy Documentation
+kamal:
+  base_url: "https://raw.githubusercontent.com/basecamp/kamal-site/refs/heads/main/docs"
+  description: "Kamal deployment tool documentation"
+  version: "latest"
+  files:
+    # Installation
+    - installation/index.md
+    - installation/dockerized.md
+
+    # Configuration
+    - configuration/accessories.md
+    - configuration/aliases.md
+    - configuration/anchors.md
+    - configuration/booting.md
+    - configuration/builder-examples.md
+    - configuration/builders.md
+    - configuration/cron.md
+    - configuration/docker-registry.md
+    - configuration/environment-variables.md
+    - configuration/logging.md
+    - configuration/overview.md
+    - configuration/proxy.md
+    - configuration/roles.md
+    - configuration/servers.md
+    - configuration/ssh.md
+    - configuration/sshkit.md
+
+    # Commands
+    - commands/accessory.md
+    - commands/app.md
+    - commands/audit.md
+    - commands/build.md
+    - commands/config.md
+    - commands/deploy.md
+    - commands/details.md
+    - commands/docs.md
+    - commands/help.md
+    - commands/init.md
+    - commands/lock.md
+    - commands/proxy.md
+    - commands/prune.md
+    - commands/redeploy.md
+    - commands/registry.md
+    - commands/remove.md
+    - commands/rollback.md
+    - commands/running-commands-on-servers.md
+    - commands/secrets.md
+    - commands/server.md
+    - commands/setup.md
+    - commands/upgrade.md
+    - commands/version.md
+    - commands/view-all-commands.md
+
+    # Hooks
+    - hooks/overview.md
+    - hooks/docker-setup.md
+    - hooks/post-app-boot.md
+    - hooks/post-deploy.md
+    - hooks/post-proxy-reboot.md
+    - hooks/pre-app-boot.md
+    - hooks/pre-build.md
+    - hooks/pre-connect.md
+    - hooks/pre-deploy.md
+    - hooks/pre-proxy-reboot.md
+
+    # Upgrading
+    - upgrading/configuration-changes.md
+    - upgrading/continuing-to-use-traefik.md
+    - upgrading/network-changes.md
+    - upgrading/overview.md
+    - upgrading/proxy-changes.md
+    - upgrading/secrets-changes.md

data/docs/RESOURCES.md

@@ -0,0 +1,339 @@
+# Rails MCP Server - Resources Guide
+
+This guide explains how the Rails MCP Server handles documentation resources, how to download predefined guides, and how to load custom documentation files. Resources in the Rails MCP Server provide access to comprehensive documentation for Rails and related frameworks through both the `load_guide` tool and direct MCP resource access.
+
+## Table of Contents
+
+- [What are Resources?](#what-are-resources)
+- [Available Resource Categories](#available-resource-categories)
+- [Downloading Predefined Resources](#downloading-predefined-resources)
+- [Loading Custom Files](#loading-custom-files)
+- [Using the load_guide Tool](#using-the-load_guide-tool)
+- [Direct Resource Access](#direct-resource-access)
+- [Troubleshooting](#troubleshooting)
+
+## What are Resources?
+
+Resources in the Rails MCP Server are documentation guides that can be accessed through two main methods:
+
+1. **Tool-based access**: Using the `load_guide` tool to retrieve specific guides
+2. **Direct resource access**: MCP clients can directly query resources using URI templates
+
+Resources are stored locally in your configuration directory and can be:
+- **Predefined resources**: Official documentation from Rails, Turbo, Stimulus, and Kamal
+- **Custom resources**: Your own markdown files imported into the system
+
+## Available Resource Categories
+
+The Rails MCP Server supports five categories of resources:
+
+### 1. Rails Guides
+- **Framework**: Ruby on Rails
+- **Content**: Official Rails 8.0.2 documentation
+
+### 2. Turbo Guides  
+- **Framework**: Turbo (Hotwire)
+- **Content**: Official Turbo framework documentation
+
+### 3. Stimulus Guides
+- **Framework**: Stimulus (Hotwire)
+- **Content**: Official Stimulus JavaScript framework documentation
+
+### 4. Kamal Guides
+- **Framework**: Kamal Deploy
+- **Content**: Official Kamal deployment tool documentation
+
+### 5. Custom Guides
+- **Framework**: Custom/Local
+- **Content**: Your imported markdown files
+
+## Downloading Predefined Resources
+
+Before you can use predefined resources, you need to download them using the resource downloader tool.
+
+### Basic Download Command
+
+```bash
+# Download Rails guides
+rails-mcp-server-download-resources rails
+
+# Download Turbo guides  
+rails-mcp-server-download-resources turbo
+
+# Download Stimulus guides
+rails-mcp-server-download-resources stimulus
+
+# Download Kamal guides
+rails-mcp-server-download-resources kamal
+```
+
+### Download Options
+
+```bash
+# Force download even if files haven't changed
+rails-mcp-server-download-resources --force rails
+
+# Verbose output to see download progress
+rails-mcp-server-download-resources --verbose turbo
+
+# Combine options
+rails-mcp-server-download-resources --verbose --force stimulus
+```
+
+### Download Process
+
+When you run the download command:
+
+1. **Creates directories**: Sets up the resource folder structure in your config directory
+2. **Downloads guides**: Fetches the latest documentation from official repositories
+3. **Creates manifest**: Generates a manifest.yaml file tracking all downloaded files
+4. **Tracks changes**: Monitors file modifications to avoid unnecessary re-downloads
+
+### Resource Storage Location
+
+Downloaded resources are stored in:
+- **macOS**: `~/.config/rails-mcp/resources/`
+- **Windows**: `%APPDATA%\rails-mcp\resources\`
+
+Directory structure:
+```
+~/.config/rails-mcp/resources/
+├── rails/
+│   ├── manifest.yaml
+│   ├── getting_started.md
+│   ├── active_record_basics.md
+│   └── ...
+├── turbo/
+│   ├── manifest.yaml
+│   ├── handbook/
+│   │   ├── 01_introduction.md
+│   │   └── ...
+│   └── reference/
+│       ├── streams.md
+│       └── ...
+├── stimulus/
+├── kamal/
+└── custom/
+```
+
+## Loading Custom Files
+
+You can import your own markdown files into the Custom guides category using the `--file` option.
+
+### Import Single File
+
+```bash
+# Import a single markdown file
+rails-mcp-server-download-resources --file /path/to/guide.md
+
+# Force import even if file hasn't changed
+rails-mcp-server-download-resources --force --file /path/to/api-docs.md
+```
+
+### Import Directory
+
+```bash
+# Import all markdown files from a directory
+rails-mcp-server-download-resources --file /path/to/docs/
+
+# Verbose import with progress information
+rails-mcp-server-download-resources --verbose --file /path/to/project-docs/
+```
+
+### Import Process
+
+When importing custom files:
+
+1. **File validation**: Checks that source files exist and are readable
+2. **Filename normalization**: Converts filenames to lowercase with underscores
+3. **Duplication handling**: Skips unchanged files unless `--force` is used
+4. **Manifest updates**: Tracks imported files in the custom manifest
+
+### Filename Normalization
+
+Custom files are normalized for consistency:
+- `API Documentation.md` → `api_documentation.md`
+- `Setup-Guide.md` → `setup_guide.md`
+- `user_manual.md` → `user_manual.md` (already normalized)
+
+## Using the load_guide Tool
+
+The `load_guide` tool is the primary way to access resources programmatically within MCP conversations.
+
+### Basic Syntax
+
+```
+load_guide guides: "category" guide: "guide_name"
+```
+
+### Loading Specific Guides
+
+#### Rails Guides
+```
+Can you load the Rails getting started guide?
+
+I need to see the Active Record basics documentation.
+
+Show me the Rails routing guide.
+```
+
+#### Turbo Guides
+```
+Can you load the Turbo introduction guide?
+
+I'd like to see the Turbo Frames documentation.
+
+Show me the Turbo streams reference.
+```
+
+#### Stimulus Guides  
+```
+Load the Hello Stimulus tutorial for me.
+
+I need help with Stimulus controllers - can you show me that guide?
+
+Can you display the Stimulus targets reference?
+```
+
+#### Kamal Guides
+```
+Show me the Kamal installation guide.
+
+I need to understand Kamal deployment - can you load that documentation?
+
+Can you get the Kamal configuration overview?
+```
+
+#### Custom Guides
+```
+Load my API documentation guide.
+
+Can you show me the setup guide I imported?
+
+I need to see my custom user manual.
+```
+
+### Listing Available Guides
+
+```
+What Rails guides are available?
+
+Show me all the Turbo documentation.
+
+List the available custom guides I've imported.
+```
+
+### Tool Output Format
+
+The `load_guide` tool returns formatted content with:
+
+```markdown
+# Guide Title
+
+**Source:** Framework Name
+**Guide:** guide_name
+**File:** path/to/file.md (for sectioned guides)
+
+---
+
+[Guide content here...]
+```
+
+## Direct Resource Access
+
+MCP clients that support resources can access documentation directly without using the `load_guide` tool.
+
+### Resource URIs
+
+Each resource category has specific URI patterns:
+
+#### List Resources (Available Guides)
+- `rails://guides` - List all Rails guides
+- `turbo://guides` - List all Turbo guides  
+- `stimulus://guides` - List all Stimulus guides
+- `kamal://guides` - List all Kamal guides
+- `custom://guides` - List all custom guides
+
+#### Specific Guide Resources
+- `rails://guides/{guide_name}` - Access specific Rails guide
+- `turbo://guides/{guide_name}` - Access specific Turbo guide
+- `stimulus://guides/{guide_name}` - Access specific Stimulus guide
+- `kamal://guides/{guide_name}` - Access specific Kamal guide
+- `custom://guides/{guide_name}` - Access specific custom guide
+
+### Resource Metadata
+
+Each resource includes metadata:
+- `resource_name`: Human-readable name
+- `description`: Resource description
+- `mime_type`: Content type (text/markdown)
+- `uri`: URI template pattern
+
+## Troubleshooting
+
+### Common Issues
+
+#### Resource Not Found
+```
+Error: Unknown resource: rails
+```
+**Solution**: Check available resources with `--help` flag
+
+#### Download Failures
+```
+failed (HTTP 404)
+```
+**Solution**: Resource may have moved; try updating or check internet connection
+
+#### Permission Errors
+```
+Error: Source not readable: /path/to/file
+```
+**Solution**: Check file permissions and path existence
+
+#### Guide Not Found
+```
+Guide 'invalid_guide' not found in Rails guides.
+```
+**Solution**: Use `load_guide guides: "rails"` to see available guides
+
+### Verbose Troubleshooting
+
+Use verbose mode for detailed information:
+
+```bash
+# Verbose download
+rails-mcp-server-download-resources --verbose rails
+
+# Verbose import
+rails-mcp-server-download-resources --verbose --file /path/to/docs/
+```
+
+### Manual Resource Management
+
+If needed, you can manually manage resources:
+
+```bash
+# Remove all downloaded resources
+rm -rf ~/.config/rails-mcp/resources/
+
+# Re-download everything  
+rails-mcp-server-download-resources rails
+rails-mcp-server-download-resources turbo
+rails-mcp-server-download-resources stimulus
+rails-mcp-server-download-resources kamal
+```
+
+## Best Practices
+
+### Resource Organization
+1. **Download first**: Always download resources before using the `load_guide` tool
+2. **Update regularly**: Keep resources current by re-downloading periodically
+3. **Organize custom guides**: Use descriptive filenames for custom imports
+
+### Performance Tips
+1. **Selective downloads**: Only download resources you need
+2. **Avoid force**: Don't use `--force` unless necessary
+3. **Batch imports**: Import multiple custom files at once using directory paths
+
+This comprehensive resource system makes the Rails MCP Server a powerful documentation companion for Rails development, providing instant access to official guides and your custom documentation through both tool-based and direct resource access methods.

data/exe/rails-mcp-server

@@ -63,17 +63,20 @@ while i < ARGV.length
   end
 end
 
-RailsMcpServer.config do |config|
-  config.log_level = log_level
-end
-
+RailsMcpServer.config.log_level = log_level
 RailsMcpServer.log(:info, "Starting Rails MCP Server in #{mode} mode...")
 
 # Create tools configuration for both modes
 def setup_mcp_tools(server)
   server.register_tools(RailsMcpServer::SwitchProject, RailsMcpServer::ProjectInfo,
     RailsMcpServer::ListFiles, RailsMcpServer::GetFile, RailsMcpServer::GetRoutes, RailsMcpServer::AnalyzeModels,
-    RailsMcpServer::GetSchema, RailsMcpServer::AnalyzeControllerViews, RailsMcpServer::AnalyzeEnvironmentConfig)
+    RailsMcpServer::GetSchema, RailsMcpServer::AnalyzeControllerViews, RailsMcpServer::AnalyzeEnvironmentConfig,
+    RailsMcpServer::LoadGuide)
+
+  server.register_resources(RailsMcpServer::RailsGuidesResource, RailsMcpServer::RailsGuidesResources,
+    RailsMcpServer::StimulusGuidesResource, RailsMcpServer::StimulusGuidesResources, RailsMcpServer::TurboGuidesResource,
+    RailsMcpServer::TurboGuidesResources, RailsMcpServer::CustomGuidesResource, RailsMcpServer::CustomGuidesResources,
+    RailsMcpServer::KamalGuidesResource, RailsMcpServer::KamalGuidesResources)
 end
 
 case mode

data/exe/rails-mcp-server-download-resources

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+
+require "optparse"
+require_relative "../lib/rails-mcp-server/config"
+require_relative "../lib/rails-mcp-server/helpers/resource_downloader"
+require_relative "../lib/rails-mcp-server/helpers/resource_importer"
+
+def show_help(parser, config_dir)
+  puts parser
+  puts "\nAvailable resources:"
+
+  available = RailsMcpServer::ResourceDownloader.available_resources(config_dir)
+  if available.any?
+    available.each { |resource| puts "  - #{resource}" }
+  else
+    puts "  No resources configured"
+  end
+
+  puts "\nOr use --file to import custom markdown files"
+end
+
+def print_summary(action, results)
+  puts "\n#{action} Summary:"
+  if action == "Import"
+    puts "  Imported: #{results[:imported]}"
+  else
+    puts "  Downloaded: #{results[:downloaded]}"
+  end
+  puts "  Skipped: #{results[:skipped]}"
+  puts "  Failed: #{results[:failed]}"
+end
+
+options = {
+  force: false,
+  verbose: false,
+  file: nil
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: rails-mcp-server-download-resources [options] RESOURCE_NAME"
+  opts.separator ""
+  opts.separator "Downloads documentation resources for Rails MCP Server"
+  opts.separator ""
+
+  opts.on("-f", "--force", "Force download/import even if files haven't changed") do
+    options[:force] = true
+  end
+
+  opts.on("-v", "--verbose", "Verbose output") do
+    options[:verbose] = true
+  end
+
+  opts.on("--file PATH", "Import custom markdown file(s) from PATH") do |path|
+    options[:file] = path
+  end
+
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    puts ""
+    puts "Examples:"
+    puts "  rails-mcp-server-download-resources rails"
+    puts "  rails-mcp-server-download-resources --file /path/to/guide.md"
+    puts "  rails-mcp-server-download-resources --file /path/to/guides/"
+    puts "  rails-mcp-server-download-resources --verbose --force stimulus"
+    exit
+  end
+end
+
+parser.parse!
+
+begin
+  # Get config directory without requiring Rails projects
+  config_dir = File.expand_path("~/.config/rails-mcp")
+
+  # Handle file import
+  if options[:file]
+    unless File.exist?(options[:file])
+      puts "Error: File or directory not found: #{options[:file]}"
+      exit 1
+    end
+
+    importer = RailsMcpServer::ResourceImporter.new(
+      "custom",
+      config_dir: config_dir,
+      source_path: options[:file],
+      force: options[:force],
+      verbose: options[:verbose]
+    )
+
+    results = importer.import
+    print_summary("Import", results)
+    exit (results[:failed] > 0) ? 1 : 0
+  end
+
+  # Handle resource download
+  if ARGV.empty?
+    show_help(parser, config_dir)
+    exit 1
+  end
+
+  resource_name = ARGV[0]
+  downloader = RailsMcpServer::ResourceDownloader.new(
+    resource_name,
+    config_dir: config_dir,
+    force: options[:force],
+    verbose: options[:verbose]
+  )
+
+  results = downloader.download
+  print_summary("Download", results)
+  exit (results[:failed] > 0) ? 1 : 0
+rescue RailsMcpServer::ResourceDownloader::DownloadError,
+  RailsMcpServer::ResourceImporter::ImportError => e
+  puts "Error: #{e.message}"
+  exit 1
+rescue => e
+  puts "Unexpected error: #{e.message}"
+  puts e.backtrace if options[:verbose]
+  exit 1
+end

data/lib/rails-mcp-server/config.rb

@@ -2,7 +2,8 @@ require "logger"
 
 module RailsMcpServer
   class Config
-    attr_accessor :logger, :log_level, :projects, :current_project, :active_project_path
+    attr_accessor :logger, :projects, :current_project, :active_project_path, :config_dir
+    attr_reader :log_level
 
     def self.setup
       new.tap do |instance|
@@ -20,6 +21,11 @@ module RailsMcpServer
       load_projects
     end
 
+    def log_level=(level)
+      @log_level = LEVELS[level] || Logger::INFO
+      @logger.level = @log_level
+    end
+
     private
 
     def load_projects