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

{
  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

{
  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

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

With Working Directory

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

With Environment Variables

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

With Timeout

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

With stdin Input

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

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

Shell Injection Prevention

// 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

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:

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