rails-active-mcp 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b477f00244c6b1b3370cc65295e401e4976d2c793e6d7344350866f5a21156eb
-  data.tar.gz: 38f43074ef26d934177dbd4a169efcd2f4b7c5cccac8b276e4927de7e5cca4cd
+  metadata.gz: 4af3c8128e9aa1ec5387c9c8ea90ff709e81287e8f9026b3a6ac1930e0f62204
+  data.tar.gz: 257ab1dd963dd7c377bc69f4a2a934d80eaa21e22e43567d551d729612b12712
 SHA512:
-  metadata.gz: de2f7f0d0d4a2122dc2e83da7f3d3e9da08fc0d94ea93c61cf63fa2f4861695624c30da605ada7ff81f6a50dd8698b211f7b01bd54c128815d851f812e622d12
-  data.tar.gz: de6ce9166bb2da50fc492a784bac432e632d0d26dec52c1c506a49038d99c05dfe042819b67b70c98ff2371a3d0f1fc1e042f32ba48fc0470023ed0f011be3cd
+  metadata.gz: a30335d0e827dfaad9a4cfda26582ecd8c79cf0c4aab1fc9695df5e46145da4009d5228211a5cd26e4cca25f9417a9420793a10c5224068bac0297a69e0980ea
+  data.tar.gz: b73993876ec57ab0ce758ed79aa50b1e0c71f3b12963c39a4170de8a5e80eb3f2f0ccd6a17d88c36e07d71badcc652ddcc373fbb1cdeaabedd0d45d300cd047b

data/app/controllers/rails_active_mcp/mcp_controller.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RailsActiveMcp
+  class McpController < ApplicationController
+    protect_from_forgery with: :null_session
+    before_action :check_enabled
+    before_action :set_cors_headers
+
+    def handle
+      return head :method_not_allowed unless request.post?
+      return head :bad_request unless json_request?
+
+      begin
+        body = request.body.read
+        data = JSON.parse(body)
+
+        mcp_server = RailsActiveMcp::McpServer.new
+        response_data = mcp_server.handle_jsonrpc_request(data)
+
+        render json: response_data
+      rescue JSON::ParserError
+        render json: { error: 'Invalid JSON' }, status: :bad_request
+      rescue StandardError => e
+        RailsActiveMcp.logger.error "MCP Controller Error: #{e.message}"
+        render json: { error: 'Internal Server Error' }, status: :internal_server_error
+      end
+    end
+
+    def sse
+      response.headers['Content-Type'] = 'text/event-stream'
+      response.headers['Cache-Control'] = 'no-cache, no-store, must-revalidate'
+      response.headers['Connection'] = 'keep-alive'
+      response.headers['X-Accel-Buffering'] = 'no'
+
+      # Send initial connection established event
+      render plain: ": SSE connection established\n\nevent: endpoint\ndata: #{request.base_url}#{rails_active_mcp.root_path}messages\n\nretry: 100\n\n"
+    end
+
+    def health
+      status = RailsActiveMcp.config.enabled ? 'healthy' : 'disabled'
+      render json: {
+        status: status,
+        version: RailsActiveMcp::VERSION,
+        timestamp: Time.current.iso8601
+      }
+    end
+
+    def info
+      render json: {
+        name: 'Rails Active MCP',
+        version: RailsActiveMcp::VERSION,
+        description: 'Rails Console access via Model Context Protocol (MCP)',
+        endpoints: {
+          mcp: rails_active_mcp.root_path,
+          health: rails_active_mcp.root_path + 'health'
+        },
+        enabled: RailsActiveMcp.config.enabled
+      }
+    end
+
+    private
+
+    def check_enabled
+      return if RailsActiveMcp.config.enabled
+
+      render json: { error: 'Rails Active MCP is disabled' }, status: :service_unavailable
+    end
+
+    def json_request?
+      request.content_type&.include?('application/json')
+    end
+
+    def set_cors_headers
+      response.headers['Access-Control-Allow-Origin'] = '*'
+      response.headers['Access-Control-Allow-Methods'] = 'GET, POST, OPTIONS'
+      response.headers['Access-Control-Allow-Headers'] = 'Content-Type'
+      response.headers['Access-Control-Max-Age'] = '86400'
+    end
+  end
+end

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"
+      }
+    }
+  }
+} 

