rails-active-mcp 0.1.6 → 2.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b477f00244c6b1b3370cc65295e401e4976d2c793e6d7344350866f5a21156eb
-  data.tar.gz: 38f43074ef26d934177dbd4a169efcd2f4b7c5cccac8b276e4927de7e5cca4cd
+  metadata.gz: dce4c2f44cc53bb550f74c549f92073a367817bf31bc2ae05a6dad17eca0ae29
+  data.tar.gz: 76645f3c0b20e148cf0044afb9dea1c8ed6064ce6e4067b6bf1b5b9cbd5c86d1
 SHA512:
-  metadata.gz: de2f7f0d0d4a2122dc2e83da7f3d3e9da08fc0d94ea93c61cf63fa2f4861695624c30da605ada7ff81f6a50dd8698b211f7b01bd54c128815d851f812e622d12
-  data.tar.gz: de6ce9166bb2da50fc492a784bac432e632d0d26dec52c1c506a49038d99c05dfe042819b67b70c98ff2371a3d0f1fc1e042f32ba48fc0470023ed0f011be3cd
+  metadata.gz: 7d7c5e938697d29db91f0276b008aa2c64307a7ff90b3afcd88c458244ee10b2ae82a4ae8014da06ea5ef99f020ffd8feaf6c66af29741f31a8b37b5300f2f26
+  data.tar.gz: 73950d69c48e192edb0071f3138eea1a148fa9ab557f67fdba8283ce5a3b188e3ee4f9297bdc1381eee74633fe0411e0d5e5affb964e5713ad4796be124b47f9

data/README.md

@@ -1,16 +1,17 @@
 # Rails Active MCP
 
-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.
+A Ruby gem that provides secure Rails console access through Model Context Protocol (MCP) for AI agents and development tools like Claude Desktop. Built using the official MCP Ruby SDK for professional protocol handling and future-proof compatibility.
 
 ## Features
 
 - 🔒 **Safe Execution**: Advanced safety checks prevent dangerous operations
-- 🚀 **Custom MCP Server**: Built-in MCP server with no external dependencies
+- 🚀 **Official MCP SDK**: Built with the official MCP Ruby SDK for robust protocol handling
 - 📊 **Read-Only Queries**: Safe database querying with automatic result limiting
 - 🔍 **Code Analysis**: Dry-run capabilities to analyze code before execution
 - 📝 **Audit Logging**: Complete execution logging for security and debugging
 - ⚙️ **Configurable**: Flexible configuration for different environments
 - 🛡️ **Production Ready**: Strict safety modes for production environments
+- ⚡ **Professional Implementation**: Built-in instrumentation, timing, and error handling
 
 ## Installation
 
@@ -35,7 +36,7 @@ $ rails generate rails_active_mcp:install
 This will:
 
 - Create an initializer with configuration options
-- Mount the custom MCP server at `/mcp`
+- Mount the MCP server for Rails integration
 - Create a `mcp.ru` server file for standalone usage
 - Set up audit logging
 
@@ -45,82 +46,36 @@ The gem is configured in `config/initializers/rails_active_mcp.rb`:
 
 ```ruby
 RailsActiveMcp.configure do |config|
-  # Basic settings
-  config.enabled = true
-  config.safe_mode = Rails.env.production?
-  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]
-
-  # Security settings
-  config.enable_mutation_tools = !Rails.env.production?
-  config.log_executions = true
-  config.audit_file = Rails.root.join("log", "rails_active_mcp.log")
-
-  # Environment presets
-  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
+  # 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
 ```
 
 ## Running the MCP Server
 
