christmas-mcp-copilot-runner/README.md

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

# 🎄 Christmas MCP Copilot Runner

A secure, cross-platform Model Context Protocol (MCP) server that allows GitHub Copilot to execute whitelisted system commands safely with **automatic VS Code setup and auto-approval**.

## 🚀 Quick Start (Automatic Setup)

### Installation with Auto-Setup

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

**That's it!** The package will automatically:
- ✅ Configure VS Code MCP integration
- ✅ Set up auto-approval for seamless command execution
- ✅ Create workspace configurations
- ✅ Enable GitHub Copilot tool integration

### Instant Usage

1. **Restart VS Code** (Cmd+Q/Ctrl+Q then reopen)
2. **Ask GitHub Copilot**: *"Use christmas-mcp-copilot-runner to run php test.php"*
3. **Watch it execute automatically** without approval prompts! 🎉

## 🚀 Features

- **Cross-Platform Support**: Works seamlessly on Windows, macOS, and Linux
- **Automatic Command Normalization**: Unix commands auto-convert to Windows equivalents
- **Safe Command Execution**: Only whitelisted base commands are allowed
- **Security First**: Blocks dangerous patterns across all platforms
- **Comprehensive Logging**: All commands are logged with timestamps to `logs/` directory
- **CLI Support**: Run commands manually via command line
- **MCP Integration**: Seamless integration with GitHub Copilot
- **Timeout Protection**: Commands timeout after 30 seconds
- **Error Handling**: Robust error handling and reporting

## 📦 Installation

### Global Installation (Recommended)

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

### Local Installation

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

## 🖥️ Platform Compatibility

### ✅ Windows
- **Supported Commands**: `cmd`, `powershell`, `dir`, `type`, `where`, `findstr`
- **Auto-normalization**: `ls` → `dir`, `cat` → `type`, `which` → `where`, `grep` → `findstr`
- **Shell Integration**: Uses Windows shell for proper command execution

### ✅ macOS / Linux
- **Supported Commands**: `ls`, `cat`, `which`, `grep`, and all standard Unix tools
- **Native Execution**: Commands run directly without modification

### 🔄 Command Normalization Examples
```bash
# These commands work on all platforms:
christmas-mcp-copilot-runner "ls -la"        # Unix/macOS: runs as-is, Windows: converts to "dir"
christmas-mcp-copilot-runner "cat file.txt"  # Unix/macOS: runs as-is, Windows: converts to "type file.txt"
christmas-mcp-copilot-runner "which node"    # Unix/macOS: runs as-is, Windows: converts to "where node"

## ⚙️ Configuration

### VS Code Integration

1. Create or update `.vscode/mcp.json` in your project root:

```json
{
  "mcps": [
    {
      "name": "christmas-mcp-copilot-runner",
      "command": "node",
      "args": [
        "node_modules/christmas-mcp-copilot-runner/src/index.js"
      ]
    }
  ]
}
```

**Alternative for global installation:**
```json
{
  "mcps": [
    {
      "name": "christmas-mcp-copilot-runner",
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/christmas-mcp-copilot-runner/src/index.js"
      ]
    }
  ]
}
```

2. Restart VS Code to load the MCP configuration.

### 🪟 Windows-Specific Setup

**Important**: Windows VS Code sometimes shows complex configuration wizards instead of simple direct execution. If you see a configuration with `"tool_uses"` and input prompts, that's WRONG!

**For Windows users, use our automatic setup script:**

1. Open Command Prompt in your project directory
2. Run the Windows setup script:
```cmd
setup-windows.bat
```

**Or manually create the correct configuration:**

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

📚 **See [WINDOWS_VS_CODE_FIX.md](./WINDOWS_VS_CODE_FIX.md) for detailed Windows troubleshooting.**

### GitHub Copilot Usage

Once configured, you can ask GitHub Copilot to run commands:

- "Run `php --version` using the MCP runner"
- "Execute `node app.js` safely"
- "Use MCP to run `curl -s https://api.github.com/users/github`"
- "Check git status with the command runner"

## 🖥️ CLI Usage

The package includes a `christmas-mcp-copilot-runner` CLI command for manual execution:

```bash
# Basic usage
christmas-mcp-copilot-runner "php --version"

# Cross-platform file listing
christmas-mcp-copilot-runner "ls -la"          # Works on all platforms

# Run Node.js applications
christmas-mcp-copilot-runner "node app.js"

# Make HTTP requests
christmas-mcp-copilot-runner "curl -s https://httpbin.org/ip"

# Git operations
christmas-mcp-copilot-runner "git status"

# File operations (cross-platform)
christmas-mcp-copilot-runner "cat package.json"  # Unix/macOS: cat, Windows: type

# Get help
christmas-mcp-copilot-runner --help

# Check version
christmas-mcp-copilot-runner --version
```

## 🖥️ Platform-Specific Usage

### Windows Users
```cmd
# Install globally
npm install -g christmas-mcp-copilot-runner

# Use PowerShell or CMD
christmas-mcp-copilot-runner "dir"
christmas-mcp-copilot-runner "type README.md"
christmas-mcp-copilot-runner "where node"

# Unix commands work too (auto-converted)
christmas-mcp-copilot-runner "ls"      # Converts to "dir"
christmas-mcp-copilot-runner "cat README.md"  # Converts to "type README.md"
```