data/docs/DEBUGGING.md

@@ -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.
 

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/exe/rails-active-mcp-server

@@ -4,20 +4,52 @@
 require 'rack'
 require 'json'
 require 'stringio'
+
+# Suppress ALL output immediately when not in debug mode to prevent MCP JSON protocol interference
+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
+end
+
+# Initialize Rails environment if available (from current working directory)
+rails_loaded = false
+if File.exist?('config/environment.rb')
+  begin
+    require './config/environment'
+    rails_loaded = true
+  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']
+  end
+end
+
+# Restore stdout/stderr after Rails loading for non-debug stdio mode
+if ARGV.first == 'stdio' && !ENV['RAILS_MCP_DEBUG']
+  $stdout = original_stdout
+  $stderr = original_stderr
+end
+
+# Now load the gem
 require_relative '../lib/rails_active_mcp'
 
-# Parse command line options with config defaults
-default_mode = if defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config)
+# 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 defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config)
+default_port = if rails_loaded && defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config)
                  RailsActiveMcp.config.server_port
                else
                  3001
                end
-default_host = if defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config)
+default_host = if rails_loaded && defined?(RailsActiveMcp) && RailsActiveMcp.respond_to?(:config)
                  RailsActiveMcp.config.server_host
                else
                  'localhost'
@@ -33,30 +65,29 @@ when 'stdio'
   require_relative '../lib/rails_active_mcp/stdio_server'
 
   begin
-    # Initialize Rails environment if available (from current working directory)
-    if File.exist?('config/environment.rb')
-      # Suppress Rails output to avoid interfering with MCP JSON protocol
-      original_stdout = $stdout
-      $stdout = StringIO.new
-
-      begin
-        require './config/environment'
-      rescue StandardError => e
-        # Log to stderr but don't fail - the server can work without Rails
-        warn "Warning: Could not load Rails environment: #{e.message}"
-      ensure
-        $stdout = original_stdout
-      end
+    # 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
     end
 
     stdio_server = RailsActiveMcp::StdioServer.new
-    stdio_server.run
+    stdio_server.start
   rescue Interrupt
     exit(0)
   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'
 
@@ -81,6 +112,9 @@ when 'http'
 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 (default)'
+  puts '  http:  For HTTP-based integrations'
+  puts ''
+  puts 'Environment variables:'
+  puts '  RAILS_MCP_DEBUG=1  Enable debug logging'
   exit(1)
 end

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

@@ -11,8 +11,106 @@ module RailsActiveMcp
         template 'initializer.rb', 'config/initializers/rails_active_mcp.rb'
       end
 