-You have several options for running the MCP server:
-
-### Option 1: Use configured mode (recommended)
+The server runs in STDIO mode, perfect for Claude Desktop integration:
 
 ```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 3: Standalone HTTP server
-
-```bash
-$ bundle exec rails-active-mcp-server http
-# Default: http://localhost:3001
-
-# Custom host/port
-$ bundle exec rails-active-mcp-server http --host 0.0.0.0 --port 8080
-```
-
-### Option 4: Using rackup
-
-```bash
-$ rackup mcp.ru -p 3001
-```
+The server automatically:
+- Loads your Rails application
+- Initializes all models and configurations
+- Provides secure access to your Rails environment
+- Uses the official MCP Ruby SDK for protocol handling
 
 ## Usage
 
-### With MCP Clients
-
-#### Claude Desktop Integration (Preferred)
+### Claude Desktop Integration (Recommended)
 
 Add to your Claude Desktop configuration file:
 
@@ -133,7 +88,7 @@ Add to your Claude Desktop configuration file:
   "mcpServers": {
     "rails-active-mcp": {
       "command": "bundle",
-      "args": ["exec", "rails-active-mcp-server", "stdio"],
+      "args": ["exec", "rails-active-mcp-server"],
       "cwd": "/path/to/your/rails/project"
     }
   }
@@ -147,7 +102,6 @@ Or if installed globally:
   "mcpServers": {
     "rails-active-mcp": {
       "command": "rails-active-mcp-server",
-      "args": ["stdio"],
       "cwd": "/path/to/your/rails/project"
     }
   }
@@ -161,142 +115,67 @@ Then in Claude Desktop, you can use prompts like:
 - "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:
-
-```json
-{
-  "mcpServers": {
-    "rails-console": {
-      "command": "curl",
-      "args": [
-        "-X",
-        "POST",
-        "-H",
-        "Content-Type: application/json",
-        "-d", "@-",
-        "http://localhost:3000/mcp"
-      ]
-    }
-  }
-}
-```
-
-#### Custom MCP Clients
-
-The server implements the MCP protocol (JSONRPC 2.0). Connect any MCP-compatible client to:
-- **Rails-mounted**: `http://localhost:3000/mcp`
-- **Standalone**: `http://localhost:3001`
-
 ### Direct Usage
 
 ```ruby
 # Execute code safely
 result = RailsActiveMcp.execute("User.count")
-puts result[:return_value] # => 42
 
 # Check if code is safe
 RailsActiveMcp.safe?("User.delete_all") # => false
-
-# Analyze code without executing
-executor = RailsActiveMcp::ConsoleExecutor.new(RailsActiveMcp.config)
-analysis = executor.dry_run("User.delete_all")
-puts analysis[:estimated_risk] # => :critical
 ```
 
-### Available MCP Tools
+## Available MCP Tools
 
-The Rails Active MCP server provides several built-in tools that will appear in Claude Desktop:
+The Rails Active MCP server provides four powerful tools that appear automatically in Claude Desktop:
 
-#### `rails_console_execute`
+### 1. `console_execute`
 
 Execute Ruby code with safety checks and timeout protection:
 
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "rails_console_execute",
-    "arguments": {
-      "code": "User.where(active: true).count",
-      "timeout": 30,
-      "safe_mode": true
-    }
-  }
-}
-```
+- **Purpose**: Run Rails console commands safely
+- **Safety**: Built-in dangerous operation detection
+- **Timeout**: Configurable execution timeout
+- **Logging**: All executions are logged for audit
 
-#### `rails_model_info`
+**Example Usage in Claude:**
+> "Execute `User.where(active: true).count`"
 
-Get detailed information about Rails models:
+### 2. `model_info`
 
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "rails_model_info",
-    "arguments": {
-      "model_name": "User"
-    }
-  }
-}
-```
+Get detailed information about Rails models:
 
-#### `rails_safe_query`
+- **Schema Information**: Column types, constraints, indexes
+- **Associations**: Has_many, belongs_to, has_one relationships
+- **Validations**: All model validations and rules
+- **Methods**: Available instance and class methods
 
-Execute safe, read-only database queries:
+**Example Usage in Claude:**
+> "Show me the User model structure"
 
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "rails_safe_query",
-    "arguments": {
-      "query": "where(active: true).count",
-      "model": "User"
-    }
-  }
-}
-```
+### 3. `safe_query`
 
-#### `rails_dry_run`
+Execute safe, read-only database queries:
 
-Analyze Ruby code for safety without executing:
+- **Read-Only**: Only SELECT operations allowed
+- **Safe Execution**: Automatic query analysis
+- **Result Limiting**: Prevents large data dumps
+- **Model Context**: Works within your model definitions
 
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "rails_dry_run",
-    "arguments": {
-      "code": "User.delete_all"
-    }
-  }
-}
-```
+**Example Usage in Claude:**
+> "Get the 10 most recent orders"
 
-#### Adding Custom Tools
+### 4. `dry_run`
 
-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`:
+Analyze Ruby code for safety without executing:
 
-```ruby
-def register_default_tools
-  # Built-in console execution tool
-  register_tool('rails_console_execute', 'Execute Ruby code safely', {...})
-
-  # Your custom tools
-  register_tool('my_custom_tool', 'Description', {...}) do |args|
-    # Tool implementation
-  end
-end
-```
+- **Risk Assessment**: Categorizes code by danger level
+- **Safety Analysis**: Identifies potential issues
+- **Recommendations**: Suggests safer alternatives
+- **Zero Execution**: Never runs the actual code
 
-Common tool implementations can include:
-- Code safety analysis
-- Read-only database queries
-- Model schema inspection
-- Custom business logic tools
+**Example Usage in Claude:**
+> "Analyze this code for safety: `User.delete_all`"
 
 ## Safety Features
 
@@ -329,114 +208,69 @@ User.where(active: true).count
 Post.includes(:comments).limit(10)
 ```
 
