rails-active-mcp 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bec983e79b11a278a9f7c39de53d6eff389f4ebbd951e9a613ce313ea3a48ba2
-  data.tar.gz: ed94322b6c2bb06cff349166dbdf4d95babeea80ac6ae2c355683c19c0dc682e
+  metadata.gz: 38778186d51ca223866b9cdf181cbe389957c840609934897547d11af69c150c
+  data.tar.gz: 9ed227e53b104de6e482428a37837b80dd0b30f01405d3abaab8e12c4e6175c8
 SHA512:
-  metadata.gz: 2281c14e99c4f2ad588fe0b222e060cb0b04e9bf0b3b874c284d6f6d6db8757a91d46a1aba7a77f365fe45c518d3a9e9bc58e2e2fbd6738c167334adfd252436
-  data.tar.gz: '0178374d4a7e8c365c582f8cc11ffce5c28d23b3ea8d0d35078cea47eaff5a3d316749ec28b7e724815e293c439b05c989be20187abed0f076d443463da4afbb'
+  metadata.gz: e80bc1548f85c52f88e766a273a7f6a3f4637a398b549a36dd65b756a4243a2d86511354324120938aabdd40c5427abe9be12169890b7745721847f6da2dbfa4
+  data.tar.gz: fd5511135a658f588d154526bbcbe1da8b2d75b7c13d3c73687aba726293555cbd1b3f38defbe8f51ea1ce33fef3c05b38fb82c7e1d8d8f9fb96f6e214d742b2

data/README.md

@@ -1,6 +1,6 @@
 # Rails Active MCP
 
-A Ruby gem that provides secure Rails console access through Model Context Protocol (MCP) for AI agents and development tools like Warp Terminal. Built with a custom MCP server implementation for full control and flexibility.
+A Ruby gem that provides secure Rails console access through Model Context Protocol (MCP) for AI agents and development tools like Claude Desktop, Warp Terminal, and other MCP clients. Built with a custom MCP server implementation for full control and flexibility.
 
 ## Features
 
@@ -51,6 +51,11 @@ RailsActiveMcp.configure do |config|
   config.default_timeout = 30
   config.max_results = 100
 
+  # Server configuration
+  config.server_mode = :stdio # :stdio for Claude Desktop, :http for web
+  config.server_host = 'localhost'
+  config.server_port = 3001
+
   # Model access control
   config.allowed_models = %w[User Post Comment] # Empty = all allowed
   config.blocked_models = %w[AdminUser Secret]
@@ -64,6 +69,10 @@ RailsActiveMcp.configure do |config|
   config.production_mode! # Very strict
   config.strict_mode! # Safe defaults
   config.permissive_mode! # Development friendly
+  
+  # Server mode shortcuts
+  config.stdio_mode! # Set stdio mode for Claude Desktop
+  config.http_mode!(host: '0.0.0.0', port: 8080) # Set HTTP mode with custom host/port
 end
 ```
 
@@ -71,24 +80,37 @@ end
 
 You have several options for running the MCP server:
 
-### Option 1: Rails-mounted (recommended for development)
+### Option 1: Use configured mode (recommended)
+
+```bash
+$ bundle exec rails-active-mcp-server
+```
+
+This will use the server mode configured in your initializer (`:stdio` by default). You can override the mode:
+
+```bash
+$ bundle exec rails-active-mcp-server stdio  # Force stdio mode
+$ bundle exec rails-active-mcp-server http   # Force HTTP mode
+```
+
+### Option 2: Rails-mounted (HTTP, good for development)
 
 ```bash
 $ rails server
 # MCP server available at http://localhost:3000/mcp
 ```
 
-### Option 2: Standalone server
+### Option 3: Standalone HTTP server
 
 ```bash
-$ bundle exec rails-active-mcp-server
+$ bundle exec rails-active-mcp-server http
 # Default: http://localhost:3001
 
 # Custom host/port
-$ bundle exec rails-active-mcp-server --host 0.0.0.0 --port 8080
+$ bundle exec rails-active-mcp-server http --host 0.0.0.0 --port 8080
 ```
 
-### Option 3: Using rackup
+### Option 4: Using rackup
 
 ```bash
 $ rackup mcp.ru -p 3001
@@ -98,7 +120,48 @@ $ rackup mcp.ru -p 3001
 
 ### With MCP Clients
 
-#### Warp Terminal Integration
+#### Claude Desktop Integration (Preferred)
+
+Add to your Claude Desktop configuration file:
+
+**Location:**
+- macOS/Linux: `~/.config/claude-desktop/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "rails-active-mcp": {
+      "command": "bundle",
+      "args": ["exec", "rails-active-mcp-server", "stdio"],
+      "cwd": "/path/to/your/rails/project"
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "rails-active-mcp": {
+      "command": "rails-active-mcp-server",
+      "args": ["stdio"],
+      "cwd": "/path/to/your/rails/project"
+    }
+  }
+}
+```
+
+Then in Claude Desktop, you can use prompts like:
+
+- "Show me all users created in the last week"
+- "What's the average order value?"
+- "Check the User model schema and associations"
+- "Analyze this code for safety: User.delete_all"
+
+#### Warp Terminal Integration (HTTP)
 
 Add to your Warp MCP configuration:
 