### macOS Users
```bash
# Install globally
sudo npm install -g christmas-mcp-copilot-runner

# Use Terminal
christmas-mcp-copilot-runner "ls -la"
christmas-mcp-copilot-runner "cat package.json"
christmas-mcp-copilot-runner "which node"
```

### Linux Users
```bash
# Install globally
sudo npm install -g christmas-mcp-copilot-runner

# Use any shell
christmas-mcp-copilot-runner "ls -la"
christmas-mcp-copilot-runner "cat /etc/os-release"
christmas-mcp-copilot-runner "which python3"
```

## 🔒 Security Features

### Whitelisted Commands

The following base commands are allowed across all platforms:

**Universal Commands:**
- `php` - PHP interpreter
- `curl` - HTTP client  
- `node` - Node.js runtime
- `git` - Git version control
- `npm` / `yarn` - Package managers
- `python` / `python3` - Python interpreter
- `pip` / `pip3` - Python package manager
- `echo` - Display text
- `pwd` - Print working directory
- `whoami` - Current user
- `date` - Current date/time

**Unix/Linux/macOS Commands:**
- `ls` - List directory contents
- `cat` - Display file contents
- `which` - Locate commands
- `grep` - Text search
- `head` / `tail` - Display file beginning/end
- `wc` - Word/line/character count
- `sort` / `uniq` - Text processing
- `find` - Find files

**Windows Commands:**
- `dir` - List directory contents (Windows equivalent of `ls`)
- `type` - Display file contents (Windows equivalent of `cat`)
- `where` - Locate commands (Windows equivalent of `which`)
- `findstr` - Text search (Windows equivalent of `grep`)
- `cmd` - Command prompt
- `powershell` - PowerShell

**Auto-Normalization:** Unix commands like `ls`, `cat`, `which`, `grep` are automatically converted to their Windows equivalents (`dir`, `type`, `where`, `findstr`) when running on Windows.

### Blocked Patterns

The following dangerous patterns are automatically rejected on all platforms:

**Unix/Linux/macOS Dangerous Commands:**
- `rm -rf` or `rm --recursive` - Recursive file deletion
- `sudo` - Superuser commands
- `chmod 777` - Dangerous permissions

**Windows Dangerous Commands:**
- `del /s` - Recursive file deletion
- `rmdir /s` - Recursive directory deletion
- `format` - Drive formatting
- `diskpart` - Disk partitioning
- `Remove-Item -Recurse` - PowerShell recursive deletion

**Cross-Platform Dangerous Patterns:**
- `>` - File redirection
- `|` - Pipe operations
- `&&` - Command chaining
- `;` - Command separation
- Backticks and `$()` - Command substitution
- `eval`, `exec`, `system` - Code evaluation

## 📊 Logging

All command executions are logged to the `logs/` directory:

- **File Format**: `commands-YYYY-MM-DD.log`
- **Content**: JSON entries with timestamp, command, result, and success status
- **Size Limit**: Results are truncated to 1000 characters in logs

Example log entry:
```json
{
  "timestamp": "2025-01-15T10:30:45.123Z",
  "command": "php --version",
  "success": true,
  "result": "PHP 8.1.0 (cli)...",
  "pid": 12345
}
```

## 🔧 API Usage

You can also use the runner programmatically:

```javascript
const { runCommand } = require('christmas-mcp-copilot-runner/src/handlers/runCommand');

async function example() {
  const result = await runCommand({ cmd: 'node --version' });
  
  if (result.success) {
    console.log('Output:', result.output);
    console.log('Platform:', result.platform);
    console.log('Normalized Command:', result.normalizedCommand);
  } else {
    console.error('Error:', result.error);
  }
}
```

## 🧪 Testing

Start the development server:

```bash
npm start
```

The server runs on port 3000 by default. Test endpoints:

- Health check: `GET http://localhost:3000/health`
- Available commands: `GET http://localhost:3000/commands`
- Execute command: `POST http://localhost:3000/` with JSON body:
  ```json
  {
    "command": "runCommand",
    "params": {
      "cmd": "php --version"
    }
  }
  ```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details.

## 🐛 Issues & Support

Report issues on [GitHub Issues](https://github.com/christmas/christmas-mcp-copilot-runner/issues).

## 🔄 Changelog

### v1.0.3
- **Enhanced**: Implemented proper JSON-RPC 2.0 protocol for MCP server
- **Fixed**: VS Code MCP integration with correct JSON-RPC initialize, tools/list, and tools/call methods
- **Improved**: Server logging now uses stderr to avoid interfering with JSON-RPC communication
- **Added**: Comprehensive VS Code setup guide (VSCODE_SETUP_GUIDE.md)
- **Updated**: MCP server now properly handles multiple JSON-RPC messages and buffering

### v1.0.2
- **Fixed**: VS Code MCP integration - updated configuration to use correct server entry point
- **Improved**: Added proper MCP JSON-RPC server mode to main index.js
- **Updated**: Documentation with correct VS Code configuration examples

### v1.0.1
- **Changed**: CLI command from `christmas-mcp` to `christmas-mcp-copilot-runner` to avoid conflicts
- **Updated**: All documentation and examples to reflect new command name

### v1.0.0
- Initial release
- Cross-platform support (Windows, macOS, Linux)
- Automatic command normalization
- Basic command execution with whitelist
- Security pattern blocking for all platforms
- Comprehensive logging
- CLI interface
- MCP integration
- VS Code configuration support