rails-active-mcp 2.0.7 → 2.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dce4c2f44cc53bb550f74c549f92073a367817bf31bc2ae05a6dad17eca0ae29
-  data.tar.gz: 76645f3c0b20e148cf0044afb9dea1c8ed6064ce6e4067b6bf1b5b9cbd5c86d1
+  metadata.gz: c09ba8583ba6900c91cef975c1942d1e5615c27d40c06d4bd58a05e755af0187
+  data.tar.gz: c30c261d6991156ea8f4ab01ab28bd9de1e51443cbd50e1f53b18e0c7cad85f1
 SHA512:
-  metadata.gz: 7d7c5e938697d29db91f0276b008aa2c64307a7ff90b3afcd88c458244ee10b2ae82a4ae8014da06ea5ef99f020ffd8feaf6c66af29741f31a8b37b5300f2f26
-  data.tar.gz: 73950d69c48e192edb0071f3138eea1a148fa9ab557f67fdba8283ce5a3b188e3ee4f9297bdc1381eee74633fe0411e0d5e5affb964e5713ad4796be124b47f9
+  metadata.gz: 50e1b520e0ee3b5ceb79543c451176cf40569759a07660c7609b7c4ba4d2c97cbaacd10281c377a323d96600573f36526c9838a4795b120016d5cccace12e690
+  data.tar.gz: 26ed8f90667ceefd1c83240e2f193c8b53bd5b9fe2b2b077cfb7d880fba58b288e03b0a0fe4ed08a463150712286a44d54016f19a1789e5877bcc837334343d2

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/gemfiles/rails_7.1.gemfile

@@ -0,0 +1,34 @@
+# Rails 7.1 Gemfile for CI testing
+source 'https://rubygems.org'
+
+# Specify the Rails version
+gem 'rails', '~> 7.1.0'
+
+# Include the main gemspec
+gemspec path: '../'
+
+# Rails 7.1 specific dependencies
+gem 'importmap-rails', '>= 1.0'
+gem 'sprockets-rails', '>= 3.4.0'
+gem 'stimulus-rails', '>= 1.0'
+gem 'turbo-rails', '>= 1.0'
+
+# Database adapters
+gem 'mysql2', '~> 0.5'
+gem 'pg', '~> 1.1'
+gem 'sqlite3', '~> 1.6'
+
+# Testing gems
+gem 'factory_bot_rails', '~> 6.0'
+gem 'faker', '~> 3.0'
+gem 'rspec-rails', '~> 6.0'
+
+# Development and debugging
+gem 'debug', '>= 1.0.0'
+gem 'web-console', '>= 4.0'
+
+group :development, :test do
+  gem 'rubocop'
+  gem 'rubocop-rails'
+  gem 'rubocop-rspec'
+end

data/lib/generators/rails_active_mcp/install/templates/README.md