@@ -120,16 +183,6 @@ Add to your Warp MCP configuration:
 }
 ```
 
-Then in Warp, you can use prompts like:
-
-- "Show me all users created in the last week"
-- "What's the average order value?"
-- "Check the User model schema and associations"
-
-#### Claude Desktop / Cline
-
-Use the same configuration format as above, pointing to your MCP server.
-
 #### Custom MCP Clients
 
 The server implements the MCP protocol (JSONRPC 2.0). Connect any MCP-compatible client to:
@@ -154,9 +207,11 @@ puts analysis[:estimated_risk] # => :critical
 
 ### Available MCP Tools
 
+The Rails Active MCP server provides several built-in tools that will appear in Claude Desktop:
+
 #### `rails_console_execute`
 
-Execute Ruby code with safety checks:
+Execute Ruby code with safety checks and timeout protection:
 
 ```json
 {
@@ -165,15 +220,65 @@ Execute Ruby code with safety checks:
     "name": "rails_console_execute",
     "arguments": {
       "code": "User.where(active: true).count",
-      "timeout": 30
+      "timeout": 30,
+      "safe_mode": true
+    }
+  }
+}
+```
+
+#### `rails_model_info`
+
+Get detailed information about Rails models:
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "rails_model_info",
+    "arguments": {
+      "model_name": "User"
+    }
+  }
+}
+```
+
+#### `rails_safe_query`
+
+Execute safe, read-only database queries:
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "rails_safe_query",
+    "arguments": {
+      "query": "where(active: true).count",
+      "model": "User"
+    }
+  }
+}
+```
+
+#### `rails_dry_run`
+
+Analyze Ruby code for safety without executing:
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "rails_dry_run",
+    "arguments": {
+      "code": "User.delete_all"
     }
   }
 }
 ```
 
-#### Additional Tools
+#### Adding Custom Tools
 