-## Rake Tasks
+## Architecture
 
-```bash
-# Check code safety
-rails rails_active_mcp:check_safety['User.count']
+### Built on Official MCP Ruby SDK
 
-# Execute code
-rails rails_active_mcp:execute['User.count']
+Rails Active MCP uses the official MCP Ruby SDK (`mcp` gem) for:
 
-# Test MCP tools
-rails rails_active_mcp:test_tools
+- **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
 
-# View configuration
-rails rails_active_mcp:config
+### Server Implementation
 
-# View audit log
-rails rails_active_mcp:audit_log[20]
+The server is implemented in `lib/rails_active_mcp/sdk/server.rb` and provides:
 
-# Clear audit log
-rails rails_active_mcp:clear_audit_log
-```
+- **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
 
-## Audit Logging
+### Tool Architecture
 
-All executions are logged to `log/rails_active_mcp.log`:
+Each tool is implemented as a separate class in `lib/rails_active_mcp/sdk/tools/`:
 
-```json
-{
-  "timestamp": "2025-01-15T10:30:00Z",
-  "code": "User.count",
-  "user": {
-    "environment": "development"
-  },
-  "safety_check": {
-    "safe": true,
-    "read_only": true,
-    "violations": []
-  }
-}
-```
+- `ConsoleExecuteTool`: Safe code execution
+- `ModelInfoTool`: Model introspection
+- `SafeQueryTool`: Read-only database access
+- `DryRunTool`: Code safety analysis
 
-## Environment-Specific Configuration
+## Error Handling
 
-### Production
+The gem provides specific error types:
 
-```ruby
-config.production_mode!
-# - Very strict safety checks
-# - Read-only replica execution
-# - Comprehensive logging
-# - No mutation tools
-```
+- `RailsActiveMcp::SafetyError`: Code failed safety checks
+- `RailsActiveMcp::TimeoutError`: Execution timed out
+- `RailsActiveMcp::ExecutionError`: General execution failure
 
-### Development
+All errors are properly reported through the MCP protocol with detailed messages.
 
-```ruby
-config.permissive_mode!
-# - Relaxed safety (but still protected)
-# - Mutation tools enabled
-# - Higher timeouts and limits
-```
+## Development and Testing
 
-### Testing
+### Running Tests
 
-```ruby
-config.strict_mode!
-# - Safe defaults
-# - No mutations
-# - Fast timeouts
+```bash
+$ bundle exec rspec
 ```
 
-## Custom MCP Server Architecture
-
-Rails Active MCP provides a custom-built MCP server implementation with no external dependencies. The server:
-
-- Implements the Model Context Protocol (MCP)
-- Uses JSON-RPC 2.0 over HTTP
-- Supports essential MCP methods:
-  - `initialize` - Server capabilities
-  - `tools/list` - Available tools
-  - `tools/call` - Execute tools
-  - `resources/list` and `resources/read` - Resource access
+### Testing MCP Integration
 
-### Server Implementation
+```bash
+$ ./bin/test-mcp-output
+```
 
-The core server is implemented in `lib/rails_active_mcp/mcp_server.rb` and follows Rack middleware conventions, making it easy to mount in Rails or run standalone.
+This tests the MCP server output redirection and JSON protocol compliance.
 
-### Extending the Server
+### Debugging
 
-You can add custom tools and resources to the server by extending the registration methods:
+Set the debug environment variable for detailed logging:
 
-```ruby
-# In an initializer or plugin
-RailsActiveMcp.server.instance_eval do
-  register_tool('my_custom_tool', 'Description', {...}) do |args|
-    # Tool implementation
-  end
-end
+```bash
+$ RAILS_MCP_DEBUG=1 bundle exec rails-active-mcp-server
 ```
 
-## Error Handling
-
-The gem provides specific error types:
-
-- `RailsActiveMcp::SafetyError`: Code failed safety checks
-- `RailsActiveMcp::TimeoutError`: Execution timed out
-- `RailsActiveMcp::ExecutionError`: General execution failure
-
 ## Contributing
 
 1. Fork it
