ez-mcp/README.md

A simple Model Context Protocol (MCP) server for executing command-line tools across different shell environments (WSL, PowerShell, CMD, Bash). Easy setup for Claude Desktop, GitHub Copilot, LM Studio, and Cursor.

# EZ-MCP: Easy Model Context Protocol Server

A simple yet powerful Model Context Protocol (MCP) server for executing command-line tools across different shell environments. Works seamlessly with Claude Desktop, GitHub Copilot, LM Studio, Cursor, and other AI tools.

## >>> Quick Start

### Installation & Setup (One Command!)

```bash
# Setup for Claude Desktop
npx ez-mcp setup claude

# Setup for GitHub Copilot (VS Code)
npx ez-mcp setup copilot

# Setup for LM Studio
npx ez-mcp setup lmstudio

# Setup for Cursor IDE
npx ez-mcp setup cursor
```

That's it! The setup automatically:
- [+] Downloads and configures the MCP server
- [+] Updates your AI tool's configuration
- [+] Preserves existing MCP servers
- [+] Works across Windows, Mac, and Linux

## [STRUCTURE] Project Structure

```
ez-mcp/
├── src/           # TypeScript source code
├── build/         # Compiled JavaScript files
├── scripts/       # Setup scripts for manual installation
│   ├── setup.bat  # Windows batch script
│   ├── setup.ps1  # PowerShell script
│   └── setup.sh   # Unix/Linux shell script
├── test/          # Test files
└── package.json   # NPM configuration
```

The setup scripts in the `scripts/` folder are provided for manual installation scenarios where `npx` might not be available.

## [TOOLS] Features

### [SYSTEM] **Multi-Shell Support**
Execute commands in any shell environment:
- **Windows**: PowerShell, CMD
- **Linux/WSL**: Bash, Zsh, Sh
- **WSL Integration**: Target specific distributions

### [SECURITY] **Military-Grade Security**
- **25+ Dangerous Command Patterns** detected
- **Absolute blocking** of destructive operations without confirmation
- **Smart warnings** with clear consequences
- **Audit logging** for security compliance

### [TARGET] **Windows Application Management**
- Launch any Windows application safely
- Command-line arguments support
- Working directory configuration
- Multiple launch methods

### [QUICK] **Developer-Friendly**
- **One-command setup** for popular AI tools
- **Cross-platform** compatibility
- **Zero configuration** for basic usage
- **Extensible** and maintainable

## [TOOLS] Available Tools

### 1. `execute_command`
Execute any command in your preferred shell environment.

```json
{
  "command": "ls -la",
  "shell": "bash",
  "workingDirectory": "/home/user/projects"
}
```

**Parameters:**
- `command` (required): The command to execute
- `shell` (optional): `wsl`, `powershell`, `cmd`, `bash`, `zsh`, `sh` (default: `powershell`)
- `workingDirectory` (optional): Working directory for command execution
- `timeout` (optional): Command timeout in milliseconds (default: 30000)
- `wslDistribution` (optional): Specific WSL distribution name
- `confirmed` (optional): Set to `true` for dangerous commands (see Security section)

### 2. `list_directory`
List contents of any directory across different shell environments.

```json
{
  "path": "/home/user/projects",
  "shell": "wsl"
}
```

### 3. `check_path`
Verify if a path exists and get detailed information.

```json
{
  "path": "C:\\Users\\username\\Documents",
  "shell": "powershell"
}
```

### 4. `open_windows_app`
Launch Windows applications with advanced options.

```json
{
  "app": "notepad",
  "arguments": "C:\\temp\\file.txt",
  "workingDirectory": "C:\\temp"
}
```

## [SECURE] Security Features

### [DANGER] **Dangerous Command Protection**

EZ-MCP automatically detects and blocks **25+ dangerous command patterns** to prevent accidental system damage:

#### [CRITICAL] **CRITICAL COMMANDS** (Require Confirmation)
- **Disk Operations**: `format`, `fdisk`, `diskpart`
- **Recursive Deletion**: `rm -rf /`, `del C:\*`, `rmdir /s`
- **System Control**: `shutdown`, `restart`, `reboot`
- **Registry**: `reg delete`, `regedit`
- **Process Control**: `taskkill /f`, `stop-process -force`
- **Container Ops**: `docker system prune -f`, `kubectl delete`
- **Git Destructive**: `git reset --hard`, `git clean -fd`
- **Database**: `drop database`, `truncate table`

#### [WARN] **Security Warning Example**
```
[DANGER] DANGEROUS COMMAND BLOCKED [DANGER]
[BLOCKED] EXECUTION REFUSED FOR SAFETY

[CRITICAL] DISK FORMATTING/PARTITIONING - PERMANENT DATA LOSS

[WARN] POTENTIAL CONSEQUENCES:
• Permanent data loss
• System corruption or instability  
• Complete system failure

[SECURITY] SECURITY REQUIREMENT:
This command will ONLY execute if you explicitly set "confirmed": true
```

#### [+] **Safe Override** (Use with EXTREME caution)
```json
{
  "command": "rm -rf /tmp/safe-to-delete",
  "confirmed": true
}
```

## [PACKAGE] Installation Methods

### Method 1: Quick Setup (Recommended)
```bash
# No installation needed - setup automatically downloads
npx ez-mcp setup claude
```

### Method 2: Global Installation
```bash
npm install -g ez-mcp
ez-mcp setup claude
```