-The custom server includes built-in support for the main console execute tool. You can extend the server with additional tools by modifying the `McpServer` class in `lib/rails_active_mcp/mcp_server.rb`:
+You can extend the server with additional tools by modifying the `McpServer` class in `lib/rails_active_mcp/mcp_server.rb` or `lib/rails_active_mcp/stdio_server.rb`:
 
 ```ruby
 def register_default_tools

data/docs/DEBUGGING.md

@@ -0,0 +1,313 @@
+# Rails Active MCP Debugging Guide
+
+This guide covers debugging and troubleshooting for the Rails Active MCP server, following the [MCP debugging best practices](https://modelcontextprotocol.io/docs/tools/debugging).
+
+## Quick Debug Commands
+
+```bash
+# Test with MCP Inspector (recommended)
+bin/debug-mcp-server --mode inspector
+
+# Enable debug logging
+RAILS_MCP_DEBUG=1 bundle exec rails-active-mcp-server stdio
+
+# View recent logs
+bin/debug-mcp-server --mode logs
+
+# Basic connectivity test
+bin/debug-mcp-server --mode test
+```
+
+## Debug Tools Overview
+
+### 1. MCP Inspector (Interactive Testing)
+
+The MCP Inspector provides the best debugging experience for MCP servers:
+
+```bash
+# Launch inspector connected to your Rails MCP server
+bin/debug-mcp-server --mode inspector
+
+# Or manually:
+npx @modelcontextprotocol/inspector bundle exec rails-active-mcp-server stdio
+```
+
+The Inspector provides:
+- ✅ Interactive tool testing
+- ✅ Real-time message inspection
+- ✅ Error visualization
+- ✅ Request/response history
+- ✅ Server capability discovery
+
+### 2. Debug Logging
+
+Enable detailed logging with the `RAILS_MCP_DEBUG` environment variable:
+
+```bash
+RAILS_MCP_DEBUG=1 bundle exec rails-active-mcp-server stdio
+```
+
+This enables:
+- Request/response logging to stderr
+- Tool execution timing
+- Detailed error stack traces
+- JSON-RPC message debugging
+
+### 3. Claude Desktop Integration Debugging
+
+#### Checking Server Status in Claude Desktop
+
+1. Click the 🔌 icon to view connected servers
+2. Click the "Search and tools" 🔍 icon to view available tools
+3. Look for these Rails Active MCP tools:
+   - `rails_console_execute`
+   - `rails_model_info`
+   - `rails_safe_query`
+   - `rails_dry_run`
+
+#### Viewing Claude Desktop Logs
+
+```bash
+# macOS
+tail -f ~/Library/Logs/Claude/mcp*.log
+
+# Alternative locations
+ls ~/Library/Logs/Claude/
+```
+
+The logs show:
+- Server connection events
+- Configuration issues
+- Runtime errors
+- Tool execution logs
+
+#### Using Chrome DevTools in Claude Desktop
+
+1. Enable developer tools:
+   ```bash
+   echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
+   ```
+
+2. Open DevTools: `Command-Option-Shift-i`
+
+3. Use Console and Network panels to inspect:
+   - Client-side errors
+   - Message payloads
+   - Connection timing
+
+## Common Issues and Solutions
+
+### 1. Working Directory Issues
+
+**Problem**: Server can't find Rails environment or files.
+
+**Solution**: Always use absolute paths in Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "rails-active-mcp": {
+      "command": "bundle",
+      "args": ["exec", "rails-active-mcp-server", "stdio"],
+      "cwd": "/absolute/path/to/your/rails/project"
+    }
+  }
+}
+```
+
+### 2. Environment Variables
+
+**Problem**: Rails environment or API keys not available.
+
+**Solution**: Specify environment variables in config:
+
+```json
+{
+  "mcpServers": {
+    "rails-active-mcp": {
+      "command": "bundle",
+      "args": ["exec", "rails-active-mcp-server", "stdio"],
+      "cwd": "/path/to/rails/project",
+      "env": {
+        "RAILS_ENV": "development",
+        "RAILS_MCP_DEBUG": "1"
+      }
+    }
+  }
+}
+```
+
+### 3. Server Initialization Problems
+
+**Common initialization issues:**
+
+1. **Path Issues**
+   ```bash
+   # Test the command directly
+   cd /path/to/rails/project
+   bundle exec rails-active-mcp-server stdio
+   ```
+
+2. **Rails Environment Issues**
+   ```bash
+   # Verify Rails loads
+   cd /path/to/rails/project
+   bundle exec rails runner "puts 'Rails loaded successfully'"
+   ```
+
+3. **Permission Problems**
+   ```bash
+   # Check file permissions
+   ls -la exe/rails-active-mcp-server
+   chmod +x exe/rails-active-mcp-server
+   ```
+
+### 4. Connection Problems
+
+**Problem**: Claude Desktop can't connect to server.
+
+**Debug steps:**
+1. Check Claude Desktop logs for errors
+2. Test with MCP Inspector: `bin/debug-mcp-server --mode inspector`
+3. Verify server process starts: `ps aux | grep rails-active-mcp`
+4. Test basic JSON-RPC response:
+   ```bash
+   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | bundle exec rails-active-mcp-server stdio
+   ```
+
+## Logging Implementation
+
+### Server-Side Logging
+
+The Rails Active MCP server implements comprehensive logging:
+
+```ruby
+# Logs to stderr (captured by Claude Desktop)
+@logger = Logger.new(STDERR)
+@logger.level = ENV['RAILS_MCP_DEBUG'] ? Logger::DEBUG : Logger::ERROR
+
+# MCP log notifications (sent to client)
+def send_log_notification(level, message)
+  notification = {
+    jsonrpc: JSONRPC_VERSION,
+    method: 'notifications/message',
+    params: { level: level, data: message }
+  }
+  puts notification.to_json
+  STDOUT.flush
+end
+```
+
+### Log Levels and Events
+
+- **INFO**: Server startup, tool execution start/completion
+- **ERROR**: Parse errors, tool execution failures, unexpected errors
+- **DEBUG**: Request/response details, execution timing (when `RAILS_MCP_DEBUG=1`)
+
+### Important Events Logged
+
+1. **Initialization**: Server startup, tool registration
+2. **Tool Execution**: Start time, completion time, success/failure
+3. **Error Conditions**: Parse errors, execution failures, safety violations
+4. **Performance**: Execution timing, request processing
+
+## Testing Your Implementation
+
+### Basic Connectivity Test
+
+```bash
+# Test initialize method
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | bundle exec rails-active-mcp-server stdio
+```
+
+Expected response:
+```json
+{
+  "jsonrpc":"2.0",
+  "id":1,
+  "result": {
+    "protocolVersion":"2025-06-18",
+    "capabilities":{"tools":{},"resources":{}},
+    "serverInfo":{"name":"rails-active-mcp","version":"..."}
+  }
+}
+```
+
+### Tools List Test
+
+```bash
+# Test tools/list method
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | bundle exec rails-active-mcp-server stdio
+```
+
+Should return all 4 Rails Active MCP tools.
+
+### Tool Execution Test
+
+```bash
+# Test a simple tool call
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"rails_dry_run","arguments":{"code":"puts \"Hello World\""}}}' | bundle exec rails-active-mcp-server stdio
+```
+
+## Best Practices
+
+### Development Workflow
+
+1. **Start with Inspector**: Use `bin/debug-mcp-server --mode inspector` for development
+2. **Enable Debug Logging**: Use `RAILS_MCP_DEBUG=1` during development
+3. **Test Integration**: Test in Claude Desktop with debug logs enabled
+4. **Monitor Performance**: Check execution times and resource usage
+
+### Security Considerations When Debugging
+
+1. **Sanitize Logs**: Never log sensitive data (passwords, API keys)
+2. **Limit Debug Info**: Don't expose internal system details in production
+3. **Protect Credentials**: Use environment variables, not hardcoded values
+
+### Performance Monitoring
+
+- Monitor tool execution times
+- Track memory usage during long operations
+- Log slow queries and operations
+- Monitor connection stability
+
+## Getting Help
+
+When reporting issues:
+
+1. **Provide log excerpts** from both server and Claude Desktop
+2. **Include configuration files** (sanitized)
+3. **List steps to reproduce** the issue
+4. **Specify environment details** (Ruby version, Rails version, OS)
+
+### Support Resources
+
+- [MCP Inspector Documentation](https://modelcontextprotocol.io/docs/tools/inspector)
+- [MCP Debugging Guide](https://modelcontextprotocol.io/docs/tools/debugging)
+- [GitHub Issues](https://github.com/goodpie/rails-active-mcp/issues)
+
+## Advanced Debugging
+
+### Custom Log Analysis
+
+Monitor specific patterns in logs:
+
+```bash
+# Watch for tool executions
+tail -f ~/Library/Logs/Claude/mcp*.log | grep "Executing tool"
+
+# Monitor errors only
+tail -f ~/Library/Logs/Claude/mcp*.log | grep "ERROR"
+
+# Track performance
+tail -f ~/Library/Logs/Claude/mcp*.log | grep "completed in"
+```
+
+### Development Tips
+
+1. **Use Inspector First**: Always test changes with MCP Inspector before Claude Desktop
+2. **Enable All Logging**: Use debug mode to see the full request/response cycle
+3. **Test Edge Cases**: Invalid inputs, timeouts, concurrent requests
+4. **Monitor Resource Usage**: Watch memory and CPU during development
+
+This debugging guide ensures your Rails Active MCP server works reliably with Claude Desktop and other MCP clients. 

data/exe/rails-active-mcp-server

@@ -3,22 +3,67 @@
 
 require 'rack'
 require 'rack/handler/webrick'
+require 'json'
 require_relative '../lib/rails_active_mcp'
 
-# Parse command line options
-port = ARGV.include?('--port') ? ARGV[ARGV.index('--port') + 1].to_i : 3001
-host = ARGV.include?('--host') ? ARGV[ARGV.index('--host') + 1] : 'localhost'
-
-puts "Starting Rails Active MCP Server on #{host}:#{port}"
-puts "Press Ctrl+C to stop"
-
-begin
-  Rack::Handler::WEBrick.run(
-    RailsActiveMcp::McpServer.new,
-    Port: port,
-    Host: host,
-    Logger: WEBrick::Log.new(nil, WEBrick::BasicLog::WARN)
-  )
-rescue Interrupt
-  puts "\nShutting down server..."
-end
+# Load Rails configuration if available
+require_relative '../config/environment' if File.exist?('config/environment.rb')
+
+# Parse command line options with config defaults
+default_mode = if defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config)
+                 RailsActiveMcp.config.server_mode.to_s
+               else
+                 'stdio'
+               end
+default_port = if defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config)
+                 RailsActiveMcp.config.server_port
+               else
+                 3001
+               end
+default_host = if 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
+
+case transport
+when 'stdio'
+  # Stdio transport for Claude Desktop
+  require_relative '../lib/rails_active_mcp/stdio_server'
+
+  begin
+    # Initialize Rails environment if available
+    require_relative '../config/environment' if File.exist?('config/environment.rb')
+
+    stdio_server = RailsActiveMcp::StdioServer.new
+    stdio_server.run
+  rescue Interrupt
+    exit(0)
+  end
+
+when 'http'
+  # HTTP transport for other integrations
+  puts "Starting Rails Active MCP Server on #{host}:#{port}"
+  puts 'Press Ctrl+C to stop'
+
+  begin
+    Rack::Handler::WEBrick.run(
+      RailsActiveMcp::McpServer.new,
+      Port: port,
+      Host: host,
+      Logger: WEBrick::Log.new(nil, WEBrick::BasicLog::WARN)
+    )
+  rescue Interrupt
+    puts "\nShutting down server..."
+  end
+
+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 (default)'
+  exit(1)
+end

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

@@ -1,4 +1,3 @@
-
 ================================================================================
 Rails Active MCP has been installed!
 ================================================================================
@@ -13,17 +12,54 @@ Next Steps:
 
 1. Review and customize the configuration in config/initializers/rails_active_mcp.rb
 
-2. Start the MCP server:
-   Option A: Rails-mounted server
-   $ rails server
+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
 
-   Option B: Standalone server
+3. Start the MCP server:
+   Option A: Use configured mode (RECOMMENDED)
    $ bundle exec rails-active-mcp-server
 
-   Option C: Using rackup
+   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
 
-3. For Warp Terminal integration, add this to your MCP configuration:
+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": "bundle",
+         "args": ["exec", "rails-active-mcp-server", "stdio"],
+         "cwd": "/path/to/your/rails/project"
+       }
+     }
+   }
+
+   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": {
@@ -33,13 +69,16 @@ Next Steps:
      }
    }
 