@@ -1,54 +1,134 @@
-================================================================================
-Rails Active MCP Installation Complete!
-================================================================================
-
-🎉 Rails Active MCP v2.0 with Official MCP Ruby SDK has been installed!
-
-📁 Files Created:
-- config/initializers/rails_active_mcp.rb (Configuration)
-- bin/rails-active-mcp-server (Main server executable)
-- bin/rails-active-mcp-wrapper (Environment wrapper for Claude Desktop)
-- mcp.ru (Rack configuration file)
-
-🛠️ Available MCP Tools:
-- console_execute: Execute Ruby code with safety checks
-- model_info: Get detailed information about Rails models  
-- safe_query: Execute safe read-only database queries
-- dry_run: Analyze Ruby code for safety without execution
-
-🚀 Quick Start:
-
-1. Test the server:
-   $ ./bin/rails-active-mcp-server
-
-2. For Claude Desktop, add to claude_desktop_config.json:
-   {
-     "mcpServers": {
-       "rails-active-mcp": {
-         "command": "/path/to/your/project/bin/rails-active-mcp-wrapper",
-         "cwd": "/path/to/your/project",
-         "env": {
-           "RAILS_ENV": "development",
-           "HOME": "/Users/your-username"
-         }
-       }
-     }
-   }
-
-3. Restart Claude Desktop and start using the tools!
-
-⚙️ Configuration:
-Edit config/initializers/rails_active_mcp.rb to customize:
-- allowed_commands: Shell commands that can be executed
-- command_timeout: Execution timeout in seconds
-- enable_logging: Enable/disable logging
-- log_level: Logging verbosity (:debug, :info, :warn, :error)
-
-🔧 Troubleshooting:
-- Use the wrapper script to avoid Ruby version manager conflicts
-- Set RAILS_MCP_DEBUG=1 for verbose logging
-- Ensure Claude Desktop has correct paths and environment variables
-
-📚 Documentation: https://github.com/goodpie/rails-active-mcp
-
-================================================================================
+# Rails Active MCP Integration
+
+This Rails application is configured with Rails Active MCP for secure AI-powered database querying and model inspection.
+
+## What is Rails Active MCP?
+
+Rails Active MCP enables secure Rails console access through Model Context Protocol (MCP) for AI agents and development tools like Claude Desktop. It provides four main tools:
+
+- **console_execute**: Execute Ruby/Rails code with safety checks
+- **model_info**: Inspect Rails models (schema, associations, validations)
+- **safe_query**: Run read-only database queries
+- **dry_run**: Analyze code safety without execution
+
+## Quick Start
+
+### 1. Test the Installation
+
+```bash
+# Test the server starts correctly
+bin/rails-active-mcp-wrapper
+
+# Enable debug mode for troubleshooting
+RAILS_MCP_DEBUG=1 bin/rails-active-mcp-server
+```
+
+### 2. Configure Claude Desktop
+
+Add this to your Claude Desktop configuration:
+
+**macOS/Linux**: `~/.config/claude-desktop/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "rails-active-mcp": {
+      "command": "/path/to/your/rails/app/bin/rails-active-mcp-wrapper",
+      "cwd": "/path/to/your/rails/app",
+      "env": {
+        "RAILS_ENV": "development"
+      }
+    }
+  }
+}
+```
+
+### 3. Try These Commands in Claude Desktop
+
+- "Show me the User model structure"
+- "How many users were created in the last week?"
+- "What are the most recent orders?"
+- "Check if this code is safe: `User.delete_all`"
+
+## Configuration
+
+Your MCP integration is configured in `config/initializers/rails_active_mcp.rb`.
+
+### Environment-Specific Settings
+
+- **Development**: More permissive, verbose logging
+- **Production**: Strict safety, limited results, audit logging
+- **Test**: Minimal logging, safety enabled
+
+### Customizing Safety Rules
+
+```ruby
+# Add custom safety patterns
+config.custom_safety_patterns = [
+  { pattern: /YourDangerousMethod/, description: "Custom dangerous operation" }
+]
+
+# Restrict model access (empty = allow all)
+config.allowed_models = %w[User Post Comment]
+```
+
+## Available Rake Tasks
+
+```bash
+# Check code safety
+rails rails_active_mcp:check_safety['User.count']
+
+# Execute code with safety checks  
+rails rails_active_mcp:execute['User.count']
+
+# Test MCP tools
+rails rails_active_mcp:test_tools
+```
+
+## Troubleshooting
+
+### Server Won't Start
+- Ensure your Rails app starts without errors: `rails console`
+- Check Ruby version compatibility
+- Verify all gems are installed: `bundle install`
+
+### Claude Desktop Connection Issues
+- Restart Claude Desktop after configuration changes
+- Check logs: `~/Library/Logs/Claude/mcp*.log` (macOS)
+- Test server manually: `bin/rails-active-mcp-wrapper`
+
+### Permission Errors
+- Ensure wrapper script is executable: `chmod +x bin/rails-active-mcp-wrapper`
+- Check Ruby path in wrapper script matches your setup
+
+## Security Notes
+
+- All dangerous operations are blocked by default in safe mode
+- Production mode enables the strictest safety settings
+- All executions can be logged for audit purposes
+- Model access can be restricted via configuration
+
+## Examples
+
+### Safe Operations (Always Allowed)
+```ruby
+User.count
+Post.where(published: true).limit(10)
+User.find(1).posts.includes(:comments)
+Rails.env
+```
+
+### Risky Operations (Blocked in Safe Mode)
+```ruby
+User.delete_all        # Mass deletion
+system('rm -rf /')     # System commands
+eval(user_input)       # Code evaluation
+File.delete('file')    # File operations
+```
+
+## Getting Help
+
+- **Documentation**: https://github.com/goodpie/rails-active-mcp
+- **Issues**: https://github.com/goodpie/rails-active-mcp/issues
+- **MCP Protocol**: https://modelcontextprotocol.io

