rails-active-mcp 0.1.7 → 2.0.7

data/docs/README.md

@@ -1,22 +1,20 @@
 # Rails Active MCP Documentation
 
 ## Introduction
-Rails Active MCP is a Ruby gem that integrates the Model Context Protocol (MCP) into Rails applications. It provides a secure, configurable, and extensible server for AI agents and developer tools to interact with your Rails app via a standardized protocol.
+Rails Active MCP is a Ruby gem that integrates the Model Context Protocol (MCP) into Rails applications using the official MCP Ruby SDK. It provides a secure, configurable, and professional server for AI agents and developer tools to interact with your Rails app via the standardized MCP protocol.
 
 ## How It Works
-- **Custom MCP Server**: Implements the MCP protocol (JSON-RPC 2.0 over HTTP) as a Rack middleware, mountable in Rails or runnable standalone.
-- **Tooling**: Exposes a set of tools (e.g., safe console execution, model info, safe queries, code analysis) to MCP clients.
-- **Safety**: Advanced safety checks, read-only modes, and audit logging protect your application from dangerous operations.
-- **Integration**: Easily added to any Rails 7+ app via a generator, with configuration via an initializer.
+- **Official MCP SDK**: Built on the official MCP Ruby SDK (`mcp` gem) for robust protocol handling
+- **Professional Implementation**: Automatic instrumentation, timing, and error reporting
+- **Tooling**: Exposes four powerful tools (console execution, model info, safe queries, code analysis) to MCP clients
+- **Safety**: Advanced safety checks, read-only modes, and audit logging protect your application from dangerous operations
+- **Integration**: Easily added to any Rails application via a generator, with simplified configuration
 
 ## MCP Protocol Overview
-- **MCP**: The Model Context Protocol is a standard for structured, secure, and auditable access to application internals for AI agents and developer tools.
-- **Supported Methods**:
-  - `initialize`: Returns server capabilities and protocol version.
-  - `tools/list`: Lists available tools and their schemas.
-  - `tools/call`: Executes a tool with given arguments.
-  - `resources/list` and `resources/read`: (Stubbed, for future resource access.)
-- **JSON-RPC 2.0**: All communication uses JSON-RPC 2.0 over HTTP POST.
+- **MCP**: The Model Context Protocol is a standard for structured, secure, and auditable access to application internals for AI agents and developer tools
+- **Official SDK**: Uses the official MCP Ruby SDK for protocol compliance and future-proof compatibility
+- **STDIO Transport**: Perfect for Claude Desktop integration
+- **JSON-RPC 2.0**: All communication uses JSON-RPC 2.0 with automatic protocol handling
 
 ## Installation & Setup
 1. Add to your Gemfile:
@@ -28,158 +26,148 @@ Rails Active MCP is a Ruby gem that integrates the Model Context Protocol (MCP)
    bundle install
    rails generate rails_active_mcp:install
    ```
-   This creates an initializer, mounts the MCP server at `/mcp`, and sets up audit logging.
+   This creates an initializer and sets up the Rails integration.
 3. Start the server:
-   - Rails: `rails server` (MCP at `/mcp`)
-   - Standalone: `bundle exec rails-active-mcp-server`
-   - Rack: `rackup mcp.ru -p 3001`
+   ```bash
+   bundle exec rails-active-mcp-server
+   ```
 
 ## Configuration
 Edit `config/initializers/rails_active_mcp.rb`:
-- Enable/disable the server
-- Safety mode (production = strict)
-- Allowed/blocked models
-- Enable/disable mutation tools
-- Audit log location
-- Environment presets: `production_mode!`, `strict_mode!`, `permissive_mode!`
 
-## Available Tools
-- **rails_console_execute**: Execute Ruby code in Rails with safety checks
-- **rails_model_info**: Inspect model schema and associations
-- **rails_safe_query**: Run safe, read-only queries on models
-- **rails_dry_run**: Analyze code for safety without executing
+```ruby
+RailsActiveMcp.configure do |config|
+  # 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
+  ]
+  config.command_timeout = 30
+  config.enable_logging = true
+  config.log_level = :info
+end
+```
 
-Each tool is described in the MCP `tools/list` response and can be extended or customized.
+## Available Tools
 
-## Security & Safety
-- **Safety Checker**: Blocks dangerous operations (e.g., mass deletions, system commands, file access)
-- **Read-Only Mode**: Enforced in production
-- **Audit Logging**: All executions are logged to `log/rails_active_mcp.log`
-- **Configurable**: Fine-tune what is allowed per environment
+### 1. console_execute
+**Purpose:**
+Execute Ruby code in the Rails console context with safety checks and timeout protection.
 
-## Extending the Gem
-- Add custom tools by calling `RailsActiveMcp.server.register_tool` in an initializer or plugin.
-- Tools must define a name, description, input schema, and a handler block.
+**Features:**
+- Built-in dangerous operation detection
+- Configurable execution timeout
+- All executions logged for audit
+- Safe execution environment
 
-## Testing & Specification Adherence
-- All features are covered by RSpec tests in the `spec/` directory.
-- Follows standard Ruby/Rails conventions for gems, engines, and generators.
-- MCP protocol compliance is maintained as per [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction).
+**Example Usage in Claude:**
+> "Execute `User.where(active: true).count`"
 
-## Per-Tool Breakdown
+---
 
-### 1. rails_console_execute
+### 2. model_info
 **Purpose:**
-Execute arbitrary Ruby code in the Rails console context, with safety checks and output capture.
-
-**Input Parameters:**
-- `code` (string, required): Ruby code to execute.
-- `safe_mode` (boolean, optional): Enable safety checks (default: true).
-- `timeout` (integer, optional): Timeout in seconds (default: 30).
-- `capture_output` (boolean, optional): Capture console output (default: true).
-
-**Output:**
-- On success: Code, result, output (if any), execution time, and notes.
-- On error: Error message and class.
-
-**Example Usage:**
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "rails_console_execute",
-    "arguments": {
-      "code": "User.count"
-    }
-  }
-}
-```
+Get detailed information about Rails models including schema, associations, and validations.
+
+**Features:**
+- Schema information (column types, constraints, indexes)
+- Association details (has_many, belongs_to, has_one relationships)
+- Validation rules and constraints
+- Available instance and class methods
+
+**Example Usage in Claude:**
+> "Show me the User model structure"
 
 ---
 