-4. Test the installation:
+6. Test the installation:
    $ rails console
    > RailsActiveMcp.safe?("User.count")
    > RailsActiveMcp.execute("User.count")
 
-Built-in Tools:
-- rails_console_execute: Execute Ruby code with safety checks
+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.
 
@@ -49,11 +88,60 @@ Security Notes:
 - 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:
+- 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
+- Enable debug logging with RAILS_MCP_DEBUG=1 for detailed output
 
 For more information: https://github.com/goodpie/rails-active-mcp
 

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

@@ -1,6 +1,5 @@
 require 'rails_active_mcp'
 
-
 RailsActiveMcp.configure do |config|
   # Enable/disable the MCP server
   config.enabled = true
@@ -19,7 +18,12 @@ RailsActiveMcp.configure do |config|
 
   # Logging and auditing
   config.log_executions = true
-  config.audit_file = Rails.root.join("log", "rails_active_mcp.log")
+  config.audit_file = Rails.root.join('log', 'rails_active_mcp.log')
+
+  # Server configuration
+  config.server_mode = :stdio # :stdio for Claude Desktop, :http for web integrations
+  config.server_host = 'localhost'
+  config.server_port = 3001
 
   # Environment-specific settings
   case Rails.env
@@ -35,5 +39,5 @@ RailsActiveMcp.configure do |config|
   # config.add_safety_pattern(/CustomDangerousMethod/, "Custom dangerous operation")
 
   # Operations that require manual confirmation