data/lib/generators/rails_active_mcp/install/templates/initializer.rb

@@ -16,15 +16,45 @@ RailsActiveMcp.configure do |config|
   config.enable_logging = true
   config.log_level = :info # :debug, :info, :warn, :error
 
+  # Safety configuration
+  config.safe_mode = true        # Enable safety checks by default
+  config.max_results = 100       # Limit query results to prevent large dumps
+  config.log_executions = true   # Log all executions for audit trail
+
+  # Model access control (empty arrays allow all)
+  config.allowed_models = [] # Whitelist specific models if needed
+  # config.allowed_models = %w[User Post Comment] # Example: restrict to specific models
+
+  # Custom safety patterns for your application
+  # config.custom_safety_patterns = [
+  #   { pattern: /YourDangerousMethod/, description: "Your custom dangerous operation" }
+  # ]
+
   # Environment-specific adjustments
-  if Rails.env.production?
-    # More restrictive settings for production
+  case Rails.env
+  when 'production'
+    # Strict settings for production
+    config.safe_mode = true
     config.log_level = :warn
     config.command_timeout = 15
-  elsif Rails.env.development?
+    config.max_results = 50
+    config.log_executions = true
+    config.allowed_models = [] # Consider restricting models in production
+
+  when 'development'
     # More permissive settings for development
+    config.safe_mode = false # Allow more operations during development
     config.log_level = :debug
     config.command_timeout = 60
+    config.max_results = 200
+    config.log_executions = false
+
+  when 'test'
+    # Test-friendly settings
+    config.safe_mode = true
+    config.log_level = :error
+    config.command_timeout = 30
+    config.log_executions = false
   end
 end
 
@@ -36,7 +66,15 @@ end
 # - safe_query: Execute safe read-only database queries
 # - dry_run: Analyze Ruby code for safety without execution
 #
-# To start the server:
-#   bin/rails-active-mcp-server
+# Quick Start:
+# 1. Start the server: bin/rails-active-mcp-server
+# 2. Configure Claude Desktop (see post-install instructions)
+# 3. Try asking Claude: "Show me all users created in the last week"
+#
+# Testing the installation:
+# - Run: bin/rails-active-mcp-wrapper (should output JSON responses)
+# - Test with: RAILS_MCP_DEBUG=1 bin/rails-active-mcp-server
+# - Check rake tasks: rails -T rails_active_mcp
 #
-# For Claude Desktop integration, see the post-install instructions.
+# Documentation: https://github.com/goodpie/rails-active-mcp
+# Need help? Create an issue or check the troubleshooting guide.

data/lib/rails_active_mcp/tasks.rake

@@ -1,5 +1,5 @@
 namespace :rails_active_mcp do
-  desc "Check the safety of Ruby code"
+  desc 'Check the safety of Ruby code'
   task :check_safety, [:code] => :environment do |task, args|
     code = args[:code]
 
@@ -24,7 +24,7 @@ namespace :rails_active_mcp do
     end
   end
 
-  desc "Execute Ruby code with safety checks"
+  desc 'Execute Ruby code with safety checks'
   task :execute, [:code] => :environment do |task, args|
     code = args[:code]
 