-### 2. rails_model_info
+### 3. safe_query
 **Purpose:**
-Get detailed information about a Rails model, including schema, associations, and validations.
-
-**Input Parameters:**
-- `model` (string, required): Model class name (e.g., "User").
-- `include_schema` (boolean, optional): Include database schema info (default: true).
-- `include_associations` (boolean, optional): Include model associations (default: true).
-- `include_validations` (boolean, optional): Include model validations (default: true).
-
-**Output:**
-- Model name, table, primary key, schema (columns, types, null/default), associations, validations.
-- On error: Error message (e.g., model not found).
-
-**Example Usage:**
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "rails_model_info",
-    "arguments": {
-      "model": "User"
-    }
-  }
-}
-```
+Execute safe, read-only database queries with automatic safety analysis.
+
+**Features:**
+- Read-only operations only (SELECT queries)
+- Automatic query analysis for safety
+- Result limiting to prevent large data dumps
+- Works within your model definitions
+
+**Example Usage in Claude:**
+> "Get the 10 most recent orders"
 
 ---
 
-### 3. rails_safe_query
+### 4. dry_run
 **Purpose:**
-Execute safe, read-only database queries on Rails models.
-
-**Input Parameters:**
-- `model` (string, required): Model class name (e.g., "User").
-- `method` (string, required): Query method (e.g., "where", "count").
-- `args` (array, optional): Arguments for the query method.
-- `limit` (integer, optional): Limit results (default: 100).
-
-**Output:**
-- Query string, count, and result (as inspected Ruby object).
-- On error: Error message.
-
-**Example Usage:**
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "rails_safe_query",
-    "arguments": {
-      "model": "User",
-      "method": "where",
-      "args": [{"active": true}],
-      "limit": 10
-    }
-  }
-}
+Analyze Ruby code for safety without executing it.
+
+**Features:**
+- Risk assessment and categorization
+- Safety analysis with detailed feedback
+- Recommendations for safer alternatives
+- Zero execution guarantee
+
+**Example Usage in Claude:**
+> "Analyze this code for safety: `User.delete_all`"
+
+## Security & Safety
+- **Safety Checker**: Blocks dangerous operations (mass deletions, system commands, file access)
+- **Read-Only Detection**: Identifies and promotes safe read-only operations
+- **Audit Logging**: All executions are logged with detailed context
+- **Configurable**: Fine-tune safety levels per environment
+
+## Architecture
+
+### Built on Official MCP Ruby SDK
+Rails Active MCP leverages the official MCP Ruby SDK for:
+
+- **Professional Protocol Handling**: Robust JSON-RPC 2.0 implementation
+- **Built-in Instrumentation**: Automatic timing and error reporting
+- **Future-Proof**: Automatic updates as MCP specification evolves
+- **Standards Compliance**: Full MCP protocol compatibility
+
+### Server Implementation
+The server is implemented in `lib/rails_active_mcp/sdk/server.rb` and provides:
+
+- **STDIO Transport**: Perfect for Claude Desktop integration
+- **Tool Registration**: Automatic discovery of available tools
+- **Error Handling**: Comprehensive error reporting and recovery
+- **Rails Integration**: Deep integration with Rails applications
+
+### Tool Architecture
+Each tool is implemented as a separate class in `lib/rails_active_mcp/sdk/tools/`:
+
+- `ConsoleExecuteTool`: Safe code execution
+- `ModelInfoTool`: Model introspection  
+- `SafeQueryTool`: Read-only database access
+- `DryRunTool`: Code safety analysis
+
+## Testing & Development
+
+### Running Tests
+```bash
+$ bundle exec rspec
 ```
 
----
+### Testing MCP Integration
+```bash
+$ ./bin/test-mcp-output
+```
 
-### 4. rails_dry_run
-**Purpose:**
-Analyze Ruby code for safety and risk without executing it.
-
-**Input Parameters:**
-- `code` (string, required): Ruby code to analyze.
-
-**Output:**
-- Code, safety status, read-only status, risk level, summary, violations, and recommendations.
-
-**Example Usage:**
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "rails_dry_run",
-    "arguments": {
-      "code": "User.delete_all"
-    }
-  }
-}
+### Debugging
+Set the debug environment variable for detailed logging:
+```bash
+$ RAILS_MCP_DEBUG=1 bundle exec rails-active-mcp-server
 ```
 
----
-For more details, see the main project README or source code. 
+## Extending the Gem
+The gem is designed to be extensible. You can add custom tools by:
+
+1. Creating new tool classes in your application
+2. Following the MCP tool interface pattern
+3. Registering tools with the server during initialization
+
+Each tool must implement the standard MCP tool interface with proper input schemas and error handling.
+
+
+For more details, see the main project README or explore the source code in `lib/rails_active_mcp/sdk/`. 

data/exe/rails-active-mcp-server

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