rails-active-mcp 0.1.1

data/docs/README.md

@@ -0,0 +1,185 @@
+# 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.
+
+## 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.
+
+## 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.
+
+## Installation & Setup
+1. Add to your Gemfile:
+   ```ruby
+   gem 'rails-active-mcp'
+   ```
+2. Run:
+   ```bash
+   bundle install
+   rails generate rails_active_mcp:install
+   ```
+   This creates an initializer, mounts the MCP server at `/mcp`, and sets up audit logging.
+3. Start the server:
+   - Rails: `rails server` (MCP at `/mcp`)
+   - Standalone: `bundle exec rails-active-mcp-server`
+   - Rack: `rackup mcp.ru -p 3001`
+
+## 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
+
+Each tool is described in the MCP `tools/list` response and can be extended or customized.
+
+## 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
+
+## 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.
+
+## 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).
+
+## Per-Tool Breakdown
+
+### 1. rails_console_execute
+**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"
+    }
+  }
+}
+```
+
+---
+
+### 2. rails_model_info
+**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"
+    }
+  }
+}
+```
+
+---
+
+### 3. rails_safe_query
+**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
+    }
+  }
+}
+```
+
+---
+
+### 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"
+    }
+  }
+}
+```
+
+---
+For more details, see the main project README or source code. 

data/exe/rails-active-mcp-server

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'rack'
+require 'rack/handler/webrick'
+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

data/lib/generators/rails_active_mcp/install/install_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class RailsActiveMcp::InstallGenerator < Rails::Generators::Base
+  source_root File.expand_path('templates', __dir__)
+
+  desc 'Install Rails Active MCP'
+
+  def create_initializer
+    template 'initializer.rb', 'config/initializers/rails_active_mcp.rb'
+  end
+
+  def create_mcp_route
+    route "mount RailsActiveMcp::McpServer.new, at: '/mcp' # Rails Active MCP"
+  end
+
+  def create_mcp_config
+    template 'mcp.ru', 'mcp.ru'
+  end
+
+  def show_readme
+    readme 'README.md' if behavior == :invoke
+  end
+
+  private
+
+  def readme(path)
+    readme_path = File.join(self.class.source_root, path)
+    if File.exist?(readme_path)
+      say IO.read(readme_path), :green
+    else
+      say "README file not found at #{readme_path}", :yellow
+    end
+  rescue => e
+    say "Error reading README: #{e.message}", :red
+  end
+
+end

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

@@ -0,0 +1,60 @@
+
+================================================================================
+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. Start the MCP server:
+   Option A: Rails-mounted server
+   $ rails server
+
+   Option B: Standalone server
+   $ bundle exec rails-active-mcp-server
+
+   Option C: Using rackup
+   $ rackup mcp.ru -p 3001
+
+3. For Warp Terminal integration, add this to your MCP configuration:
+   {
+     "mcpServers": {
+       "rails-console": {
+         "command": "curl",
+         "args": ["-X", "POST", "-H", "Content-Type: application/json", "-d", "@-", "http://localhost:3000/mcp"]
+       }
+     }
+   }
+
+4. 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
+
+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
+
+Custom MCP Server Benefits:
+- No external dependencies
+- Full control over implementation
+- Simplified deployment
+- Enhanced security
+
+For more information: https://github.com/goodpie/rails-active-mcp
+
+================================================================================

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

@@ -0,0 +1,39 @@
+require 'rails_active_mcp'
+
+
+RailsActiveMcp.configure do |config|
+  # Enable/disable the MCP server
+  config.enabled = true
+
+  # Safety configuration
+  config.safe_mode = Rails.env.production? # Always safe in production
+  config.default_timeout = 30 # seconds
+  config.max_results = 100
+
+  # 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
+
+  # Mutation tools (dangerous operations)
+  config.enable_mutation_tools = !Rails.env.production?
+
+  # Logging and auditing
+  config.log_executions = true
+  config.audit_file = Rails.root.join("log", "rails_active_mcp.log")
+
+  # Environment-specific settings
+  case Rails.env
+  when 'production'
+    config.production_mode! # Very strict settings
+  when 'development'
+    config.permissive_mode! # More relaxed for development
+  when 'test'
+    config.strict_mode! # Safe for testing
+  end
+
+  # Add custom safety patterns
+  # config.add_safety_pattern(/CustomDangerousMethod/, "Custom dangerous operation")
+
+  # Operations that require manual confirmation
+  config.require_confirmation_for = [:delete, :destroy, :update_all, :delete_all]
+end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'config/environment'
+require 'rails_active_mcp'
+
+# Run the Rails Active MCP server
+run RailsActiveMcp::McpServer.new

data/lib/rails_active_mcp/configuration.rb

@@ -0,0 +1,95 @@
+require 'fileutils'
+
+module RailsActiveMcp
+  class Configuration
+    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
+
+    def initialize
+      @enabled = true
+      @safe_mode = true
+      @default_timeout = 30
+      @max_results = 100
+      @allowed_models = [] # Empty means all models allowed
+      @blocked_models = []
+      @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
+      @enable_mutation_tools = false
+      @require_confirmation_for = [:delete, :destroy, :update_all, :delete_all]
+      @execution_environment = :current # :current, :sandbox, :readonly_replica
+    end
+
+    # Safety configuration
+    def strict_mode!
+      @safe_mode = true
+      @enable_mutation_tools = false
+      @default_timeout = 15
+      @max_results = 50
+    end
+
+    def permissive_mode!
+      @safe_mode = false
+      @enable_mutation_tools = true
+      @default_timeout = 60
+      @max_results = 1000
+    end
+
+    def production_mode!
+      strict_mode!
+      @execution_environment = :readonly_replica
+      @log_executions = true
+      @require_confirmation_for = [:delete, :destroy, :update, :create, :save]
+    end
+
+    # Model access configuration
+    def allow_models(*models)
+      @allowed_models.concat(models.map(&:to_s))
+    end
+
+    def block_models(*models)
+      @blocked_models.concat(models.map(&:to_s))
+    end
+
+    def add_safety_pattern(pattern, description = nil)
+      @custom_safety_patterns << { pattern: pattern, description: description }
+    end
+
+    # Validation
+    def model_allowed?(model_name)
+      model_str = model_name.to_s
+
+      # Check if specifically blocked
+      return false if @blocked_models.include?(model_str)
+
+      # If allow list is empty, allow all (except blocked)
+      return true if @allowed_models.empty?
+
+      # Check allow list
+      @allowed_models.include?(model_str)
+    end
+
+    def validate!
+      raise ArgumentError, "timeout must be positive" if @default_timeout <= 0
+      raise ArgumentError, "max_results must be positive" if @max_results <= 0
+
+      if defined?(Rails) && @audit_file
+        audit_dir = File.dirname(@audit_file)
+        FileUtils.mkdir_p(audit_dir) unless File.directory?(audit_dir)
+      end
+    end
+
+    private
+
+    def rails_root_join(*args)
+      if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        Rails.root.join(*args)
+      else
+        File.join(Dir.pwd, *args)
+      end
+    end
+  end
+end