@@ -44,111 +44,267 @@ namespace :rails_active_mcp do
         puts "Error: #{result[:error]}"
         puts "Error class: #{result[:error_class]}" if result[:error_class]
       end
-    rescue => e
+    rescue StandardError => e
       puts "Failed to execute: #{e.message}"
       exit 1
     end
   end
 
-  desc "Test MCP tools"
-  task :test_tools => :environment do
-    puts "Testing Rails Active MCP tools..."
+  desc 'Test MCP tools'
+  task test_tools: :environment do
+    puts 'Testing Rails Active MCP tools...'
 
-    # Test SafeQueryTool
-    puts "\n1. Testing SafeQueryTool..."
-    if defined?(User)
-      tool = RailsActiveMcp::Tools::SafeQueryTool.new
-      result = tool.call(model: "User", method: "count")
-      puts "  User.count: #{result[:success] ? result[:result] : result[:error]}"
+    # Test console execution
+    puts "\n1. Testing console_execute tool:"
+    result = RailsActiveMcp.execute('1 + 1')
+    puts "  Simple math: #{result[:success] ? 'PASS' : 'FAIL'}"
+
+    # Test safety checking
+    puts "\n2. Testing safety checking:"
+    safe_result = RailsActiveMcp.safe?('User.count')
+    dangerous_result = RailsActiveMcp.safe?('User.delete_all')
+    puts "  Safe code detection: #{safe_result ? 'PASS' : 'FAIL'}"
+    puts "  Dangerous code detection: #{!dangerous_result ? 'PASS' : 'FAIL'}"
+
+    # Test Rails integration
+    puts "\n3. Testing Rails integration:"
+    if defined?(Rails) && Rails.respond_to?(:env)
+      puts "  Rails environment: #{Rails.env} - PASS"
     else
-      puts "  Skipped (User model not found)"
+      puts '  Rails environment: NOT DETECTED - FAIL'
     end
 
-    # Test ConsoleExecuteTool
-    puts "\n2. Testing ConsoleExecuteTool..."
-    tool = RailsActiveMcp::Tools::ConsoleExecuteTool.new
-    result = tool.call(code: "1 + 1")
-    puts "  1 + 1: #{result[:success] ? result[:return_value] : result[:error]}"
+    puts "\nAll tests completed!"
+  end
 
-    # Test DryRunTool
-    puts "\n3. Testing DryRunTool..."
-    tool = RailsActiveMcp::Tools::DryRunTool.new
-    result = tool.call(code: "User.delete_all")
-    puts "  User.delete_all analysis: #{result[:estimated_risk]} risk"
+  desc 'Benchmark MCP tools performance'
+  task benchmark: :environment do
+    require 'benchmark'
 
-    puts "\nAll tools tested!"
-  end
+    puts 'Rails Active MCP Performance Benchmark'
+    puts '=' * 50
 
-  desc "Show configuration"
-  task :config => :environment do
-    config = RailsActiveMcp.config
+    # Benchmark safety checking
+    puts "\nSafety Checker Performance:"
+    Benchmark.bm(20) do |x|
+      x.report('Simple check:') do
+        1000.times { RailsActiveMcp.safe?('User.count') }
+      end
 
-    puts "Rails Active MCP Configuration:"
-    puts "  Enabled: #{config.enabled}"
-    puts "  Safe mode: #{config.safe_mode}"
-    puts "  Default timeout: #{config.default_timeout}s"
-    puts "  Max results: #{config.max_results}"
-    puts "  Log executions: #{config.log_executions}"
-    puts "  Audit file: #{config.audit_file}"
-    puts "  Enable mutation tools: #{config.enable_mutation_tools}"
-    puts "  Execution environment: #{config.execution_environment}"
+      x.report('Complex check:') do
+        100.times { RailsActiveMcp.safe?('User.where(active: true).includes(:posts).limit(10)') }
+      end
 
-    if config.allowed_models.any?
-      puts "  Allowed models: #{config.allowed_models.join(', ')}"
+      x.report('Dangerous check:') do
+        1000.times { RailsActiveMcp.safe?('User.delete_all') }
+      end
     end
 