-  config.require_confirmation_for = [:delete, :destroy, :update_all, :delete_all]
+  config.require_confirmation_for = %i[delete destroy update_all delete_all]
 end

data/lib/rails_active_mcp/configuration.rb

@@ -5,7 +5,8 @@ module RailsActiveMcp
     attr_accessor :enabled, :safe_mode, :default_timeout, :max_results,
                   :allowed_models, :blocked_models, :custom_safety_patterns,
                   :log_executions, :audit_file, :enable_mutation_tools,
-                  :require_confirmation_for, :execution_environment
+                  :require_confirmation_for, :execution_environment, :server_mode,
+                  :server_host, :server_port
 
     def initialize
       @enabled = true
@@ -17,10 +18,16 @@ module RailsActiveMcp
       @custom_safety_patterns = []
       @log_executions = true
       # Safe Rails.root access
-      @audit_file = rails_root_join("log", "rails_active_mcp.log") if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+      if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        @audit_file = rails_root_join('log',
+                                      'rails_active_mcp.log')
+      end
       @enable_mutation_tools = false
-      @require_confirmation_for = [:delete, :destroy, :update_all, :delete_all]
+      @require_confirmation_for = %i[delete destroy update_all delete_all]
       @execution_environment = :current # :current, :sandbox, :readonly_replica
+      @server_mode = :stdio # :stdio, :http
+      @server_host = 'localhost'
+      @server_port = 3001
     end
 
     # Safety configuration
@@ -42,7 +49,7 @@ module RailsActiveMcp
       strict_mode!
       @execution_environment = :readonly_replica
       @log_executions = true
-      @require_confirmation_for = [:delete, :destroy, :update, :create, :save]
+      @require_confirmation_for = %i[delete destroy update create save]
     end
 
     # Model access configuration
@@ -58,6 +65,21 @@ module RailsActiveMcp
       @custom_safety_patterns << { pattern: pattern, description: description }
     end
 
+    # Server configuration
+    def stdio_mode!
+      @server_mode = :stdio
+    end
+
+    def http_mode!(host: 'localhost', port: 3001)
+      @server_mode = :http
+      @server_host = host
+      @server_port = port
+    end
+
+    def server_mode_valid?
+      %i[stdio http].include?(@server_mode)
+    end
+
     # Validation
     def model_allowed?(model_name)
       model_str = model_name.to_s
@@ -73,13 +95,15 @@ module RailsActiveMcp
     end
 
     def validate!
-      raise ArgumentError, "timeout must be positive" if @default_timeout <= 0
-      raise ArgumentError, "max_results must be positive" if @max_results <= 0
+      raise ArgumentError, 'timeout must be positive' if @default_timeout <= 0
+      raise ArgumentError, 'max_results must be positive' if @max_results <= 0
+      raise ArgumentError, "invalid server_mode: #{@server_mode}" unless server_mode_valid?
+      raise ArgumentError, 'server_port must be positive' if @server_port <= 0
 
-      if defined?(Rails) && @audit_file
-        audit_dir = File.dirname(@audit_file)
-        FileUtils.mkdir_p(audit_dir) unless File.directory?(audit_dir)
-      end
+      return unless defined?(Rails) && @audit_file
+
+      audit_dir = File.dirname(@audit_file)
+      FileUtils.mkdir_p(audit_dir) unless File.directory?(audit_dir)
     end
 
     private

data/lib/rails_active_mcp/stdio_server.rb

