# 🚨 VS Code NPX Bug - Definitive Fix Guide

## The Persistent Problem

You're getting this **WRONG** configuration:
```json
"command": "npx",
"args": ["christmas-mcp-copilot-runner@1.4.5"]
```

Instead of this **CORRECT** configuration:
```json
"command": "node", 
"args": ["C:\\Users\\chris\\AppData\\Roaming\\npm\\node_modules\\christmas-mcp-copilot-runner\\src\\index.js"]
```

## 🔍 Why This Keeps Happening

1. **VS Code "Add Server..." UI Bug**: The UI always defaults to `npx` for npm packages
2. **No Setup Wizard**: VS Code doesn't show our interactive setup - it uses its broken default
3. **Configuration Override**: Even with our hints, VS Code ignores them and forces `npx`
4. **Platform Differences**: This bug is more severe on Windows than macOS/Linux

## ✅ DEFINITIVE SOLUTIONS (Choose One)

### Solution 1: Use Our New Configuration Wizard 🆕

**This completely bypasses the VS Code UI bug:**

```bash
# Install latest version
npm install -g christmas-mcp-copilot-runner@latest

# Run the FORCED configuration wizard
mcp-config-wizard
```

This wizard will:
- ✅ Detect your exact npm installation path
- ✅ Create the FORCED `"command": "node"` configuration
- ✅ Bypass all VS Code UI bugs
- ✅ Give you exactly what you need

### Solution 2: Windows Batch Script (Windows Only)

```cmd
# In your project directory
setup-windows.bat
```

This will create the **exact** configuration you need with your Windows paths.

### Solution 3: Manual Configuration (Last Resort)

1. **Close VS Code completely**
2. **Delete any existing MCP server configuration**
3. **Create `.vscode/settings.json` manually:**

```json
{
  "mcp.servers": {
    "christmas-mcp-copilot-runner": {
      "command": "node",
      "args": [
        "C:\\Users\\chris\\AppData\\Roaming\\npm\\node_modules\\christmas-mcp-copilot-runner\\src\\index.js"
      ],
      "cwd": "C:\\Your\\Project\\Directory",
      "env": {},
      "disabled": false,
      "alwaysAllow": true
    }
  },
  "languageModels.experimental": {
    "tools": {
      "enabled": true,
      "autoApprove": ["christmas-mcp-copilot-runner"]
    }
  }
}
```

4. **Save and restart VS Code**

## 🚨 CRITICAL: Never Use "Add Server..." UI

**The VS Code "Add Server..." button is BROKEN for npm packages.**

- ❌ It will always create `"command": "npx"`
- ❌ It ignores all our configuration hints
- ❌ It creates the wrong performance-killing configuration
- ❌ This is a known VS Code MCP extension bug

## 🔍 How to Find Your Exact Path

**Windows:**
```cmd
npm list -g christmas-mcp-copilot-runner
```

**Common Windows paths:**
- `C:\Users\{username}\AppData\Roaming\npm\node_modules\christmas-mcp-copilot-runner\src\index.js`
- `C:\Program Files\nodejs\node_modules\christmas-mcp-copilot-runner\src\index.js`

**Replace `{username}` with your actual Windows username.**

## 🧪 Test Your Configuration

After setup, you should see:
1. **Fast execution** (under 1 second)
2. **No "resolving package" messages**
3. **Direct command execution**

Test command: *"Use christmas-mcp-copilot-runner to run dir"*

## 🎯 Why Our Solution Works

- **Bypasses VS Code UI**: Never touches the broken "Add Server..." button
- **Forces Correct Paths**: Uses absolute file paths, not package names
- **Direct Node Execution**: No npm/npx overhead
- **Platform-Specific**: Handles Windows path differences correctly

## 📞 If You're Still Getting NPX

**This means:**
1. Someone used the "Add Server..." UI button (don't!)
2. VS Code cached the old configuration
3. The configuration wasn't properly overwritten

**Fix:**
1. **Delete ALL MCP server entries** from VS Code settings
2. **Close VS Code completely** (all windows)
3. **Run `mcp-config-wizard`** again
4. **Never touch the "Add Server..." UI**

## 🎉 Success Indicators

You'll know it's working when you see:
```json
"christmas-mcp-copilot-runner": {
  "command": "node",
  "args": ["C:\\Users\\chris\\AppData\\Roaming\\npm\\node_modules\\christmas-mcp-copilot-runner\\src\\index.js"]
}
```

**No more npx. No more performance issues. Just fast, direct execution.**