christmas-mcp-copilot-runner/INSTALLATION_WARNING.md

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

# ⚠️ IMPORTANT: Installation Method

## ✅ Recommended Installation (Automatic Node Setup)

```bash
npm install -g christmas-mcp-copilot-runner
```

This will:
1. ✅ Install the package globally
2. ✅ Automatically run setup with **"node"** command (recommended)
3. ✅ Configure proper npm paths for your OS
4. ✅ Set up auto-approval
5. ✅ Create optimized VS Code configuration

## ❌ Avoid: VS Code "Add Server..." UI

**DO NOT** use VS Code's "Add Server..." UI to add this package because:

- ❌ VS Code defaults to `"command": "npx"` 
- ❌ Uses `"args": ["christmas-mcp-copilot-runner@version"]`
- ❌ Slower startup times
- ❌ Potential version conflicts
- ❌ No proper working directory configuration

## ✅ Correct Configuration (Auto-Generated)

After running the npm install, you'll get:

### Windows:
```json
{
  "command": "node",
  "args": ["C:\\Users\\user\\AppData\\Roaming\\npm\\node_modules\\christmas-mcp-copilot-runner\\src\\index.js", "--mcp"],
  "cwd": "C:\\your\\project\\directory"
}
```

### macOS/Linux:
```json
{
  "command": "node", 
  "args": ["/usr/local/lib/node_modules/christmas-mcp-copilot-runner/src/index.js", "--mcp"],
  "cwd": "/your/project/directory"
}
```

## 🔧 Manual Setup (If Needed)

If the automatic setup fails:

```bash
mcp-setup-vscode
```

This will run the interactive setup again.

## 📝 Why Node vs NPX?

| Feature | Node (✅ Recommended) | NPX (⚠️ Avoid) |
|---------|---------------------|----------------|
| Startup Speed | ✅ Fast | ⚠️ Slow |
| Reliability | ✅ Direct execution | ⚠️ Package resolution |
| Performance | ✅ Optimized | ⚠️ Overhead |
| Path Config | ✅ Proper paths | ❌ Generic |
| Working Dir | ✅ Configurable | ⚠️ Limited |

## 🎯 Summary

**Always use the npm installation method** - it sets up everything correctly with the optimal "node" configuration!