Lupul-Augmentat/docs/tools/system-command.md

# System Command Tool

Execute system commands with comprehensive security controls and output handling.

## Overview

The SystemCommandTool allows controlled execution of whitelisted system commands with proper security boundaries, timeout handling, and output management.

## Input Schema

```typescript
{
  command: string;           // Command to execute (must be whitelisted)
  args?: string[];           // Command arguments
  cwd?: string;              // Working directory
  env?: Record<string, string>;  // Environment variables
  timeout?: number;          // Timeout in ms (100-300000, default: 30000)
  stdin?: string;            // Input to send to stdin
}
```

## Output Schema

```typescript
{
  stdout: string;            // Standard output
  stderr: string;            // Standard error output
  exitCode: number;          // Process exit code
  duration: number;          // Execution time in ms
}
```

## Whitelisted Commands

Only the following commands are allowed for security:

- `ls` - List directory contents
- `cat` - Display file contents
- `grep` - Search text patterns
- `find` - Find files and directories
- `echo` - Print text
- `pwd` - Print working directory
- `whoami` - Show current user
- `date` - Show current date/time
- `env` - Show environment variables
- `which` - Find command location
- `wc` - Word/line/character count
- `head` - Show first lines
- `tail` - Show last lines
- `sort` - Sort lines
- `uniq` - Remove duplicate lines
- `curl` - HTTP requests
- `ping` - Network connectivity test
- `dig` - DNS lookup
- `ps` - Process list
- `df` - Disk usage
- `du` - Directory size
- `uptime` - System uptime

## Security Features

### Command Validation
- Only whitelisted commands can be executed
- Shell operators (`|`, `&`, `;`, `>`, `<`, etc.) are blocked in arguments
- Prevents command injection attacks

### Resource Limits
- Configurable timeout (max 5 minutes)
- Output size limited to 1MB per stream
- Process is killed if limits exceeded

### Permission Control
- Requires `system:exec` permission
- Inherits process environment with modifications

## Example Usage

### Basic Command
```javascript
const result = await mcp.callTool('system_command', {
  command: 'ls',
  args: ['-la', '/tmp']
});
console.log(result.stdout);
```

### With Working Directory
```javascript
const result = await mcp.callTool('system_command', {
  command: 'grep',
  args: ['-r', 'TODO', '.'],
  cwd: '/home/user/project'
});
```

### With Environment Variables
```javascript
const result = await mcp.callTool('system_command', {
  command: 'echo',
  args: ['$MY_VAR'],
  env: {
    MY_VAR: 'Hello from environment!'
  }
});
```

### With Timeout
```javascript
const result = await mcp.callTool('system_command', {
  command: 'find',
  args: ['/', '-name', '*.log'],
  timeout: 5000  // 5 seconds
});
```

### With stdin Input
```javascript
const result = await mcp.callTool('system_command', {
  command: 'grep',
  args: ['error'],
  stdin: 'line 1\nerror on line 2\nline 3'
});
```

## Error Handling

### Command Not Allowed
```javascript
// This will throw an error
await mcp.callTool('system_command', {
  command: 'rm'  // Not in whitelist
});
// Error: Command not allowed: rm
```

### Shell Injection Prevention
```javascript
// This will throw an error
await mcp.callTool('system_command', {
  command: 'ls',
  args: ['; rm -rf /']  // Shell operators blocked
});
// Error: Shell characters not allowed in arguments
```

### Timeout Handling
```javascript
try {
  await mcp.callTool('system_command', {
    command: 'find',
    args: ['/'],
    timeout: 1000  // 1 second
  });
} catch (error) {
  // Error: Command timed out after 1000ms
}
```

### Non-Zero Exit Codes
Non-zero exit codes don't throw errors but are returned in the result:
```javascript
const result = await mcp.callTool('system_command', {
  command: 'grep',
  args: ['nonexistent', 'file.txt']
});
// result.exitCode will be 1 or 2
// result.stderr will contain the error message
```

## Best Practices

1. **Use specific commands** instead of shell scripts
2. **Set appropriate timeouts** for long-running commands
3. **Check exit codes** to handle command failures
4. **Limit output size** by using head/tail when appropriate
5. **Avoid user input** in command arguments without validation
6. **Use working directory** instead of cd commands
7. **Monitor stderr** for warnings and errors

## Limitations

- No shell features (pipes, redirects, wildcards)
- No interactive commands
- No sudo or privileged operations
- Output limited to 1MB per stream
- Maximum timeout of 5 minutes