+      def create_binstub
+        # Create binstub for easy server execution
+        create_file 'bin/rails-active-mcp-server', <<~RUBY
+          #!/usr/bin/env ruby
+
+          # Binstub for Rails Active MCP Server
+          # This ensures the server runs within the Rails project context
+
+          require 'bundler/setup'
+          require 'stringio'
+
+          # Set Rails environment
+          ENV['RAILS_ENV'] ||= 'development'
+
+          # Suppress Rails loading output for MCP JSON protocol
+          unless ENV['RAILS_MCP_DEBUG'] == '1'
+            original_stdout = $stdout
+            original_stderr = $stderr
+            $stdout = StringIO.new
+            $stderr = StringIO.new
+          end
+
+          # Load Rails application
+          require_relative '../config/environment'
+
+          # Restore output streams
+          unless ENV['RAILS_MCP_DEBUG'] == '1'
+            $stdout = original_stdout
+            $stderr = original_stderr
+          end
+
+          # Now run the actual MCP server
+          load Gem.bin_path('rails_active_mcp', 'rails-active-mcp-server')
+        RUBY
+
+        chmod 'bin/rails-active-mcp-server', 0o755
+        say 'Created Rails binstub at bin/rails-active-mcp-server', :green
+
+        # Create environment-aware wrapper for Claude Desktop compatibility
+        ruby_path = `which ruby`.strip
+
+        create_file 'bin/rails-active-mcp-wrapper', <<~BASH
+          #!/usr/bin/env bash
+
+          # Rails Active MCP Wrapper Script
+          # Ensures correct Ruby environment for Claude Desktop execution
+          # Research-based solution for version manager compatibility
+
+          # Fix Claude Desktop environment isolation issues
+          export HOME="${HOME:-#{ENV['HOME']}}"
+          export USER="${USER:-$(whoami)}"
+
+          # Strategy 1: Use absolute Ruby path (most reliable)
+          RUBY_PATH="#{ruby_path}"
+
+          # Strategy 2: Try /usr/local/bin/ruby symlink as fallback
+          if [ ! -x "$RUBY_PATH" ]; then
+              RUBY_PATH="/usr/local/bin/ruby"
+          fi
+
+          # Strategy 3: Setup environment and use PATH resolution as last resort
+          if [ ! -x "$RUBY_PATH" ]; then
+              # Set up asdf environment if available
+              export ASDF_DIR="$HOME/.asdf"
+              if [ -f "$ASDF_DIR/asdf.sh" ]; then
+                  source "$ASDF_DIR/asdf.sh"
+              fi
+          #{'    '}
+              # Add version manager paths
+              export PATH="$HOME/.asdf/shims:$HOME/.rbenv/shims:$HOME/.rvm/bin:$PATH"
+              RUBY_PATH="ruby"
+          fi
+
+          # Change to the Rails project directory
+          cd "$(dirname "$0")/.."
+
+          # Execute with the determined Ruby path
+          exec "$RUBY_PATH" bin/rails-active-mcp-server "$@"
+        BASH
+
+        chmod 'bin/rails-active-mcp-wrapper', 0o755
+        say 'Created environment wrapper at bin/rails-active-mcp-wrapper', :green
+      end
+
       def create_mcp_route
-        route "mount RailsActiveMcp::McpServer.new, at: '/mcp' # Rails Active MCP"
+        # Check if routes file exists and is writable
+        routes_file = 'config/routes.rb'
+        return unless File.exist?(routes_file)
+
+        # Read current routes to check for conflicts
+        routes_content = File.read(routes_file)
+
+        if routes_content.include?('/mcp')
+          say "Warning: Route '/mcp' already exists. Skipping route creation.", :yellow
+          say "Manual setup: Add 'mount RailsActiveMcp::Engine, at: \"/mcp\"' to your routes.rb", :yellow
+        else
+          # Use Engine mounting instead of direct server mounting
+          route "mount RailsActiveMcp::Engine, at: '/mcp'"
+          say "Added MCP route at '/mcp'. You can change this in config/routes.rb", :green
+        end
       end
 
       def create_mcp_config
@@ -23,6 +121,48 @@ module RailsActiveMcp
         readme 'README.md' if behavior == :invoke
       end
 
+      def show_post_install_instructions
+        return unless behavior == :invoke
+
+        say "\n" + '=' * 50, :green
+        say 'Rails Active MCP Installation Complete!', :green
+        say '=' * 50, :green
+        say "\nFor Claude Desktop configuration:", :green
+        say 'Add this to your claude_desktop_config.json:', :yellow
+        say '', :green
+        say '{', :cyan
+        say '  "mcpServers": {', :cyan
+        say '    "rails-active-mcp": {', :cyan
+        say "      \"command\": \"#{Rails.root}/bin/rails-active-mcp-wrapper\",", :cyan
+        say '      "args": ["stdio"],', :cyan
+        say "      \"cwd\": \"#{Rails.root}\",", :cyan
+        say '      "env": {', :cyan
+        say '        "RAILS_ENV": "development",', :cyan
+        say "        \"HOME\": \"#{ENV['HOME']}\"", :cyan
+        say '      }', :cyan
+        say '    }', :cyan
+        say '  }', :cyan
+        say '}', :cyan
+        say '', :green
+        say "\nWhy use the wrapper?", :green
+        say '- Handles Ruby version manager environments (asdf, rbenv, etc.)', :yellow
+        say '- Prevents "bundler version" and "Ruby version" conflicts', :yellow
+        say '- Works reliably across different development setups', :yellow
+        say "\nAlternative (if wrapper doesn't work):", :green
+        say 'Use bin/rails-active-mcp-server instead of the wrapper', :yellow
+        say "\nTesting:", :green
+        say '1. Test manually: bin/rails-active-mcp-wrapper stdio', :yellow
+        say '2. Should output JSON (not plain text)', :yellow
+        say '3. Restart Claude Desktop after config changes', :yellow
+        say "\nTroubleshooting:", :green
+        say '- Set RAILS_MCP_DEBUG=1 for verbose logging', :yellow
+        say '- Check README.md for more configuration options', :yellow
+        say "\nFor Ruby version manager users (asdf/rbenv/RVM):", :green
+        say 'If you encounter "bundler version" errors, create a system symlink:', :yellow
+        say "sudo ln -sf #{`which ruby`.strip} /usr/local/bin/ruby", :cyan
+        say '=' * 50, :green
+      end
+
       private
 
       def readme(path)