@@ -447,28 +281,21 @@ The gem provides specific error types:
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Security
-
-This gem provides multiple layers of security, but always:
+The gem is available as open source under the [MIT License](https://opensource.org/licenses/MIT).
 
-- Review the configuration for your environment
-- Monitor the audit logs
-- Use read-only database replicas in production when possible
-- Restrict model access as needed
-- Test safety patterns thoroughly
-
-### Benefits of the Custom MCP Server
+## Changelog
 
-- **No External Dependencies**: Reduced attack surface with minimal dependencies
-- **Full Control**: Complete visibility into the server implementation
-- **Customizable Security**: Easily add additional security layers or checks
-- **Simplified Deployment**: No need to manage external MCP server dependencies
-- **Protocol Isolation**: MCP protocol implementation is self-contained and auditable
+### Version 2.0.0 (Latest)
 
-For security issues, please report using Github Issues.
+- **BREAKING**: Migrated to official MCP Ruby SDK
+- **BREAKING**: Removed custom MCP server implementation
+- **BREAKING**: Simplified configuration options
+- **NEW**: Professional protocol handling with built-in instrumentation
+- **NEW**: Automatic MCP specification compliance
+- **IMPROVED**: 85% reduction in codebase complexity
+- **IMPROVED**: Better error handling and reporting
+- **IMPROVED**: Future-proof architecture
 
-## Changelog
+### Previous Versions
 
-See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

data/changelog.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2025-01-15
+
+### Added
+
+- Official MCP Ruby SDK integration (`mcp` gem v0.1.0)
+- Professional protocol handling with built-in instrumentation
+- Automatic timing and error reporting
+- Standards-compliant MCP protocol implementation
+- Future-proof architecture with automatic SDK updates
+- Enhanced error handling and comprehensive reporting
+- Simplified tool names (removed `rails_` prefix)
+- Updated documentation reflecting new architecture
+
+### Changed
+
+- **BREAKING**: Migrated from custom MCP server to official MCP Ruby SDK
+- **BREAKING**: Simplified configuration options (removed complex server modes)
+- **BREAKING**: Tool names updated:
+  - `rails_console_execute` → `console_execute`
+  - `rails_model_info` → `model_info`
+  - `rails_safe_query` → `safe_query`
+  - `rails_dry_run` → `dry_run`
+- **BREAKING**: Removed HTTP server mode (STDIO only for Claude Desktop)
+- **BREAKING**: Removed feature flag system (SDK implementation only)
+- Server implementation moved to `lib/rails_active_mcp/sdk/server.rb`
+- Tool implementations moved to `lib/rails_active_mcp/sdk/tools/`
+- Updated README and documentation for new architecture
+
+### Removed
+
+- **BREAKING**: Custom MCP server implementation (799 lines of code)
+- **BREAKING**: Legacy tool implementations
+- **BREAKING**: Complex configuration options:
+  - `server_mode`, `server_host`, `server_port`
+  - `allowed_models`, `blocked_models`
+  - `enable_mutation_tools`
+  - Environment presets (`production_mode!`, `strict_mode!`, etc.)
+- **BREAKING**: HTTP server mode and Rails mounting
+- **BREAKING**: Feature flag system (`use_mcp_sdk`)
+- Legacy files:
+  - `lib/rails_active_mcp/mcp_server.rb`
+  - `lib/rails_active_mcp/stdio_server.rb`
+  - `lib/rails_active_mcp/application_mcp_tool.rb`
+  - `lib/rails_active_mcp/tool_registry.rb`
+  - `lib/rails_active_mcp/tools/` (legacy implementations)
+
+### Performance
+
+- 85% reduction in MCP protocol handling code
+- Improved protocol performance through official SDK
+- Better memory usage and resource management
+- Faster tool execution with reduced overhead
+
+### Security
+
+- Maintained all existing safety features
+- Enhanced error reporting without exposing internals
+- Professional protocol handling reduces attack surface
+- Continued comprehensive audit logging
+
+### Migration Guide
+
+For users upgrading from v1.x:
+
+1. Update your `config/initializers/rails_active_mcp.rb` to use the simplified configuration
+2. Update Claude Desktop configuration to remove any HTTP-specific settings
+3. Tool names in your MCP client integrations need to be updated (remove `rails_` prefix)
+4. The server now only supports STDIO mode (perfect for Claude Desktop)
+
 ## [0.1.0] - 2025-06-25
 
 ### Added

data/claude_desktop_config.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "rails-active-mcp": {
+      "command": "bin/rails-active-mcp-server",
+      "args": ["stdio"],
+      "cwd": "/Users/brandyn/Documents/development/ascend-health-plus",
+      "env": {
+        "RAILS_ENV": "development"
+      }
+    }
+  }
+}