rails-active-mcp 0.1.7 → 2.0.8

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