rails-active-mcp 0.1.7 → 2.0.8

data/examples/rails_app_integration.md

@@ -0,0 +1,405 @@
+# Rails Active MCP - Real-World Integration Examples
+
+This guide demonstrates how to integrate Rails Active MCP in various real-world scenarios, following the best practices outlined in the [Rails application structure guide](https://dev.to/kimrgrey/tuning-rails-application-structure-5f74).
+
+## E-commerce Application Example
+
+### Model Setup
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_many :orders, dependent: :destroy
+  has_one :profile, dependent: :destroy
+  
+  validates :email, presence: true, uniqueness: true
+  scope :active, -> { where(active: true) }
+end
+
+# app/models/order.rb
+class Order < ApplicationRecord
+  belongs_to :user
+  has_many :order_items, dependent: :destroy
+  has_many :products, through: :order_items
+  
+  validates :total_amount, presence: true, numericality: { greater_than: 0 }
+  scope :recent, -> { where('created_at > ?', 1.week.ago) }
+end
+
+# app/models/product.rb
+class Product < ApplicationRecord
+  has_many :order_items
+  has_many :orders, through: :order_items
+  
+  validates :name, presence: true
+  validates :price, presence: true, numericality: { greater_than: 0 }
+  scope :available, -> { where(available: true) }
+end
+```
+
+### Configuration for E-commerce
+```ruby
+# config/initializers/rails_active_mcp.rb
+RailsActiveMcp.configure do |config|
+  # Core safety settings
+  config.safe_mode = true
+  config.max_results = 100
+  config.command_timeout = 30
+  
+  # Environment-specific settings
+  case Rails.env
+  when 'production'
+    # Strict production settings
+    config.safe_mode = true
+    config.max_results = 50
+    config.command_timeout = 15
+    config.log_executions = true
+    
+    # Only allow safe models in production
+    config.allowed_models = %w[User Order Product OrderItem]
+    
+  when 'development'
+    # More permissive for development
+    config.safe_mode = false
+    config.max_results = 200
+    config.command_timeout = 60
+    config.log_level = :debug
+    
+  when 'staging'
+    # Production-like but slightly more permissive
+    config.safe_mode = true
+    config.max_results = 100
+    config.command_timeout = 30
+    config.log_executions = true
+  end
+  
+  # Custom safety patterns for e-commerce
+  config.custom_safety_patterns = [
+    { 
+      pattern: /payment.*delete|destroy.*payment/i, 
+      description: "Payment data modification is dangerous" 
+    },
+    { 
+      pattern: /User.*\.update_all.*role/i, 
+      description: "Mass role updates are dangerous" 
+    }
+  ]
+end
+```
+
+### Claude Desktop Queries for E-commerce
+
+#### Sales Analytics
+```ruby
+# Ask Claude: "What are our sales metrics for the last week?"
+Order.recent.sum(:total_amount)
+Order.recent.count
+Order.recent.average(:total_amount)
+
+# Ask Claude: "Who are our top customers by order value?"
+User.joins(:orders)
+    .group('users.id', 'users.email')
+    .order('SUM(orders.total_amount) DESC')
+    .limit(10)
+    .pluck('users.email', 'SUM(orders.total_amount)')
+```
+
+#### Inventory Management
+```ruby
+# Ask Claude: "Which products are running low on inventory?"
+Product.where('inventory_count < ?', 10)
+        .order(:inventory_count)
+        .pluck(:name, :inventory_count)
+
+# Ask Claude: "What are our best-selling products this month?"
+Product.joins(:order_items)
+       .where(order_items: { created_at: 1.month.ago.. })
+       .group(:name)
+       .order('COUNT(*) DESC')
+       .limit(10)
+       .count
+```
+
+#### Customer Support
+```ruby
+# Ask Claude: "Find recent orders for customer email@example.com"
+User.find_by(email: 'email@example.com')
+    &.orders
+    &.recent
+    &.includes(:products)
+    &.map { |o| { id: o.id, total: o.total_amount, products: o.products.pluck(:name) } }
+
+# Ask Claude: "Check the User model structure"
+# Uses model_info tool to show schema, associations, validations
+```
+
+## SaaS Application Example
+
+### Multi-tenant Setup
+```ruby
+# app/models/account.rb
+class Account < ApplicationRecord
+  has_many :users, dependent: :destroy
+  has_many :projects, dependent: :destroy
+  
+  validates :name, presence: true
+  validates :plan, inclusion: { in: %w[free pro enterprise] }
+end
+
+# app/models/project.rb
+class Project < ApplicationRecord
+  belongs_to :account
+  belongs_to :user, -> { where(role: 'owner') }
+  has_many :tasks, dependent: :destroy
+  
+  validates :name, presence: true
+  scope :active, -> { where(archived: false) }
+end
+```
+
+### SaaS-specific Configuration
+```ruby
+# config/initializers/rails_active_mcp.rb
+RailsActiveMcp.configure do |config|
+  config.safe_mode = true
+  config.max_results = 100
+  
+  # Tenant isolation safety
+  config.custom_safety_patterns = [
+    { 
+      pattern: /Account.*delete_all|destroy_all/i, 
+      description: "Account mass operations are forbidden" 
+    },
+    { 
+      pattern: /User.*update_all.*account_id/i, 
+      description: "Cross-tenant user moves are dangerous" 
+    }
+  ]
+  
+  # Production tenant restrictions
+  if Rails.env.production?
+    config.allowed_models = %w[Account User Project Task]
+    config.max_results = 50
+  end
+end
+```
+
+### Claude Queries for SaaS Analytics
+```ruby
+# Ask Claude: "How many active accounts do we have by plan?"
+Account.group(:plan).count
+
+# Ask Claude: "What's our monthly recurring revenue?"
+Account.where(plan: ['pro', 'enterprise'])
+       .sum('CASE 
+             WHEN plan = "pro" THEN 29 
+             WHEN plan = "enterprise" THEN 99 
+             ELSE 0 END')
+
+# Ask Claude: "Which accounts have the most projects?"
+Account.joins(:projects)
+       .group('accounts.name')
+       .order('COUNT(projects.id) DESC')
+       .limit(10)
+       .count
+```
+
+## Content Management System Example
+
+### CMS Model Structure
+```ruby
+# app/models/article.rb
+class Article < ApplicationRecord
+  belongs_to :author, class_name: 'User'
+  belongs_to :category
+  has_many :comments, dependent: :destroy
+  
+  validates :title, presence: true
+  validates :content, presence: true
+  
+  scope :published, -> { where(published: true) }
+  scope :recent, -> { order(created_at: :desc) }
+end
+
+# app/models/category.rb
+class Category < ApplicationRecord
+  has_many :articles
+  validates :name, presence: true, uniqueness: true
+end
+```
+
+### CMS Configuration
+```ruby
+# config/initializers/rails_active_mcp.rb
+RailsActiveMcp.configure do |config|
+  config.safe_mode = true
+  
+  # Content-specific safety patterns
+  config.custom_safety_patterns = [
+    { 
+      pattern: /Article.*delete_all.*published.*true/i, 
+      description: "Mass deletion of published articles is dangerous" 
+    }
+  ]
+  
+  # Environment-specific settings
+  case Rails.env
+  when 'production'
+    config.allowed_models = %w[Article Category User Comment]
+    config.max_results = 25  # Smaller for content queries
+  end
+end
+```
+
+### Claude Queries for Content Analytics
+```ruby
+# Ask Claude: "What are our most popular categories?"
+Category.joins(:articles)
+        .where(articles: { published: true })
+        .group(:name)
+        .order('COUNT(articles.id) DESC')
+        .count
+
+# Ask Claude: "Show me recent article performance"
+Article.published
+       .recent
+       .limit(10)
+       .pluck(:title, :views_count, :created_at)
+
+# Ask Claude: "Find articles that need moderation"
+Article.joins(:comments)
+       .where(comments: { flagged: true })
+       .distinct
+       .pluck(:title, :id)
+```
+
+## Advanced Safety Patterns
+
+### Custom Validators
+```ruby
+# config/initializers/rails_active_mcp.rb
+RailsActiveMcp.configure do |config|
+  # Financial data protection
+  config.custom_safety_patterns += [
+    { pattern: /payment|billing|card|bank/i, description: "Financial data access" },
+    { pattern: /password|token|secret|key/i, description: "Sensitive credential access" },
+    { pattern: /delete.*where.*id.*in/i, description: "Bulk deletion by ID list" }
+  ]
+  
+  # Model-specific restrictions
+  config.allowed_models = case Rails.env
+  when 'production'
+    %w[User Order Product Customer Invoice]  # Whitelist approach
+  else
+    []  # Empty = allow all models
+  end
+end
+```
+
+### Environment-specific Presets
+```ruby
+# config/initializers/rails_active_mcp.rb
+RailsActiveMcp.configure do |config|
+  case Rails.env
+  when 'production'
+    # Ultra-safe production mode
+    config.safe_mode = true
+    config.command_timeout = 10
+    config.max_results = 25
+    config.log_executions = true
+    
+  when 'staging' 
+    # Production-like testing
+    config.safe_mode = true
+    config.command_timeout = 20
+    config.max_results = 50
+    config.log_executions = true
+    
+  when 'development'
+    # Developer-friendly
+    config.safe_mode = false
+    config.command_timeout = 60
+    config.max_results = 200
+    config.log_level = :debug
+    
+  when 'test'
+    # Fast and minimal for tests
+    config.safe_mode = true
+    config.command_timeout = 5
+    config.max_results = 10
+    config.log_executions = false
+  end
+end
+```
+
+## Best Practices
+
+### 1. Always Use Limits
+```ruby
+# ✅ Good - Always include limits
+User.where(active: true).limit(10)
+Order.recent.limit(20)
+
+# ❌ Avoid - Unlimited queries can overwhelm Claude
+User.all
+Order.where(status: 'pending')
+```
+
+### 2. Prefer Aggregations Over Raw Data
+```ruby
+# ✅ Good - Summary data
+User.group(:status).count
+Order.group_by_day(:created_at).sum(:total_amount)
+
+# ❌ Less useful - Raw data dumps
+User.pluck(:email, :status, :created_at)
+```
+
+### 3. Use Meaningful Scopes
+```ruby
+# ✅ Good - Readable business logic
+User.active.recent_signups.count
+Order.completed.this_month.sum(:total_amount)
+
+# ❌ Less clear - Complex inline conditions
+User.where(active: true, created_at: 1.week.ago..).count
+```
+
+### 4. Structure Claude Queries Naturally
+```ruby
+# Ask Claude natural questions:
+# "How many users signed up this week?"
+# "What's our average order value?"
+# "Which products need restocking?"
+# "Show me the User model structure"
+```
+
+## Troubleshooting Common Issues
+
+### Performance Issues
+```ruby
+# Monitor execution times
+rails rails_active_mcp:benchmark
+
+# Check for slow queries
+rails rails_active_mcp:status
+```
+
+### Safety Violations
+```ruby
+# Test code safety before asking Claude
+rails rails_active_mcp:check_safety['User.delete_all']
+
+# View current configuration
+rails rails_active_mcp:validate_config
+```
+
+### Claude Desktop Integration
+```ruby
+# Generate Claude Desktop config
+rails rails_active_mcp:install_claude_config
+
+# Test server connectivity  
+bin/rails-active-mcp-wrapper
+```
+
+This comprehensive integration guide helps Rails developers understand how to effectively use Rails Active MCP in real-world applications, following modern Rails patterns and ensuring secure, efficient AI-powered database interactions. 

data/exe/rails-active-mcp-server

@@ -1,120 +1,197 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'rack'
+# Require essential gems first
 require 'json'
 require 'stringio'
 
-# Suppress ALL output immediately when not in debug mode to prevent MCP JSON protocol interference
+# CRITICAL: Redirect stdout IMMEDIATELY for stdio mode to prevent any output interference
+# This must happen before any other gem loading
 original_stdout = $stdout
 original_stderr = $stderr
 
-# Only suppress if we're likely running in stdio mode (for Claude) and not debugging
-if ARGV.first == 'stdio' && !ENV['RAILS_MCP_DEBUG']
-  # Redirect to temporary StringIO until Rails loading is complete
-  $stdout = StringIO.new
-  $stderr = StringIO.new
+# Determine if we should redirect output (stdio mode or explicit request)
+should_redirect = (ARGV.first == 'stdio' || ARGV.first.nil?) && !ENV['RAILS_MCP_DEBUG']
+
+if should_redirect
+  # Create log directory early
+  log_dir = File.join(Dir.pwd, 'log')
+  Dir.mkdir(log_dir) unless Dir.exist?(log_dir)
+
+  # Redirect stderr to log file immediately, before any loading
+  stderr_log = File.join(log_dir, 'rails_mcp_stderr.log')
+  $stderr.reopen(stderr_log, 'a')
+  $stderr.sync = true
+
+  # Use StringIO to capture any unwanted stdout during loading
+  # We'll filter out non-JSON content later
+  captured_stdout = StringIO.new
+  $stdout = captured_stdout
 end
 
 # Initialize Rails environment if available (from current working directory)
 rails_loaded = false
+rails_load_error = nil
 if File.exist?('config/environment.rb')
   begin
     require './config/environment'
     rails_loaded = true
+
+    # Log successful Rails loading
+    warn "[#{Time.now}] [RAILS-MCP] INFO: Rails environment loaded successfully" if should_redirect
   rescue StandardError => e
     # Rails loading failed, continue without it
-    # Only show warning in debug mode
-    warn "Warning: Failed to load Rails environment: #{e.message}" if ENV['RAILS_MCP_DEBUG']
+    rails_load_error = e
+    # Log to stderr (which is already redirected if needed)
+    warn "[#{Time.now}] [RAILS-MCP] WARNING: Failed to load Rails environment: #{e.message}"
+    warn "[#{Time.now}] [RAILS-MCP] WARNING: #{e.backtrace.first(3).join("\n")}" if ENV['RAILS_MCP_DEBUG']
   end
+elsif should_redirect
+  warn "[#{Time.now}] [RAILS-MCP] INFO: No Rails environment found (config/environment.rb missing)"
 end
 
-# Restore stdout/stderr after Rails loading for non-debug stdio mode
-if ARGV.first == 'stdio' && !ENV['RAILS_MCP_DEBUG']
+# Restore stdout after Rails loading for stdio mode (stderr stays redirected)
+if should_redirect
+  # Check if anything was captured during loading
+  captured_content = captured_stdout.string
+  unless captured_content.empty?
+    # Log any captured content to stderr for debugging
+    warn "[#{Time.now}] [RAILS-MCP] WARNING: Captured stdout during loading: #{captured_content.inspect}"
+    $stderr.flush
+  end
+
+  # Restore original stdout
   $stdout = original_stdout
-  $stderr = original_stderr
 end
 
 # Now load the gem
-require_relative '../lib/rails_active_mcp'
-
-# Parse command line options with config defaults (only after Rails is loaded)
-default_mode = if rails_loaded && defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config)
-                 RailsActiveMcp.config.server_mode.to_s
-               else
-                 'stdio'
-               end
-default_port = if rails_loaded && defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config)
-                 RailsActiveMcp.config.server_port
-               else
-                 3001
-               end
-default_host = if rails_loaded && defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config)
-                 RailsActiveMcp.config.server_host
-               else
-                 'localhost'
-               end
-
-transport = ARGV[0] || default_mode
-port = ARGV.include?('--port') ? ARGV[ARGV.index('--port') + 1].to_i : default_port
-host = ARGV.include?('--host') ? ARGV[ARGV.index('--host') + 1] : default_host
+begin
+  require_relative '../lib/rails_active_mcp'
+rescue LoadError => e
+  warn "[#{Time.now}] [RAILS-MCP] FATAL: Failed to load rails_active_mcp gem: #{e.message}"
+  exit(1)
+end
+
+# Parse command line options
+transport = ARGV[0] || 'stdio'
+port = ARGV.include?('--port') ? ARGV[ARGV.index('--port') + 1].to_i : 3001
+host = ARGV.include?('--host') ? ARGV[ARGV.index('--host') + 1] : 'localhost'
+
+# Determine and set correct working directory
+def find_rails_root(start_dir = Dir.pwd)
+  current_dir = start_dir
+
+  # Look for Gemfile and config/environment.rb up to 5 levels up
+  5.times do
+    gemfile_path = File.join(current_dir, 'Gemfile')
+    config_path = File.join(current_dir, 'config', 'environment.rb')
+
+    return current_dir if File.exist?(gemfile_path) && File.exist?(config_path)
+
+    parent_dir = File.dirname(current_dir)
+    break if parent_dir == current_dir # reached root
+
+    current_dir = parent_dir
+  end
+
+  nil
+end
+
+# Auto-detect Rails root and change directory if needed
+rails_root = find_rails_root
+if rails_root && rails_root != Dir.pwd
+  warn "[#{Time.now}] [RAILS-MCP] INFO: Detected Rails root at #{rails_root}, changing directory" if should_redirect
+  Dir.chdir(rails_root)
+elsif rails_root.nil?
+  # Check if we're in the gem directory and need to find a Rails app
+  if File.basename(Dir.pwd) == 'rails-active-mcp-gem' || Dir.pwd.include?('rails-active-mcp-gem')
+    warn "[#{Time.now}] [RAILS-MCP] ERROR: Running from gem directory, not Rails application directory"
+    warn "[#{Time.now}] [RAILS-MCP] ERROR: Please run the server from your Rails application root directory"
+    warn "[#{Time.now}] [RAILS-MCP] ERROR: Example: cd /path/to/your/rails/app && /path/to/rails-active-mcp-gem/exe/rails-active-mcp-server stdio"
+    exit(1)
+  end
+
+  # Final check for Gemfile in current directory
+  unless File.exist?('Gemfile')
+    warn "[#{Time.now}] [RAILS-MCP] ERROR: Could not locate Gemfile in current directory: #{Dir.pwd}"
+    warn "[#{Time.now}] [RAILS-MCP] ERROR: Please ensure you're running from a Rails application root directory"
+    warn "[#{Time.now}] [RAILS-MCP] ERROR: Current directory contents:"
+    Dir.entries('.').each { |entry| warn "[#{Time.now}] [RAILS-MCP] ERROR:   #{entry}" unless entry.start_with?('.') }
+    exit(1)
+  end
+end
+
+# Log the working directory for debugging
+warn "[#{Time.now}] [RAILS-MCP] INFO: Working directory: #{Dir.pwd}" if should_redirect
+warn "[#{Time.now}] [RAILS-MCP] INFO: Gemfile found: #{File.exist?('Gemfile')}" if should_redirect
 
 case transport
 when 'stdio'
-  # Stdio transport for Claude Desktop
-  require_relative '../lib/rails_active_mcp/stdio_server'
-
+  # Stdio transport for Claude Desktop using MCP SDK
   begin
-    # Final stderr redirection to prevent any remaining output from interfering with MCP JSON protocol
-    # This is critical because Claude Desktop expects ONLY JSON on stdout and ANY non-JSON breaks the protocol
-    unless ENV['RAILS_MCP_DEBUG']
-      # Create log directory if it doesn't exist
-      log_dir = File.join(Dir.pwd, 'log')
-      Dir.mkdir(log_dir) unless Dir.exist?(log_dir)
-
-      # Redirect stderr to log file
-      stderr_log = File.join(log_dir, 'rails_mcp_stderr.log')
-      $stderr.reopen(stderr_log, 'a')
-      $stderr.sync = true
+    require_relative '../lib/rails_active_mcp/sdk/server'
+
+    # Log startup information
+    if should_redirect
+      warn "[#{Time.now}] [RAILS-MCP] INFO: Starting Rails Active MCP Server v#{RailsActiveMcp::VERSION}"
+    end
+    warn "[#{Time.now}] [RAILS-MCP] INFO: Rails loaded: #{rails_loaded}" if should_redirect
+    if rails_load_error && should_redirect
+      warn "[#{Time.now}] [RAILS-MCP] WARNING: Rails load error: #{rails_load_error.class.name}: #{rails_load_error.message}"
     end
 
-    stdio_server = RailsActiveMcp::StdioServer.new
-    stdio_server.start
+    server = RailsActiveMcp::Sdk::Server.new
+    server.run_stdio
   rescue Interrupt
+    warn "[#{Time.now}] [RAILS-MCP] INFO: Server interrupted by user" if should_redirect
     exit(0)
+  rescue LoadError => e
+    warn "[#{Time.now}] [RAILS-MCP] FATAL: MCP SDK not available: #{e.message}"
+    warn "[#{Time.now}] [RAILS-MCP] FATAL: Please install the MCP gem: gem install mcp"
+    exit(1)
+  rescue StandardError => e
+    warn "[#{Time.now}] [RAILS-MCP] FATAL: Server startup failed: #{e.message}"
+    warn "[#{Time.now}] [RAILS-MCP] FATAL: #{e.backtrace.join("\n")}" if ENV['RAILS_MCP_DEBUG']
+    exit(1)
   end
 
 when 'http'
-  # HTTP transport for other integrations
-  puts 'Warning: Rails environment not loaded. Some features may not work properly.' unless rails_loaded
-
-  puts "Starting Rails Active MCP Server on #{host}:#{port}"
-  puts 'Press Ctrl+C to stop'
+  puts 'Error: HTTP transport is no longer supported in v2.0.0'
+  puts 'Please use stdio mode for MCP integration: rails-active-mcp-server stdio'
+  puts ''
+  puts 'For more information, see the migration guide in the documentation.'
+  exit(1)
 
-  begin
-    require 'webrick'
-    require 'rack/handler/webrick'
-
-    Rack::Handler::WEBrick.run(
-      RailsActiveMcp::McpServer.new,
-      Port: port,
-      Host: host,
-      Logger: WEBrick::Log.new(nil, WEBrick::BasicLog::WARN)
-    )
-  rescue LoadError => e
-    puts 'Error: WEBrick not available. Please install: gem install webrick'
-    puts 'Or use stdio mode for Claude Desktop: rails-active-mcp-server stdio'
-    exit(1)
-  rescue Interrupt
-    puts "\nShutting down server..."
-  end
+when '--help', '-h'
+  puts 'Rails Active MCP Server'
+  puts "Version: #{RailsActiveMcp::VERSION}"
+  puts ''
+  puts 'Usage: rails-active-mcp-server [stdio] [options]'
+  puts '  stdio: For MCP integration (default)'
+  puts ''
+  puts 'Options:'
+  puts '  --help, -h Show this help message'
+  puts ''
+  puts 'Environment variables:'
+  puts '  RAILS_MCP_DEBUG=1  Enable debug logging and disable output redirection'
+  puts ''
+  puts 'Examples:'
+  puts '  rails-active-mcp-server stdio                # Start in stdio mode'
+  puts '  RAILS_MCP_DEBUG=1 rails-active-mcp-server   # Start with debug logging'
+  puts ''
+  puts 'Note: HTTP transport was removed in v2.0.0. Use stdio mode for MCP integration.'
+  exit(0)
 
 else
-  puts 'Usage: rails-active-mcp-server [stdio|http] [--port PORT] [--host HOST]'
-  puts '  stdio: For Claude Desktop integration'
-  puts '  http:  For HTTP-based integrations'
+  puts 'Usage: rails-active-mcp-server [stdio] [options]'
+  puts '  stdio: For MCP integration (default)'
+  puts ''
+  puts 'Options:'
+  puts '  --help, -h Show this help message'
   puts ''
   puts 'Environment variables:'
-  puts '  RAILS_MCP_DEBUG=1  Enable debug logging'
+  puts '  RAILS_MCP_DEBUG=1  Enable debug logging and disable output redirection'
+  puts ''
+  puts 'Note: HTTP transport was removed in v2.0.0. Use stdio mode for MCP integration.'
   exit(1)
 end