🎄 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

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)

npm install -g christmas-mcp-copilot-runner

Local Installation

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

# 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:

{
  "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:

setup-windows.bat

Or manually create the correct configuration:

{
  "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 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:

# 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

# 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

# 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

# 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:

{
  "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:

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:

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:

  {
    "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.

🔄 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