-    if config.blocked_models.any?
-      puts "  Blocked models: #{config.blocked_models.join(', ')}"
-    end
+    # Benchmark code execution
+    puts "\nCode Execution Performance:"
+    Benchmark.bm(20) do |x|
+      x.report('Simple math:') do
+        100.times { RailsActiveMcp.execute('1 + 1') }
+      end
 
-    if config.custom_safety_patterns.any?
-      puts "  Custom safety patterns: #{config.custom_safety_patterns.size}"
+      x.report('String operations:') do
+        100.times { RailsActiveMcp.execute('"hello".upcase') }
+      end
     end
   end
 
-  desc "View audit log"
-  task :audit_log, [:lines] => :environment do |task, args|
-    lines = args[:lines]&.to_i || 10
-    audit_file = RailsActiveMcp.config.audit_file
+  desc 'Validate Rails Active MCP configuration'
+  task validate_config: :environment do
+    puts 'Validating Rails Active MCP configuration...'
+
+    config = RailsActiveMcp.config
+
+    if config.valid?
+      puts '✅ Configuration is valid'
 
-    unless File.exist?(audit_file)
-      puts "Audit log not found at: #{audit_file}"
+      puts "\nCurrent Settings:"
+      puts "  Safe mode: #{config.safe_mode}"
+      puts "  Command timeout: #{config.command_timeout}s"
+      puts "  Max results: #{config.max_results}"
+      puts "  Log executions: #{config.log_executions}"
+      puts "  Log level: #{config.log_level}"
+      puts "  Allowed models: #{config.allowed_models.any? ? config.allowed_models.join(', ') : 'All models allowed'}"
+      puts "  Custom safety patterns: #{config.custom_safety_patterns.length} patterns"
+    else
+      puts '❌ Configuration is invalid'
+      puts 'Please check your config/initializers/rails_active_mcp.rb file'
       exit 1
     end
+  end
+
+  desc 'Generate example usage documentation'
+  task generate_examples: :environment do
+    examples_file = Rails.root.join('doc', 'rails_active_mcp_examples.md')
+    FileUtils.mkdir_p(File.dirname(examples_file))
+
+    content = <<~MARKDOWN
+      # Rails Active MCP Usage Examples
+
+      Generated on #{Date.current}
+
+      ## Safe Operations
+
+      These operations are considered safe and can be executed in safe mode:
+
+      ```ruby
+      # Basic model queries
+      User.count
+      User.all.limit(10)
+      User.where(active: true)
+      User.find(1)
+
+      # Associations
+      User.includes(:posts).limit(5)
+      Post.joins(:user).where(users: { active: true })
+
+      # Aggregations
+      Order.sum(:total_amount)
+      User.group(:status).count
+
+      # System information
+      Rails.env
+      Rails.version
+      Time.current
+      ```
+
+      ## Dangerous Operations (Blocked in Safe Mode)
+
+      These operations are blocked when safe_mode is enabled:
 
