christmas-mcp-copilot-runner/ENHANCED_SETUP_GUIDE.md

A Model Copilot Provider (MCP) for safely executing whitelisted system commands across platforms with automatic VS Code setup

# Enhanced npm Path Detection - Version 1.3.0

## Problem Solved 🎯

The main issue was that Windows and macOS/Linux have different npm global installation paths:

### macOS Example:
```json
"args": [
    "/Users/christmas/Desktop/projects/christmas-mcp-copilot-bypass/src/index.js",
    "--mcp"
]
```

### Windows Example:
```json
"args": [
    "C:\\Users\\chris\\AppData\\Roaming\\npm\\node_modules\\christmas-mcp-copilot-runner\\src\\index.js",
    "--mcp"
]
```

## Enhanced Solution 🚀

### 1. Comprehensive NPM Path Detection

The new setup system now detects multiple possible installation locations:

**For Windows:**
- `%USERPROFILE%\AppData\Roaming\npm\node_modules\christmas-mcp-copilot-runner`
- `C:\Program Files\nodejs\node_modules\christmas-mcp-copilot-runner`
- `C:\Program Files (x86)\nodejs\node_modules\christmas-mcp-copilot-runner`

**For macOS/Linux:**
- `/usr/local/lib/node_modules/christmas-mcp-copilot-runner`
- `~/.npm-global/lib/node_modules/christmas-mcp-copilot-runner`
- `/opt/homebrew/lib/node_modules/christmas-mcp-copilot-runner` (Apple Silicon Mac)

**Universal:**
- Uses `npm root -g` command to detect npm global root automatically
- Local development installations via `require.resolve()`
- Current directory fallback for development mode

### 2. Interactive Installation Selection

When users run the setup, they now get:

```
🔍 Detecting npm package installations...

📦 Found the following installations:
1. NPM Global Installation
   Path: C:\Users\chris\AppData\Roaming\npm\node_modules\christmas-mcp-copilot-runner\src\index.js
2. Local/Development Installation
   Path: /Users/christmas/Desktop/projects/christmas-mcp-copilot-runner/src/index.js

Select installation (1-2) or 0 for manual path: 1
```

### 3. Manual Path Entry Fallback

If automatic detection fails, users can manually enter the path:

```
❌ Could not find christmas-mcp-copilot-runner installation
Please enter the full path to christmas-mcp-copilot-runner/src/index.js: 
```

### 4. Cross-Platform Path Formatting

The system automatically formats paths correctly for the target OS:
- **Windows**: Converts `/` to `\\` and uses proper Windows path format
- **Unix/macOS**: Uses `/` separators and Unix path format

## Installation Flow 📋

1. **OS Detection**: "Detected OS: Windows. Is this correct? (y/n)"
2. **NPM Path Detection**: Scans for all possible installation locations
3. **Path Selection**: User chooses from detected installations or enters manual path
4. **Project Directory**: User selects where commands should execute from
5. **Configuration**: Creates properly formatted VS Code MCP configuration

## Benefits ✅

- ✅ **Automatic Detection**: Finds npm installations across all platforms
- ✅ **User Choice**: Multiple installation options with user selection
- ✅ **Fallback Support**: Manual path entry if auto-detection fails
- ✅ **Cross-Platform**: Proper path formatting for Windows/macOS/Linux
- ✅ **Validation**: Verifies paths exist before using them
- ✅ **Future-Proof**: Handles various npm installation scenarios

## Example Configurations Generated

### Windows Configuration:
```json
{
  "servers": [
    {
      "name": "christmas-mcp-copilot-runner",
      "command": "node",
      "args": [
        "C:\\Users\\chris\\AppData\\Roaming\\npm\\node_modules\\christmas-mcp-copilot-runner\\src\\index.js",
        "--mcp"
      ],
      "cwd": "C:\\Users\\chris\\Projects\\MyProject",
      "env": {},
      "disabled": false,
      "alwaysAllow": true
    }
  ]
}
```

### macOS Configuration:
```json
{
  "servers": [
    {
      "name": "christmas-mcp-copilot-runner",
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/christmas-mcp-copilot-runner/src/index.js",
        "--mcp"
      ],
      "cwd": "/Users/christmas/Projects/MyProject",
      "env": {},
      "disabled": false,
      "alwaysAllow": true
    }
  ]
}
```

This resolves the Windows compatibility issue completely while providing a robust, user-friendly setup experience across all platforms! 🎉