rails-active-mcp 0.1.7 → 2.0.8

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/install_generator.rb

@@ -20,30 +20,24 @@ module RailsActiveMcp
           # This ensures the server runs within the Rails project context
 
           require 'bundler/setup'
-          require 'stringio'
 
           # Set Rails environment
           ENV['RAILS_ENV'] ||= 'development'
 
-          # Suppress Rails loading output for MCP JSON protocol
-          unless ENV['RAILS_MCP_DEBUG'] == '1'
-            original_stdout = $stdout
-            original_stderr = $stderr
-            $stdout = StringIO.new
-            $stderr = StringIO.new
-          end
-
-          # Load Rails application
+          # Load Rails application first
           require_relative '../config/environment'
 
-          # Restore output streams
-          unless ENV['RAILS_MCP_DEBUG'] == '1'
-            $stdout = original_stdout
-            $stderr = original_stderr
-          end
+          # Now start the MCP server using the SDK implementation
+          require 'rails_active_mcp/sdk/server'
 
-          # Now run the actual MCP server
-          load Gem.bin_path('rails_active_mcp', 'rails-active-mcp-server')
+          begin
+            server = RailsActiveMcp::SDK::Server.new
+            server.run
+          rescue StandardError => e
+            warn "Error starting Rails Active MCP server: \#{e.message}"
+            warn e.backtrace if ENV['RAILS_MCP_DEBUG'] == '1'
+            exit 1
+          end
         RUBY
 
         chmod 'bin/rails-active-mcp-server', 0o755
@@ -57,7 +51,6 @@ module RailsActiveMcp
 
           # Rails Active MCP Wrapper Script
           # Ensures correct Ruby environment for Claude Desktop execution
-          # Research-based solution for version manager compatibility
 
           # Fix Claude Desktop environment isolation issues
           export HOME="${HOME:-#{ENV['HOME']}}"
@@ -95,24 +88,6 @@ module RailsActiveMcp
         say 'Created environment wrapper at bin/rails-active-mcp-wrapper', :green
       end
 
-      def create_mcp_route
-        # Check if routes file exists and is writable
-        routes_file = 'config/routes.rb'
-        return unless File.exist?(routes_file)
-
-        # Read current routes to check for conflicts
-        routes_content = File.read(routes_file)
-
-        if routes_content.include?('/mcp')
-          say "Warning: Route '/mcp' already exists. Skipping route creation.", :yellow
-          say "Manual setup: Add 'mount RailsActiveMcp::Engine, at: \"/mcp\"' to your routes.rb", :yellow
-        else
-          # Use Engine mounting instead of direct server mounting
-          route "mount RailsActiveMcp::Engine, at: '/mcp'"
-          say "Added MCP route at '/mcp'. You can change this in config/routes.rb", :green
-        end
-      end
-
       def create_mcp_config
         template 'mcp.ru', 'mcp.ru'
       end
@@ -134,7 +109,6 @@ module RailsActiveMcp
         say '  "mcpServers": {', :cyan
         say '    "rails-active-mcp": {', :cyan
         say "      \"command\": \"#{Rails.root}/bin/rails-active-mcp-wrapper\",", :cyan
-        say '      "args": ["stdio"],', :cyan
         say "      \"cwd\": \"#{Rails.root}\",", :cyan
         say '      "env": {', :cyan
         say '        "RAILS_ENV": "development",', :cyan
@@ -144,6 +118,12 @@ module RailsActiveMcp
         say '  }', :cyan
         say '}', :cyan
         say '', :green
+        say "\nAvailable Tools in Claude Desktop:", :green
+        say '- console_execute: Execute Ruby code with safety checks', :yellow
+        say '- model_info: Get detailed information about Rails models', :yellow
+        say '- safe_query: Execute safe read-only database queries', :yellow
+        say '- dry_run: Analyze Ruby code for safety without execution', :yellow
+        say '', :green
         say "\nWhy use the wrapper?", :green
         say '- Handles Ruby version manager environments (asdf, rbenv, etc.)', :yellow
         say '- Prevents "bundler version" and "Ruby version" conflicts', :yellow
@@ -151,8 +131,8 @@ module RailsActiveMcp
         say "\nAlternative (if wrapper doesn't work):", :green
         say 'Use bin/rails-active-mcp-server instead of the wrapper', :yellow
         say "\nTesting:", :green
-        say '1. Test manually: bin/rails-active-mcp-wrapper stdio', :yellow
-        say '2. Should output JSON (not plain text)', :yellow
+        say '1. Test manually: bin/rails-active-mcp-wrapper', :yellow
+        say '2. Should output JSON responses (not plain text)', :yellow
         say '3. Restart Claude Desktop after config changes', :yellow
         say "\nTroubleshooting:", :green
         say '- Set RAILS_MCP_DEBUG=1 for verbose logging', :yellow

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