-    puts "Last #{lines} entries from audit log:"
-    puts "=" * 50
-
-    File.readlines(audit_file).last(lines).each do |line|
-      begin
-        entry = JSON.parse(line)
-        timestamp = entry['timestamp']
-        code = entry['code']
-        user = entry.dig('user', 'email') || entry.dig('user', 'environment') || 'unknown'
-
-        puts "#{timestamp} [#{user}]: #{code}"
-
-        if entry['type'] == 'error'
-          puts "  ERROR: #{entry['error']}"
-        elsif entry['safety_check'] && !entry['safety_check']['safe']
-          puts "  SAFETY: #{entry['safety_check']['summary']}"
-        end
-        puts
-      rescue JSON::ParserError
-        puts "Invalid JSON entry: #{line}"
+      ```ruby
+      # Mass deletions
+      User.delete_all
+      User.destroy_all
+
+      # System commands
+      system('rm -rf /')
+      `ls -la`
+
+      # File operations
+      File.delete('important_file.txt')
+      FileUtils.rm_rf('/important/directory')
+
+      # Code evaluation
+      eval(user_input)
+      send(dynamic_method)
+      ```
+
+      ## Claude Desktop Usage Examples
+
+      Ask Claude these questions to interact with your Rails app:
+
+      - "How many users do we have?"
+      - "Show me the User model structure"
+      - "What are the most recent orders?"
+      - "Check if this code is safe: User.where(active: false).delete_all"
+      - "Find users created in the last week"
+      - "What associations does the Post model have?"
+
+      ## Configuration Examples
+
+      ### Development Configuration
+      ```ruby
+      RailsActiveMcp.configure do |config|
+        config.safe_mode = false
+        config.log_level = :debug
+        config.command_timeout = 60
+        config.max_results = 200
       end
-    end
+      ```
+
+      ### Production Configuration
+      ```ruby
+      RailsActiveMcp.configure do |config|
+        config.safe_mode = true
+        config.log_level = :warn
+        config.command_timeout = 15
+        config.max_results = 50
+        config.allowed_models = %w[User Post Comment]
+      end
+      ```
+    MARKDOWN
+
+    File.write(examples_file, content)
+    puts "Examples generated at: #{examples_file}"
   end
 
-  desc "Clear audit log"
-  task :clear_audit_log => :environment do
-    audit_file = RailsActiveMcp.config.audit_file
+  desc 'Install Claude Desktop configuration'
+  task install_claude_config: :environment do
+    config_template = {
+      mcpServers: {
+        'rails-active-mcp' => {
+          command: Rails.root.join('bin', 'rails-active-mcp-wrapper').to_s,
+          cwd: Rails.root.to_s,
+          env: {
+            RAILS_ENV: Rails.env
+          }
+        }
+      }
+    }
 
-    if File.exist?(audit_file)
-      File.truncate(audit_file, 0)
-      puts "Audit log cleared: #{audit_file}"
-    else
-      puts "Audit log not found: #{audit_file}"
+    puts 'Claude Desktop Configuration:'
+    puts JSON.pretty_generate(config_template)
+    puts ''
+    puts 'Add this to your Claude Desktop configuration file:'
+    puts '  macOS/Linux: ~/.config/claude-desktop/claude_desktop_config.json'
+    puts '  Windows: %APPDATA%\\Claude\\claude_desktop_config.json'
+  end
+
+  desc 'Show comprehensive status and diagnostics'
+  task status: :environment do
+    puts 'Rails Active MCP Status Report'
+    puts '=' * 50
+
+    # Basic environment info
+    puts "\n📋 Environment Information:"
+    puts "  Rails version: #{Rails.version}"
+    puts "  Ruby version: #{RUBY_VERSION}"
+    puts "  Rails environment: #{Rails.env}"
+    puts "  Rails Active MCP version: #{RailsActiveMcp::VERSION}"
+
+    # Configuration status
+    puts "\n⚙️  Configuration Status:"
+    config = RailsActiveMcp.config
+    puts "  Valid: #{config.valid? ? '✅' : '❌'}"
+    puts "  Safe mode: #{config.safe_mode ? '🔒 Enabled' : '⚠️  Disabled'}"
+    puts "  Timeout: #{config.command_timeout}s"
+    puts "  Max results: #{config.max_results}"
+
+    # File status
+    puts "\n📁 File Status:"
+    files_to_check = [
+      'bin/rails-active-mcp-server',
+      'bin/rails-active-mcp-wrapper',
+      'config/initializers/rails_active_mcp.rb'
+    ]
+
+    files_to_check.each do |file|
+      full_path = Rails.root.join(file)
+      if File.exist?(full_path)
+        executable = File.executable?(full_path)
+        puts "  #{file}: ✅ #{executable ? '(executable)' : ''}"
+      else
+        puts "  #{file}: ❌ Missing"
+      end
+    end
+
+    # Test basic functionality
+    puts "\n🧪 Functionality Test:"
+    begin
+      test_result = RailsActiveMcp.execute('1 + 1')
+      puts "  Basic execution: #{test_result[:success] ? '✅' : '❌'}"
+    rescue StandardError => e
+      puts "  Basic execution: ❌ (#{e.message})"
     end
