rails-active-mcp 0.1.6 → 2.0.7

data/docs/DEBUGGING.md

@@ -60,10 +60,10 @@ This enables:
 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`
+   - `console_execute`
+   - `model_info`
+   - `safe_query`
+   - `dry_run`
 
 #### Viewing Claude Desktop Logs
 
@@ -126,7 +126,7 @@ The logs show:
   "mcpServers": {
     "rails-active-mcp": {
       "command": "bundle",
-      "args": ["exec", "rails-active-mcp-server", "stdio"],
+      "args": ["exec", "rails-active-mcp-server"],
       "cwd": "/path/to/rails/project",
       "env": {
         "RAILS_ENV": "development",
@@ -137,7 +137,39 @@ The logs show:
 }
 ```
 
-### 3. Server Initialization Problems
+**Note**: The server will use the mode configured in your Rails initializer (`:stdio` by default). You can override this by adding the mode as an argument: `["exec", "rails-active-mcp-server", "stdio"]`
+
+### 3. Server Mode Configuration
+
+**Problem**: Want to change the default server mode.
+
+**Solution**: Configure server mode in your Rails initializer:
+
+```ruby
+# config/initializers/rails_active_mcp.rb
+RailsActiveMcp.configure do |config|
+  # For Claude Desktop (default)
+  config.server_mode = :stdio
+  
+  # For HTTP-based integrations
+  config.http_mode!(host: '0.0.0.0', port: 8080)
+  
+  # Or just set stdio mode
+  config.stdio_mode!
+end
+```
+
+**Command line override**:
+```bash
+# Use configured mode
+bundle exec rails-active-mcp-server
+
+# Force specific mode
+bundle exec rails-active-mcp-server stdio
+bundle exec rails-active-mcp-server http --port 8080
+```
+
+### 4. Server Initialization Problems
 
 **Common initialization issues:**
 
@@ -162,7 +194,7 @@ The logs show:
    chmod +x exe/rails-active-mcp-server
    ```
 
-### 4. Connection Problems
+### 5. Connection Problems
 
 **Problem**: Claude Desktop can't connect to server.
 
@@ -246,7 +278,7 @@ Should return all 4 Rails Active MCP tools.
 
 ```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
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"dry_run","arguments":{"code":"puts \"Hello World\""}}}' | bundle exec rails-active-mcp-server
 ```
 
 ## Best Practices

data/docs/GENERATOR_TESTING.md

@@ -0,0 +1,121 @@
+# Testing the Rails Active MCP Generator
+
+This guide explains how to test that your Rails Active MCP generator is working correctly.
+
+## Quick Test in a New Rails App
+
+1. **Create a test Rails app:**
+   ```bash
+   rails new test_mcp_app
+   cd test_mcp_app
+   ```
+
+2. **Add your gem to the Gemfile:**
+   ```ruby
+   # Add to Gemfile
+   gem 'rails-active-mcp', path: '/path/to/your/gem'
+   # OR if published:
+   gem 'rails-active-mcp'
+   ```
+
+3. **Bundle install:**
+   ```bash
+   bundle install
+   ```
+
+4. **Check if the generator is available:**
+   ```bash
+   rails generate --help
+   ```
+   You should see `rails_active_mcp:install` in the list.
+
+5. **Run the generator:**
+   ```bash
+   rails generate rails_active_mcp:install
+   ```
+
+6. **Verify generated files:**
+   - `config/initializers/rails_active_mcp.rb` should exist
+   - `mcp.ru` should exist
+   - `config/routes.rb` should have the mount line added
+
+## What the Generator Should Create
+
+### Initializer File
+Location: `config/initializers/rails_active_mcp.rb`
+
+Should contain:
+- Configuration block with `RailsActiveMcp.configure`
+- Environment-specific settings
+- Safety and logging configuration
+
+### MCP Server Configuration
+Location: `mcp.ru`
+
+Should contain:
+- Rack configuration for standalone MCP server
+- Proper requires and server initialization
+
+### Route Addition
+In `config/routes.rb`:
+- Should add: `mount RailsActiveMcp::McpServer.new, at: '/mcp'`
+
+## Generator Commands to Test
+
+```bash
+# See generator help
+rails generate rails_active_mcp:install --help
+
+# Run with verbose output
+rails generate rails_active_mcp:install --verbose
+
+# Skip files (for testing)
+rails generate rails_active_mcp:install --skip-route
+```
+
+## Common Issues and Solutions
+
+### Generator Not Found
+If `rails generate rails_active_mcp:install` returns "Could not find generator", check:
+
+1. **Gem is properly installed:** `bundle list | grep rails-active-mcp`
+2. **Generator file exists:** Check `lib/generators/rails_active_mcp/install/install_generator.rb`
+3. **Class name matches:** Ensure class is `RailsActiveMcp::Generators::InstallGenerator`
+4. **Engine is loaded:** Check that the Engine is being required
+
+### Files Not Generated
+If files aren't created:
+
+1. **Check permissions:** Ensure Rails can write to the directories
+2. **Check templates:** Verify template files exist in `templates/` directory
+3. **Check source_root:** Ensure `source_root` points to correct directory
+
+### Route Not Added
+If the route isn't added to `config/routes.rb`:
+
+1. **Check routes.rb exists:** Generator requires existing routes file
+2. **File permissions:** Ensure routes.rb is writable
+
+## Running Tests
+
+Run the generator specs:
+```bash
+bundle exec rspec spec/generators/
+```
+
+## Debugging Generator Issues
+
+Add debugging to your generator:
+```ruby
+def create_initializer
+  say "Creating initializer at: #{destination_root}/config/initializers/rails_active_mcp.rb"
+  template 'initializer.rb', 'config/initializers/rails_active_mcp.rb'
+  say "Initializer created successfully", :green
+end
+```
+
+Check Rails generator resolution:
+```ruby
+# In rails console
+Rails::Generators.find_by_namespace("rails_active_mcp:install")
+``` 

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/`.