@@ -1,188 +1,134 @@
-================================================================================
-Rails Active MCP has been installed!
-================================================================================
-
-Configuration:
-- Initializer created at: config/initializers/rails_active_mcp.rb
-- Custom MCP server mounted at: /mcp
-- MCP server configuration: mcp.ru
-- Audit log will be created at: log/rails_active_mcp.log
-
-Next Steps:
-
-1. Review and customize the configuration in config/initializers/rails_active_mcp.rb
-
-2. Configure server mode in config/initializers/rails_active_mcp.rb:
-   config.server_mode = :stdio    # For Claude Desktop (default)
-   config.server_mode = :http     # For HTTP-based integrations
-   config.server_host = 'localhost'
-   config.server_port = 3001
-
-3. Start the MCP server:
-   Option A: Use configured mode (RECOMMENDED)
-   $ bundle exec rails-active-mcp-server
-
-   Option B: Override mode via command line
-   $ bundle exec rails-active-mcp-server stdio  # Force stdio mode
-   $ bundle exec rails-active-mcp-server http   # Force HTTP mode
-
-   Option C: Rails-mounted server (HTTP)
-   $ rails server
-
-   Option D: Using rackup
-   $ rackup mcp.ru -p 3001
-
-4. For Claude Desktop integration, add this to your Claude Desktop configuration:
-
-   Location: ~/.config/claude-desktop/claude_desktop_config.json (Linux/macOS)
-   Location: %APPDATA%\Claude\claude_desktop_config.json (Windows)
-
-   {
-     "mcpServers": {
-       "rails-active-mcp": {
-         "command": "<%= Rails.root %>/bin/rails-active-mcp-wrapper",
-         "args": ["stdio"],
-         "cwd": "<%= Rails.root %>", 
-         "env": {
-           "RAILS_ENV": "development",
-           "HOME": "/Users/your-username"
-         }
-       }
-     }
-   }
-
-   OR if you've installed the gem globally:
-
-   {
-     "mcpServers": {
-       "rails-active-mcp": {
-         "command": "rails-active-mcp-server",
-         "args": ["stdio"],
-         "cwd": "/path/to/your/rails/project"
-       }
-     }
-   }
-
-5. For other MCP clients (HTTP-based), add this to your MCP configuration:
-   {
-     "mcpServers": {
-       "rails-console": {
-         "command": "curl",
-         "args": ["-X", "POST", "-H", "Content-Type: application/json", "-d", "@-", "http://localhost:3000/mcp"]
-       }
-     }
-   }
-
-6. Test the installation:
-   $ rails console
-   > RailsActiveMcp.safe?("User.count")
-   > RailsActiveMcp.execute("User.count")
-
-Built-in Tools Available in Claude:
-- rails_console_execute: Execute Ruby code in Rails console with safety checks
-- rails_model_info: Get detailed information about Rails models
-- rails_safe_query: Execute safe read-only database queries
-- rails_dry_run: Analyze Ruby code for safety without execution
-
-Extend with custom tools by modifying the MCP server implementation.
-
-Security Notes:
-- Production mode enables strict safety by default
-- All executions are logged to the audit file
-- Dangerous operations are blocked in safe mode
-- Review the safety patterns in the configuration
-
-Transport Modes:
-- stdio: For Claude Desktop and compatible MCP clients (recommended)
-- http: For HTTP-based integrations and web applications
-
-Configuration Examples:
-
-For Claude Desktop (default):
-  config.server_mode = :stdio
-
-For HTTP web integrations:
-  config.server_mode = :http
-  config.server_host = 'localhost'
-  config.server_port = 3001
-
-For Docker/remote access:
-  config.http_mode!(host: '0.0.0.0', port: 8080)
-
-For development with multiple transport modes:
-  if Rails.env.development?
-    config.stdio_mode!  # Claude Desktop
-  else
-    config.http_mode!(host: '0.0.0.0', port: 3001)  # Production HTTP
-  end
-
-Custom MCP Server Benefits:
-- No external dependencies
-- Full control over implementation
-- Simplified deployment
-- Enhanced security
-- Works with Claude Desktop
-
-Debugging and Troubleshooting:
-
-For interactive debugging, use the MCP Inspector:
-$ bin/debug-mcp-server --mode inspector
-
-This will:
-- Launch the MCP Inspector connected to your server
-- Allow interactive testing of all tools
-- Show real-time debug output and logs
-
-Debug logging:
-$ RAILS_MCP_DEBUG=1 bundle exec rails-active-mcp-server stdio
-
-View Claude Desktop logs:
-$ tail -f ~/Library/Logs/Claude/mcp*.log  # macOS
-$ tail -f ~/.config/claude-desktop/logs/*.log  # Linux
-
-Common issues:
-
-1. Ruby Version Manager Conflicts (Most Common Issue):
-   If you see errors like "Could not find 'bundler' (X.X.X)" or "Your Ruby version is X.X.X, but your Gemfile specified Y.Y.Y":
-   
-   This happens because Claude Desktop uses system Ruby instead of your project's Ruby version.
-   
-   Solution A - Use the wrapper script (Recommended):
-   In claude_desktop_config.json, use:
-   "command": "<%= Rails.root %>/bin/rails-active-mcp-wrapper"
-   
-   Solution B - Create system symlink:
-   $ sudo ln -sf $(which ruby) /usr/local/bin/ruby
-   
-   Solution C - Use absolute Ruby path:
-   In claude_desktop_config.json, change "command" to your full Ruby path:
-   "command": "$(which ruby)"
-   "args": ["<%= Rails.root %>/bin/rails-active-mcp-server", "stdio"]
-
-2. Environment Variable Issues:
-   If you see "error loading config: $HOME is not defined":
-   
-   This happens because Claude Desktop doesn't inherit all environment variables.
-   
-   Solution: Add HOME to your env section in claude_desktop_config.json:
-   "env": {
-     "RAILS_ENV": "development",
-     "HOME": "/Users/your-username"
-   }
-
-3. General Environment Issues:
-   - Ensure your Rails environment loads properly in the project directory
-   - Check that the gem is properly installed and configured  
-   - Verify the Rails application starts without errors
-   - Make sure the cwd path in Claude Desktop config is correct
-
-4. Debug Steps:
-   - Test manually: $ ./bin/rails-active-mcp-wrapper stdio
-   - Should output JSON (not plain text)
-   - Enable debug logging with RAILS_MCP_DEBUG=1 for detailed output
-   - Check Claude logs: $ tail -f ~/Library/Logs/Claude/mcp*.log
-   - Test environment variables: $ echo $HOME (should show your home directory)
-
-For more information: 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

@@ -1,43 +1,80 @@
 require 'rails_active_mcp'
 
 RailsActiveMcp.configure do |config|
-  # Enable/disable the MCP server
-  config.enabled = true
+  # Core configuration options
+  config.allowed_commands = %w[
+    ls pwd cat head tail grep find wc
+    rails console rails runner
+    bundle exec rspec bundle exec test
+    git status git log git diff
+  ]
 
-  # Safety configuration
-  config.safe_mode = Rails.env.production? # Always safe in production
-  config.default_timeout = 30 # seconds
-  config.max_results = 100
+  # Execution timeout in seconds
+  config.command_timeout = 30
 
-  # Model access control
-  # config.allowed_models = %w[User Post Comment]  # Empty means all allowed
-  # config.blocked_models = %w[AdminUser Secret]   # Models to never allow access
+  # Logging configuration
+  config.enable_logging = true
+  config.log_level = :info # :debug, :info, :warn, :error
 
-  # Mutation tools (dangerous operations)
-  config.enable_mutation_tools = !Rails.env.production?
+  # 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
 
-  # Logging and auditing
-  config.log_executions = true
-  config.audit_file = Rails.root.join('log', 'rails_active_mcp.log')
+  # 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
 
-  # Server configuration
-  config.server_mode = :stdio # :stdio for Claude Desktop, :http for web integrations
-  config.server_host = 'localhost'
-  config.server_port = 3001
+  # Custom safety patterns for your application
+  # config.custom_safety_patterns = [
+  #   { pattern: /YourDangerousMethod/, description: "Your custom dangerous operation" }
+  # ]
 
-  # Environment-specific settings
+  # Environment-specific adjustments
   case Rails.env
   when 'production'
-    config.production_mode! # Very strict settings
+    # Strict settings for production
+    config.safe_mode = true
+    config.log_level = :warn
+    config.command_timeout = 15
+    config.max_results = 50
+    config.log_executions = true
+    config.allowed_models = [] # Consider restricting models in production
+
   when 'development'
-    config.permissive_mode! # More relaxed for 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'
-    config.strict_mode! # Safe for testing
+    # Test-friendly settings
+    config.safe_mode = true
+    config.log_level = :error
+    config.command_timeout = 30
+    config.log_executions = false
   end
-
-  # Add custom safety patterns
-  # config.add_safety_pattern(/CustomDangerousMethod/, "Custom dangerous operation")
-
-  # Operations that require manual confirmation
-  config.require_confirmation_for = %i[delete destroy update_all delete_all]
 end
+
+# Rails Active MCP is now ready!
+#
+# 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. 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
+#
+# Documentation: https://github.com/goodpie/rails-active-mcp
+# Need help? Create an issue or check the troubleshooting guide.

data/lib/generators/rails_active_mcp/install/templates/mcp.ru

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require_relative 'config/environment'
-require 'rails_active_mcp'
+require 'rails_active_mcp/sdk/server'
 
-# Run the Rails Active MCP server
-run RailsActiveMcp::McpServer.new
+# Run the Rails Active MCP server using the official MCP Ruby SDK
+# Note: This file is primarily for reference. The recommended way to run
+# the server is using: bin/rails-active-mcp-server
+
+server = RailsActiveMcp::SDK::Server.new
+server.run