+
+    puts "\n🔗 Integration URLs:"
+    puts '  Documentation: https://github.com/goodpie/rails-active-mcp'
+    puts '  Issues: https://github.com/goodpie/rails-active-mcp/issues'
+    puts '  MCP Protocol: https://modelcontextprotocol.io'
   end
-end
+end

data/lib/rails_active_mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsActiveMcp
-  VERSION = '2.0.7'
+  VERSION = '2.0.8'
 end

data/rails_active_mcp.gemspec

@@ -8,23 +8,51 @@ Gem::Specification.new do |spec|
   spec.authors = ['Brandyn Britton']
   spec.email = ['brandynbb96@gmail.com']
 
-  spec.summary = 'Rails Console access via Model Context Protocol (MCP)'
-  spec.description = 'Secure Rails console access for AI agents through Model Context Protocol with safety features and read-only modes'
+  spec.summary = 'Secure Rails console access via Model Context Protocol (MCP)'
+  spec.description = <<~DESC
+    Rails Active MCP enables secure Rails console access through Model Context Protocol (MCP)#{' '}
+    for AI agents and development tools like Claude Desktop. Provides safe database querying,#{' '}
+    model introspection, and code execution with comprehensive safety checks and audit logging.
+
+    Features include:
+    • Safe Ruby code execution with configurable safety checks
+    • Read-only database query tools with result limiting
+    • Rails model introspection (schema, associations, validations)
+    • Dry-run code analysis for safety validation
+    • Environment-specific configuration presets
+    • Comprehensive audit logging and monitoring
+    • Claude Desktop integration out of the box
+  DESC
+
   spec.homepage = 'https://github.com/goodpie/rails-active-mcp'
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 3.0.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 = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => "#{spec.homepage}/tree/main",
+    'changelog_uri' => "#{spec.homepage}/blob/main/changelog.md",
+    'bug_tracker_uri' => "#{spec.homepage}/issues",
+    'documentation_uri' => "#{spec.homepage}#readme",
+    'wiki_uri' => "#{spec.homepage}/wiki",
+    'mailing_list_uri' => "#{spec.homepage}/discussions",
+    'funding_uri' => 'https://github.com/sponsors/goodpie',
+    'rubygems_mfa_required' => 'true'
+  }
 
-  # Specify which files should be added to the gem when it is released.
+  # Specify which files should be added to the gem when it is released
   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])
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile]) ||
+        f.match?(%r{\A(?:log|tmp|\.)/}) ||
+        f.end_with?('.log', '.tmp')
     end
-  end
+  end + [
+    'examples/rails_app_integration.md',
+    'docs/DEBUGGING.md',
+    'docs/README.md'
+  ].select { |f| File.exist?(f) }
 
   spec.bindir = 'exe'
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
@@ -44,11 +72,31 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'webrick', '~> 1.8'
 
   # Development dependencies - keep versions consistent with Gemfile
+  spec.add_development_dependency 'colorize', '~> 0.8'
   spec.add_development_dependency 'factory_bot_rails', '~> 6.0'
+  spec.add_development_dependency 'faker', '~> 2.19'
   spec.add_development_dependency 'rspec', '~> 3.1'
-  spec.add_development_dependency 'rspec-rails'
+  spec.add_development_dependency 'rspec-rails', '~> 6.0'
   spec.add_development_dependency 'rubocop', '~> 1.77'
   spec.add_development_dependency 'rubocop-rails', '~> 2.32'
-  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'rubocop-rspec', '~> 3.0'
   spec.add_development_dependency 'sqlite3', '~> 2.7'
