# Run Command MCP Server

A Model Context Protocol (MCP) server that provides command execution capabilities with both synchronous and asynchronous streaming support.

## Features
- **Synchronous Command Execution**: Run commands and wait for completion
- **Asynchronous Command Execution**: Start commands in background and monitor progress
- **Real-time Output Streaming**: Check command output while it's running
- **Process Management**: List, monitor, kill, and clean up processes
- **Timeout Support**: Automatically terminate long-running commands
- **Multiple Transport Modes**: 
  - **Stdio Transport**: Standard MCP communication via stdin/stdout
  - **HTTP Transport**: RESTful API with Server-Sent Events (SSE) support for real-time notifications
- **MCP Standard Compliance**: Fully compliant with MCP specifications
   
## Usage

### Stdio Transport (Default)

#### Claude Desktop
```json
{
  "mcpServers": {
    "run-command": {
      "command": "npx",
      "args": ["github:stilllovee/run-command-mcp"]
    }
  }
}
```

Or use locally after cloning:
```json
{
  "mcpServers": {
    "run-command": {
      "command": "node",
      "args": ["PATH_TO_YOUR_REPO/index.js"]
    }
  }
}
```

#### Github Copilot
```json
{
    "servers": {
        "run-command": {
            "type": "stdio",
            "command": "npx",
            "args": ["github:stilllovee/run-command-mcp"]
        },
    },
    "inputs": []
}
```

Or use locally after cloning:
```json
{
    "servers": {
        "run-command": {
            "type": "stdio",
            "command": "node",
            "args": ["PATH_TO_YOUR_REPO/index.js"]
        }
    },
    "inputs": []
}
```

### HTTP Transport (Streamable)

Start the HTTP server:

```bash
# Default port (8123)
npm run start:http

# Custom port
node http-server.js --port=3000
```

The server will be available at: `http://localhost:8123/mcp`

#### Github Copilot Configuration (HTTP)

```json
{
    "servers": {
        "run-command-http": {
            "type": "http",
            "url": "http://localhost:8123/mcp"
        }
    },
    "inputs": []
}
```

### Available Tools

#### `run_command`
Run a custom shell command synchronously and return the output (stdout, stderr, exit code). Blocks until command completes.

**Parameters:**
- `command` (required): The full command to execute (e.g., "echo hello world", "npm install", "git status")
- `timeout` (optional): Timeout in milliseconds (default: 30000)

**Example:**
```json
{
  "command": "echo hello world",
  "timeout": 5000
}
```

#### `start_command`
Start a command asynchronously (non-blocking). Returns a process_id to check status and output later.

**Parameters:**
- `command` (required): The full command to execute (e.g., "node server.js", "npm run dev")
- `timeout` (optional): Timeout in milliseconds. 0 means no timeout (default: 0)

**Example:**
```json
{
  "command": "node server.js",
  "timeout": 0
}
```

#### `get_command_output`
Get the current output and status of a running or completed async command by process_id.

**Parameters:**
- `process_id` (required): The process ID returned by start_command
- `tail` (optional): Only return the last N lines of output (0 = all)

**Example:**
```json
{
  "process_id": "550e8400-e29b-41d4-a716-446655440000",
  "tail": 10
}
```

#### `list_processes`
List all tracked processes (running, completed, failed, etc.)

**Parameters:**
- `status` (optional): Filter by status: running, completed, failed, killed, error, timed_out

**Example:**
```json
{
  "status": "running"
}
```

#### `kill_process`
Kill a running process by process_id

**Parameters:**
- `process_id` (required): The process ID to kill

**Example:**
```json
{
  "process_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### `clear_processes`
Clear finished processes from memory. If process_id is provided, clears that specific process. Otherwise clears all non-running processes.

**Parameters:**
- `process_id` (optional): Specific process ID to clear

**Example:**
```json
{
  "process_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

## Usage Examples

### Example 1: Run a simple synchronous command
```
User: Run "echo hello world"
AI: Uses run_command to execute and get immediate results
```

### Example 2: Start a long-running server
```
User: Start my Node.js server
AI: Uses start_command to start server in background
AI: Uses get_command_output to check if server started successfully
```

### Example 3: Monitor build progress
```
User: Build my project and show me the progress
AI: Uses start_command to start build
AI: Periodically uses get_command_output to check build logs
AI: Reports progress to user in real-time
```

### Example 4: Run Azure Functions locally
```
User: Start my Azure Functions app
AI: Uses start_command with "func start"
AI: Monitors output with get_command_output
AI: Shows compilation progress and when functions are ready
```

## Use Cases

- **Development Servers**: Start and monitor Node.js, Python, or other development servers asynchronously
- **Build Processes**: Run and monitor long build processes (webpack, tsc, etc.)
- **Testing**: Run test suites and monitor results
- **System Administration**: Execute system commands and check results
- **Log Monitoring**: Start services and continuously check their logs