@@ -30,7 +170,7 @@ module RailsActiveMcp
         if File.exist?(readme_path)
           say IO.read(readme_path), :green
         else
-          say "README file not found at #{readme_path}", :yellow
+          say "README file not found at #{readme_path}", :green
         end
       rescue StandardError => e
         say "Error reading README: #{e.message}", :red

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

@@ -40,9 +40,13 @@ Next Steps:
    {
      "mcpServers": {
        "rails-active-mcp": {
-         "command": "bundle",
-         "args": ["exec", "rails-active-mcp-server", "stdio"],
-         "cwd": "/path/to/your/rails/project"
+         "command": "<%= Rails.root %>/bin/rails-active-mcp-wrapper",
+         "args": ["stdio"],
+         "cwd": "<%= Rails.root %>", 
+         "env": {
+           "RAILS_ENV": "development",
+           "HOME": "/Users/your-username"
+         }
        }
      }
    }
@@ -137,11 +141,47 @@ $ tail -f ~/Library/Logs/Claude/mcp*.log  # macOS
 $ tail -f ~/.config/claude-desktop/logs/*.log  # Linux
 
 Common issues:
-- Ensure your Rails environment loads properly in the project directory
-- Check that the gem is properly installed and configured  
-- Verify the Rails application starts without errors
-- Make sure the cwd path in Claude Desktop config is correct
-- Enable debug logging with RAILS_MCP_DEBUG=1 for detailed output
+
+1. Ruby Version Manager Conflicts (Most Common Issue):
+   If you see errors like "Could not find 'bundler' (X.X.X)" or "Your Ruby version is X.X.X, but your Gemfile specified Y.Y.Y":
+   
+   This happens because Claude Desktop uses system Ruby instead of your project's Ruby version.
+   
+   Solution A - Use the wrapper script (Recommended):
+   In claude_desktop_config.json, use:
+   "command": "<%= Rails.root %>/bin/rails-active-mcp-wrapper"
+   
+   Solution B - Create system symlink:
+   $ sudo ln -sf $(which ruby) /usr/local/bin/ruby
+   
+   Solution C - Use absolute Ruby path:
+   In claude_desktop_config.json, change "command" to your full Ruby path:
+   "command": "$(which ruby)"
+   "args": ["<%= Rails.root %>/bin/rails-active-mcp-server", "stdio"]
+
+2. Environment Variable Issues:
+   If you see "error loading config: $HOME is not defined":
+   
+   This happens because Claude Desktop doesn't inherit all environment variables.
+   
+   Solution: Add HOME to your env section in claude_desktop_config.json:
+   "env": {
+     "RAILS_ENV": "development",
+     "HOME": "/Users/your-username"
+   }
+
+3. General Environment Issues:
+   - Ensure your Rails environment loads properly in the project directory
+   - Check that the gem is properly installed and configured  
+   - Verify the Rails application starts without errors
+   - Make sure the cwd path in Claude Desktop config is correct
+
+4. Debug Steps:
+   - Test manually: $ ./bin/rails-active-mcp-wrapper stdio
+   - Should output JSON (not plain text)
+   - Enable debug logging with RAILS_MCP_DEBUG=1 for detailed output
+   - Check Claude logs: $ tail -f ~/Library/Logs/Claude/mcp*.log
+   - Test environment variables: $ echo $HOME (should show your home directory)
 
 For more information: https://github.com/goodpie/rails-active-mcp