+
+  # Post-install message to help users get started
+  spec.post_install_message = <<~MSG
+
+    🎉 Thanks for installing Rails Active MCP!
+
+    Quick Start:
+    1. Add to your Rails app: rails generate rails_active_mcp:install
+    2. Test the setup: rails rails_active_mcp:status
+    3. Configure Claude Desktop: rails rails_active_mcp:install_claude_config
+
+    📚 Documentation: #{spec.homepage}#readme
+    🐛 Issues: #{spec.homepage}/issues
+    💬 Discussions: #{spec.homepage}/discussions
+
+    Follow the project: ⭐ #{spec.homepage}
+
+  MSG
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-active-mcp
 version: !ruby/object:Gem::Version
-  version: 2.0.7
+  version: 2.0.8
 platform: ruby
 authors:
 - Brandyn Britton
@@ -119,6 +119,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: factory_bot_rails
   requirement: !ruby/object:Gem::Requirement
@@ -133,6 +147,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.19'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -151,16 +179,16 @@ dependencies:
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -193,16 +221,16 @@ dependencies:
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -217,8 +245,14 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
-description: Secure Rails console access for AI agents through Model Context Protocol
-  with safety features and read-only modes
+description: "Rails Active MCP enables secure Rails console access through Model Context
+  Protocol (MCP) \nfor AI agents and development tools like Claude Desktop. Provides
+  safe database querying, \nmodel introspection, and code execution with comprehensive
+  safety checks and audit logging.\n\nFeatures include:\n• Safe Ruby code execution
+  with configurable safety checks\n• Read-only database query tools with result limiting\n•
+  Rails model introspection (schema, associations, validations)\n• Dry-run code analysis
+  for safety validation\n• Environment-specific configuration presets\n• Comprehensive
+  audit logging and monitoring\n• Claude Desktop integration out of the box\n"
 email:
 - brandynbb96@gmail.com
 executables:
@@ -237,7 +271,9 @@ files:
 - docs/DEBUGGING.md
 - docs/GENERATOR_TESTING.md
 - docs/README.md
+- examples/rails_app_integration.md
 - exe/rails-active-mcp-server
+- gemfiles/rails_7.1.gemfile
 - lib/generators/rails_active_mcp/install/install_generator.rb
 - lib/generators/rails_active_mcp/install/templates/README.md
 - lib/generators/rails_active_mcp/install/templates/initializer.rb
@@ -261,8 +297,20 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/goodpie/rails-active-mcp
-  source_code_uri: https://github.com/goodpie/rails-active-mcp
-  changelog_uri: https://github.com/goodpie/rails-active-mcp/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/goodpie/rails-active-mcp/tree/main
+  changelog_uri: https://github.com/goodpie/rails-active-mcp/blob/main/changelog.md
+  bug_tracker_uri: https://github.com/goodpie/rails-active-mcp/issues
+  documentation_uri: https://github.com/goodpie/rails-active-mcp#readme
+  wiki_uri: https://github.com/goodpie/rails-active-mcp/wiki
+  mailing_list_uri: https://github.com/goodpie/rails-active-mcp/discussions
+  funding_uri: https://github.com/sponsors/goodpie
+  rubygems_mfa_required: 'true'
+post_install_message: "\n\U0001F389 Thanks for installing Rails Active MCP!\n\nQuick
+  Start:\n1. Add to your Rails app: rails generate rails_active_mcp:install\n2. Test
+  the setup: rails rails_active_mcp:status\n3. Configure Claude Desktop: rails rails_active_mcp:install_claude_config\n\n\U0001F4DA
+  Documentation: https://github.com/goodpie/rails-active-mcp#readme\n\U0001F41B Issues:
+  https://github.com/goodpie/rails-active-mcp/issues\n\U0001F4AC Discussions: https://github.com/goodpie/rails-active-mcp/discussions\n\nFollow
+  the project: ⭐ https://github.com/goodpie/rails-active-mcp\n\n"
 rdoc_options: []
 require_paths:
 - lib
@@ -279,5 +327,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: Rails Console access via Model Context Protocol (MCP)
+summary: Secure Rails console access via Model Context Protocol (MCP)
 test_files: []