rails-active-mcp 2.0.7 → 2.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dce4c2f44cc53bb550f74c549f92073a367817bf31bc2ae05a6dad17eca0ae29
-  data.tar.gz: 76645f3c0b20e148cf0044afb9dea1c8ed6064ce6e4067b6bf1b5b9cbd5c86d1
+  metadata.gz: fee611445971a5e113a23146281a9f2a68d0c8c0690213df2704ee7fb80f7700
+  data.tar.gz: ce6ba7ab86616fd0a5a0e60aff50e9c4e8f29101a9866597e1dfd99ef2c6ee85
 SHA512:
-  metadata.gz: 7d7c5e938697d29db91f0276b008aa2c64307a7ff90b3afcd88c458244ee10b2ae82a4ae8014da06ea5ef99f020ffd8feaf6c66af29741f31a8b37b5300f2f26
-  data.tar.gz: 73950d69c48e192edb0071f3138eea1a148fa9ab557f67fdba8283ce5a3b188e3ee4f9297bdc1381eee74633fe0411e0d5e5affb964e5713ad4796be124b47f9
+  metadata.gz: 312b0f2384b4cc7a57b0be9284a52c559897d10e31487eb859cd70b9e5dc385a1005a245cff4a42b7d3abe7f0480b1fdcd8caa317e7ff2388fbeb635ed447c13
+  data.tar.gz: 875467cc1ad75645d32607f2c6c3a98951807da776b626dc113f186720fc6042fe90303fe19ae8c230f036a2a085e6caa1e38e518da0a3ef71356d2cbbce10fd

data/.rubocop.yml

@@ -0,0 +1,141 @@
+plugins:
+  - rubocop-rails
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.1
+  Exclude:
+    - 'bin/bundle'
+    - 'bin/setup'
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'db/schema.rb'
+    - 'log/**/*'
+
+# Documentation is not always necessary for utility classes and tools
+Style/Documentation:
+  Enabled: false
+
+# Allow longer classes for main functionality classes
+Metrics/ClassLength:
+  Max: 400
+  Exclude:
+    - 'bin/*'
+
+# Allow longer methods for setup/configuration methods
+Metrics/MethodLength:
+  Max: 50
+  Exclude:
+    - 'bin/*'
+    - 'lib/generators/**/*'
+
+# Allow higher complexity for main execution methods
+Metrics/AbcSize:
+  Max: 55
+  Exclude:
+    - 'bin/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 15
+
+# Allow longer blocks in specs and configuration
+Metrics/BlockLength:
+  Max: 50
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/rails_active_mcp/tasks.rake'
+    - 'lib/generators/**/*'
+
+# Allow longer lines for error messages and documentation
+Layout/LineLength:
+  Max: 150
+  Exclude:
+    - 'bin/*'
+    - 'exe/*'
+
+# Disable some style checks that are too strict for utility scripts
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+# Allow safe navigation preference but don't enforce it everywhere
+Style/SafeNavigation:
+  Enabled: true
+
+# Allow both single and double quotes
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+# Don't enforce frozen string literals in every file
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Allow numeric comparisons with zero
+Style/NumericPredicate:
+  Enabled: false
+
+# Rails specific configurations
+Rails:
+  Enabled: true
+
+# RSpec specific configurations
+RSpec:
+  Enabled: true
+
+# Gemspec specific configurations
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# Allow some duplication in methods that handle similar cases
+Lint/DuplicateMethods:
+  Enabled: false
+
+Lint/DuplicateBranch:
+  Enabled: false
+
+# RSpec specific overrides for test quality
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/InstanceVariable:
+  Enabled: false
+
+RSpec/BeforeAfterAll:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/MessageChain:
+  Enabled: false
+
+RSpec/ReceiveMessages:
+  Enabled: false
+
+RSpec/ScatteredSetup:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+# Allow Time.zone vs Time.now flexibility
+Rails/TimeZone:
+  Enabled: false
+
+# Naming conventions - allow short parameter names in specs/tools
+Naming/MethodParameterName:
+  Exclude:
+    - 'spec/**/*' 

data/README.md

@@ -24,13 +24,13 @@ gem 'rails-active-mcp'
 And then execute:
 
 ```bash
-$ bundle install
+bundle install
 ```
 
 Run the installer:
 
 ```bash
-$ rails generate rails_active_mcp:install
+rails generate rails_active_mcp:install
 ```
 
 This will:
@@ -298,4 +298,4 @@ The gem is available as open source under the [MIT License](https://opensource.o
 
 ### Previous Versions
 
-See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

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

@@ -4,11 +4,11 @@
 # Require essential gems first
 require 'json'
 require 'stringio'
+require 'fileutils'
 
 # 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
 
 # Determine if we should redirect output (stdio mode or explicit request)
 should_redirect = (ARGV.first == 'stdio' || ARGV.first.nil?) && !ENV['RAILS_MCP_DEBUG']
@@ -16,7 +16,7 @@ should_redirect = (ARGV.first == 'stdio' || ARGV.first.nil?) && !ENV['RAILS_MCP_
 if should_redirect
   # Create log directory early
   log_dir = File.join(Dir.pwd, 'log')
-  Dir.mkdir(log_dir) unless Dir.exist?(log_dir)
+  FileUtils.mkdir_p(log_dir)
 
   # Redirect stderr to log file immediately, before any loading
   stderr_log = File.join(log_dir, 'rails_mcp_stderr.log')
@@ -74,8 +74,8 @@ 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'
+ARGV.include?('--port') ? ARGV[ARGV.index('--port') + 1].to_i : 3001
+ARGV.include?('--host') ? ARGV[ARGV.index('--host') + 1] : 'localhost'
 
 # Determine and set correct working directory
 def find_rails_root(start_dir = Dir.pwd)
@@ -116,7 +116,9 @@ elsif rails_root.nil?
     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?('.') }
+    Dir.entries('.').each do |entry|
+      warn "[#{Time.now}] [RAILS-MCP] ERROR:   #{entry}" unless entry.start_with?('.')
+    end
     exit(1)
   end
 end
@@ -132,9 +134,7 @@ when 'stdio'
     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: Starting Rails Active MCP Server v#{RailsActiveMcp::VERSION}" if should_redirect
     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}"

data/gemfiles/rails_6.0.gemfile

@@ -0,0 +1,34 @@
+# Rails 6.0 Gemfile for CI testing
+source 'https://rubygems.org'
+
+# Specify the Rails version
+gem 'rails', '~> 6.0'
+
+# Include the main gemspec
+gemspec path: '../'
+
+group :development, :test do
+  gem 'byebug'
+  gem 'database_cleaner-active_record', '~> 2.1'
+  gem 'factory_bot_rails', '~> 6.0'
+  gem 'rspec', '~> 3.1'
+  gem 'rspec-rails'
+  gem 'sqlite3', '~> 2.7'
+  gem 'timecop', '~> 0.9.8'
+  gem 'webmock', '~> 3.19'
+end
+
+group :development do
+  gem 'redcarpet' # For YARD markdown support
+  gem 'rubocop', '~> 1.77'
+  gem 'rubocop-rails', '~> 2.32'
+  gem 'rubocop-rspec'
+  gem 'simplecov', '~> 0.22'
+  gem 'yard'
+end
+
+# For testing the gem in a Rails app
+gem 'sprockets-rails' # Required for Rails 7+
+
+# Official MCP Ruby SDK for migration
+gem 'mcp', '~> 0.1.0'

data/gemfiles/rails_6.1.gemfile

@@ -0,0 +1,34 @@
+# Rails 6.0 Gemfile for CI testing
+source 'https://rubygems.org'
+
+# Specify the Rails version
+gem 'rails', '~> 6.0'
+
+# Include the main gemspec
+gemspec path: '../'
+
+group :development, :test do
+  gem 'byebug'
+  gem 'database_cleaner-active_record', '~> 2.1'
+  gem 'factory_bot_rails', '~> 6.0'
+  gem 'rspec', '~> 3.1'
+  gem 'rspec-rails'
+  gem 'sqlite3', '~> 2.7'
+  gem 'timecop', '~> 0.9.8'
+  gem 'webmock', '~> 3.19'
+end
+
+group :development do
+  gem 'redcarpet' # For YARD markdown support
+  gem 'rubocop', '~> 1.77'
+  gem 'rubocop-rails', '~> 2.32'
+  gem 'rubocop-rspec'
+  gem 'simplecov', '~> 0.22'
+  gem 'yard'
+end
+
+# For testing the gem in a Rails app
+gem 'sprockets-rails' # Required for Rails 7+
+
+# Official MCP Ruby SDK for migration
+gem 'mcp', '~> 0.1.0'