### Method 3: Manual Setup Scripts
```bash
# Clone the repository
git clone https://github.com/thechandanbhagat/ez-mcp.git
cd ez-mcp

# Run platform-specific setup script
# Windows (Command Prompt)
scripts\setup.bat

# Windows (PowerShell)
scripts\setup.ps1

# Linux/Mac/WSL
chmod +x scripts/setup.sh
scripts/setup.sh
```

### Method 4: Manual MCP Configuration
```json
{
  "mcpServers": {
    "ez-mcp": {
      "command": "npx",
      "args": ["ez-mcp"]
    }
  }
}
```

## [TARGET] Use Cases

### [AI] **AI Assistant Integration**
- Execute system commands through Claude, Copilot, etc.
- File system operations and navigation  
- Development workflow automation
- System monitoring and diagnostics

### [DEV] **Development Workflows**
```json
// Build and test projects
{"command": "npm run build && npm test", "shell": "bash"}

// Git operations  
{"command": "git status && git log --oneline -5", "shell": "bash"}

// Cross-platform development
{"command": "ls -la", "shell": "wsl", "wslDistribution": "Ubuntu"}
```

### [TOOLS] **System Administration** 
```json
// Check system resources
{"command": "Get-Process | Sort-Object CPU -Desc | Select-Object -First 10", "shell": "powershell"}

// Monitor disk space
{"command": "df -h", "shell": "bash"}

// Network diagnostics
{"command": "ping -c 4 google.com", "shell": "bash"}
```

### [WINDOWS] **Windows App Management**
```json
// Launch applications
{"app": "code", "arguments": ".", "workingDirectory": "C:\\Projects"}

// Open system tools
{"app": "taskmgr", "method": "start"}

// Start with specific settings
{"app": "notepad++", "arguments": "file.txt", "waitForExit": true}
```

## [QUICK] Examples

### Basic Commands
```json
// List files
{"command": "ls -la", "shell": "bash"}

// Windows directory listing  
{"command": "dir", "shell": "cmd"}

// PowerShell processes
{"command": "Get-Process", "shell": "powershell"}
```

### Advanced Usage
```json
// WSL with specific distribution
{
  "command": "uname -a && lsb_release -a", 
  "shell": "wsl",
  "wslDistribution": "Ubuntu-20.04"
}

// Working directory execution
{
  "command": "npm install && npm start",
  "shell": "bash", 
  "workingDirectory": "/home/user/project",
  "timeout": 60000
}

// Windows app with arguments
{
  "app": "C:\\Program Files\\VSCode\\Code.exe",
  "arguments": "--new-window .",
  "workingDirectory": "C:\\Projects\\MyApp"
}
```

## [TOOLS] Configuration

### Supported AI Tools

| Tool | Status | Setup Command |
|------|--------|---------------|
| **Claude Desktop** | [+] Fully Supported | `npx ez-mcp setup claude` |
| **GitHub Copilot** | [+] VS Code Integration | `npx ez-mcp setup copilot` |
| **LM Studio** | [+] Local Models | `npx ez-mcp setup lmstudio` |
| **Cursor IDE** | [+] AI Code Editor | `npx ez-mcp setup cursor` |
| **Other MCP Clients** | [+] Manual Config | See manual setup below |

### Manual Configuration
```json
{
  "mcpServers": {
    "ez-mcp": {
      "command": "npx",
      "args": ["ez-mcp"]
    }
  }
}
```

## [DEBUG] Troubleshooting

### WSL Issues
```bash
# Check WSL status
wsl --list --verbose

# Install WSL if missing  
wsl --install

# Update WSL distribution
wsl --update
```

### Permission Errors
- **Windows**: Run terminal as Administrator for system operations
- **Linux/Mac**: Use `sudo` for privileged commands (with `confirmed: true`)
- **WSL**: Ensure WSL has proper permissions

### Command Timeouts
- Increase `timeout` parameter for long operations
- Use `&` for background processes in Unix shells
- Consider `Start-Job` for PowerShell background tasks

### Common Issues
| Issue | Solution |
|-------|----------|
| "Command not found" | Check PATH environment variable |
| "Access denied" | Run with appropriate permissions |
| "Shell not supported" | Use supported shell names |
| "WSL not available" | Install and configure WSL |

## [STATS] Performance

- **Lightweight**: ~10KB package size
- **Fast**: Direct shell execution, no overhead
- **Reliable**: Comprehensive error handling
- **Scalable**: Handles concurrent command execution

## [CONTRIB] Contributing

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** changes (`git commit -m 'Add amazing feature'`)
4. **Push** to branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request

### Development Setup
- `src/` - TypeScript source code
- `build/` - Compiled JavaScript (auto-generated)
- `scripts/` - Platform-specific setup scripts
- `test/` - Test files for validation

## [LICENSE] License

MIT License - see [LICENSE](LICENSE) file for details.

## [SUPPORT] Support

- **Issues**: [GitHub Issues](https://github.com/thechandanbhagat/ez-mcp/issues)
- **Documentation**: This README + inline help
- **Security**: Report security issues via GitHub Security tab

## >>> What's Next?

- **v1.1**: Enhanced logging and audit trails
- **v1.2**: Plugin system for custom commands  
- **v1.3**: Web UI for command management
- **v2.0**: Distributed execution and clustering

---

**[STAR] Star this repo if EZ-MCP helps your AI workflow!**