@@ -0,0 +1,467 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'logger'
+
+module RailsActiveMcp
+  class StdioServer
+    JSONRPC_VERSION = '2.0'
+    MCP_VERSION = '2025-06-18'
+
+    def initialize
+      @tools = {}
+      @logger = Logger.new(STDERR) # Log to stderr to avoid interfering with stdout
+      @logger.level = ENV['RAILS_MCP_DEBUG'] ? Logger::DEBUG : Logger::ERROR
+      @logger.formatter = proc do |severity, datetime, progname, msg|
+        "[#{datetime}] [RAILS-MCP] #{severity}: #{msg}\n"
+      end
+      register_default_tools
+      @logger.info "Rails Active MCP Server initialized with #{@tools.size} tools"
+    end
+
+    def run
+      @logger.info 'Starting Rails Active MCP Stdio Server'
+      send_log_notification('info', 'Rails Active MCP Server started successfully')
+
+      STDIN.each_line do |line|
+        line = line.strip
+        next if line.empty?
+
+        @logger.debug "Received request: #{line}" if ENV['RAILS_MCP_DEBUG']
+        data = JSON.parse(line)
+
+        @logger.debug "Processing method: #{data['method']}" if ENV['RAILS_MCP_DEBUG']
+        response = handle_jsonrpc_request(data)
+
+        if response
+          @logger.debug "Sending response: #{response.to_json}" if ENV['RAILS_MCP_DEBUG']
+          puts response.to_json
+          STDOUT.flush
+        end
+      rescue JSON::ParserError => e
+        @logger.error "JSON Parse Error: #{e.message}"
+        send_log_notification('error', "JSON Parse Error: #{e.message}")
+        error_response = jsonrpc_error(nil, -32_700, 'Parse error')
+        puts error_response.to_json
+        STDOUT.flush
+      rescue StandardError => e
+        @logger.error "Unexpected error: #{e.message}"
+        @logger.error e.backtrace.join("\n")
+        send_log_notification('error', "Server error: #{e.message}")
+        error_response = jsonrpc_error(nil, -32_603, 'Internal error')
+        puts error_response.to_json
+        STDOUT.flush
+      end
+    end
+
+    private
+
+    def handle_jsonrpc_request(data)
+      case data['method']
+      when 'initialize'
+        handle_initialize(data)
+      when 'tools/list'
+        handle_tools_list(data)
+      when 'tools/call'
+        handle_tools_call(data)
+      when 'resources/list'
+        handle_resources_list(data)
+      when 'resources/read'
+        handle_resources_read(data)
+      when 'ping'
+        handle_ping(data)
+      else
+        jsonrpc_error(data['id'], -32_601, 'Method not found')
+      end
+    end
+
+    def handle_initialize(data)
+      {
+        jsonrpc: JSONRPC_VERSION,
+        id: data['id'],
+        result: {
+          protocolVersion: MCP_VERSION,
+          capabilities: {
+            tools: {},
+            resources: {}
+          },
+          serverInfo: {
+            name: 'rails-active-mcp',
+            version: RailsActiveMcp::VERSION
+          }
+        }
+      }
+    end
+
+    def handle_tools_list(data)
+      tools_array = @tools.values.map do |tool|
+        tool_def = {
+          name: tool[:name],
+          description: tool[:description],
+          inputSchema: tool[:input_schema]
+        }
+
+        # Add annotations if present
+        tool_def[:annotations] = tool[:annotations] if tool[:annotations] && !tool[:annotations].empty?
+
+        tool_def
+      end
+
+      {
+        jsonrpc: JSONRPC_VERSION,
+        id: data['id'],
+        result: { tools: tools_array }
+      }
+    end
+
+    def handle_tools_call(data)
+      tool_name = data.dig('params', 'name')
+      arguments = data.dig('params', 'arguments') || {}
+
+      tool = @tools[tool_name]
+      return jsonrpc_error(data['id'], -32_602, "Tool '#{tool_name}' not found") unless tool
+
+      @logger.info "Executing tool: #{tool_name}"
+      send_log_notification('info', "Executing tool: #{tool_name}")
+
+      begin
+        start_time = Time.now
+        result = tool[:handler].call(arguments)
+        execution_time = Time.now - start_time
+
+        @logger.info "Tool #{tool_name} completed in #{execution_time}s"
+        send_log_notification('info', "Tool #{tool_name} completed successfully")
+
+        {
+          jsonrpc: JSONRPC_VERSION,
+          id: data['id'],
+          result: {
+            content: [{ type: 'text', text: result.to_s }],
+            isError: false
+          }
+        }
+      rescue StandardError => e
+        @logger.error "Tool execution error: #{e.message}"
+        @logger.error e.backtrace.first(5).join("\n") if ENV['RAILS_MCP_DEBUG']
+        send_log_notification('error', "Tool #{tool_name} failed: #{e.message}")
+
+        {
+          jsonrpc: JSONRPC_VERSION,
+          id: data['id'],
+          result: {
+            content: [{ type: 'text', text: "Error: #{e.message}" }],
+            isError: true
+          }
+        }
+      end
+    end
+
+    def handle_resources_list(data)
+      {
+        jsonrpc: JSONRPC_VERSION,
+        id: data['id'],
+        result: { resources: [] }
+      }
+    end
+
+    def handle_resources_read(data)
+      {
+        jsonrpc: JSONRPC_VERSION,
+        id: data['id'],
+        result: { contents: [] }
+      }
+    end
+
+    def handle_ping(data)
+      {
+        jsonrpc: JSONRPC_VERSION,
+        id: data['id'],
+        result: {}
+      }
+    end
+
+    def register_tool(name, description, input_schema, annotations = {}, &handler)
+      @tools[name] = {
+        name: name,
+        description: description,
+        input_schema: input_schema,
+        annotations: annotations,
+        handler: handler
+      }
+    end
+
+    def register_default_tools
+      register_tool(
+        'rails_console_execute',
+        'Execute Ruby code in Rails console context',
+        {
+          type: 'object',
+          properties: {
+            code: { type: 'string', description: 'Ruby code to execute' },
+            timeout: { type: 'number', description: 'Timeout in seconds', default: 30 },
+            safe_mode: { type: 'boolean', description: 'Enable safety checks', default: true },
+            capture_output: { type: 'boolean', description: 'Capture console output', default: true }
+          },
+          required: ['code']
+        },
+        {
+          title: 'Rails Console Executor',
+          readOnlyHint: false,
+          destructiveHint: true,
+          idempotentHint: false,
+          openWorldHint: false
+        }
+      ) do |args|
+        execute_console_code(args)
+      end
+
+      register_tool(
+        'rails_model_info',
+        'Get information about Rails models including columns, associations, and table structure',
+        {
+          type: 'object',
+          properties: {
+            model_name: { type: 'string', description: 'Name of the Rails model class to inspect' }
+          },
+          required: ['model_name']
+        },
+        {
+          title: 'Rails Model Inspector',
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: false
+        }
+      ) do |args|
+        get_model_info(args['model_name'])
+      end
+
+      register_tool(
+        'rails_safe_query',
+        'Execute safe read-only database queries using ActiveRecord',
+        {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'ActiveRecord query to execute (read-only methods only)' },
+            model: { type: 'string', description: 'Model class name to query against' }
+          },
+          required: %w[query model]
+        },
+        {
+          title: 'Rails Safe Query Executor',
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: false
+        }
+      ) do |args|
+        execute_safe_query(args)
+      end
+
+      register_tool(
+        'rails_dry_run',
+        'Analyze Ruby code for safety without executing it',
+        {
+          type: 'object',
+          properties: {
+            code: { type: 'string', description: 'Ruby code to analyze for safety and potential issues' }
+          },
+          required: ['code']
+        },
+        {
+          title: 'Rails Code Safety Analyzer',
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: false
+        }
+      ) do |args|
+        dry_run_analysis(args['code'])
+      end
+    end
+
+    # Tool implementation methods (reused from McpServer)
+    def execute_console_code(args)
+      unless defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config) && RailsActiveMcp.config.enabled
+        return 'Rails Active MCP is disabled. Enable it in your Rails configuration.'
+      end
+
+      executor = RailsActiveMcp::ConsoleExecutor.new(RailsActiveMcp.config)
+
+      begin
+        result = executor.execute(
+          args['code'],
+          timeout: args['timeout'] || 30,
+          safe_mode: args['safe_mode'] != false,
+          capture_output: args['capture_output'] != false
+        )
+
+        if result[:success]
+          format_success_result(result)
+        else
+          "Error: #{result[:error]} (#{result[:error_class]})"
+        end
+      rescue RailsActiveMcp::SafetyError => e
+        "Safety check failed: #{e.message}"
+      rescue RailsActiveMcp::TimeoutError => e
+        "Execution timed out: #{e.message}"
+      rescue StandardError => e
+        "Execution failed: #{e.message}"
+      end
+    end
+
+    def get_model_info(model_name)
+      unless defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config) && RailsActiveMcp.config.enabled
+        return 'Rails Active MCP is disabled. Enable it in your Rails configuration.'
+      end
+
+      begin
+        # Try to load Rails environment if not already loaded
+        require_relative '../../../config/environment' if !defined?(Rails) && File.exist?('config/environment.rb')
+
+        model_class = model_name.constantize
+        unless defined?(ActiveRecord) && model_class < ActiveRecord::Base
+          return "#{model_name} is not an ActiveRecord model"
+        end
+
+        info = []
+        info << "Model: #{model_class.name}"
+        info << "Table: #{model_class.table_name}"
+        info << "Columns: #{model_class.column_names.join(', ')}"
+
+        associations = model_class.reflect_on_all_associations.map(&:name)
+        info << "Associations: #{associations.any? ? associations.join(', ') : 'None'}"
+
+        # Add validation info if available
+        if model_class.respond_to?(:validators) && model_class.validators.any?
+          validations = model_class.validators.map { |v| "#{v.attributes.join(', ')}: #{v.class.name.demodulize}" }.uniq
+          info << "Validations: #{validations.join(', ')}"
+        end
+
+        info.join("\n")
+      rescue NameError
+        "Model '#{model_name}' not found. Make sure the model class exists and is properly defined."
+      rescue StandardError => e
+        "Error getting model info: #{e.message}"
+      end
+    end
+
+    def execute_safe_query(args)
+      unless defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config) && RailsActiveMcp.config.enabled
+        return 'Rails Active MCP is disabled. Enable it in your Rails configuration.'
+      end
+
+      begin
+        # Try to load Rails environment if not already loaded
+        require_relative '../../../config/environment' if !defined?(Rails) && File.exist?('config/environment.rb')
+
+        model_class = args['model'].constantize
+        unless defined?(ActiveRecord) && model_class < ActiveRecord::Base
+          return "#{args['model']} is not an ActiveRecord model"
+        end
+
+        # Only allow safe read-only methods
+        safe_methods = %w[find find_by where select count sum average maximum minimum first last pluck ids exists?
+                          empty? any? many? include? limit offset order group having joins includes references distinct uniq readonly]
+
+        # Extract the first method call to validate it's safe
+        query_parts = args['query'].split('.')
+        query_method = query_parts.first.split('(').first
+
+        unless safe_methods.include?(query_method)
+          return "Unsafe query method: #{query_method}. Only read-only methods are allowed."
+        end
+
+        result = model_class.instance_eval(args['query'])
+
+        # Format result appropriately
+        case result
+        when ActiveRecord::Relation
+          "Query returned #{result.count} records: #{result.limit(10).pluck(:id).join(', ')}#{result.count > 10 ? '...' : ''}"
+        when Array
+          "Array with #{result.length} items: #{result.take(5).inspect}#{result.length > 5 ? '...' : ''}"
+        else
+          result.to_s
+        end
+      rescue NameError
+        "Model '#{args['model']}' not found. Make sure the model class exists and is properly defined."
+      rescue StandardError => e
+        "Error executing query: #{e.message}"
+      end
+    end
+
+    def dry_run_analysis(code)
+      unless defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config) && RailsActiveMcp.config.enabled
+        return 'Rails Active MCP is disabled. Enable it in your Rails configuration.'
+      end
+
+      executor = RailsActiveMcp::ConsoleExecutor.new(RailsActiveMcp.config)
+
+      begin
+        analysis = executor.dry_run(code)
+
+        output = []
+        output << 'Code Analysis Results:'
+        output << "Code: #{analysis[:code]}"
+        output << "Safe: #{analysis[:safety_analysis][:safe] ? 'Yes' : 'No'}"
+        output << "Read-only: #{analysis[:safety_analysis][:read_only] ? 'Yes' : 'No'}"
+        output << "Risk level: #{analysis[:estimated_risk]}"
+        output << "Would execute: #{analysis[:would_execute] ? 'Yes' : 'No'}"
+        output << "Summary: #{analysis[:safety_analysis][:summary]}"
+
+        if analysis[:safety_analysis][:violations] && analysis[:safety_analysis][:violations].any?
+          output << "\nSafety Violations:"
+          analysis[:safety_analysis][:violations].each do |violation|
+            output << "  - #{violation[:description]} (#{violation[:severity]})"
+          end
+        end
+
+        if analysis[:recommendations] && analysis[:recommendations].any?
+          output << "\nRecommendations:"
+          analysis[:recommendations].each do |rec|
+            output << "  - #{rec}"
+          end
+        end
+
+        output.join("\n")
+      rescue StandardError => e
+        "Analysis failed: #{e.message}. Make sure the Rails environment is properly loaded."
+      end
+    end
+
+    def format_success_result(result)
+      output = []
+      output << 'Execution Results:'
+      output << "Code: #{result[:code]}"
+      output << "Result: #{result[:return_value_string] || result[:return_value]}"
+      output << "Output: #{result[:output]}" if result[:output] && !result[:output].empty?
+      output << "Execution time: #{result[:execution_time]}s" if result[:execution_time]
+      output << "Note: #{result[:note]}" if result[:note]
+      output.join("\n")
+    end
+
+    def send_log_notification(level, message)
+      notification = {
+        jsonrpc: JSONRPC_VERSION,
+        method: 'notifications/message',
+        params: {
+          level: level,
+          data: message
+        }
+      }
+
+      puts notification.to_json
+      STDOUT.flush
+    rescue StandardError => e
+      @logger.error "Failed to send log notification: #{e.message}"
+    end
+
+    def jsonrpc_error(id, code, message)
+      {
+        jsonrpc: JSONRPC_VERSION,
+        id: id,
+        error: { code: code, message: message }
+      }
+    end
+  end
+end

data/lib/rails_active_mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-active-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Brandyn Britton
@@ -193,6 +193,7 @@ files:
 - ".idea/vcs.xml"
 - README.md
 - changelog.md
+- docs/DEBUGGING.md
 - docs/README.md
 - exe/rails-active-mcp-server
 - lib/generators/rails_active_mcp/install/install_generator.rb
@@ -206,6 +207,7 @@ files:
 - lib/rails_active_mcp/mcp_server.rb
 - lib/rails_active_mcp/railtie.rb
 - lib/rails_active_mcp/safety_checker.rb
+- lib/rails_active_mcp/stdio_server.rb
 - lib/rails_active_mcp/tasks.rake
 - lib/rails_active_mcp/tools/console_execute_tool.rb
 - lib/rails_active_mcp/tools/dry_run_tool.rb