# MCP Process Server
A Model Context Protocol (MCP) server that provides process management and monitoring capabilities for AI agents, with strict security boundaries enforced by executable allowlists and resource limits.
## 🔗 Repository
This package is now maintained in its own repository: **[https://github.com/Digital-Defiance/mcp-process](https://github.com/Digital-Defiance/mcp-process)**
This repository is part of the [AI Capabilities Suite](https://github.com/Digital-Defiance/ai-capabilities-suite) on GitHub.
## Table of Contents
- [Features](#features)
- [Security](#security)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [MCP Tools](#mcp-tools)
- [Usage Examples](#usage-examples)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [License](#license)
## Features
- **Process Launching**: Spawn processes with specified arguments and environment variables
- **Resource Monitoring**: Track CPU, memory, thread count, and I/O usage in real-time
- **Output Capture**: Capture and retrieve stdout and stderr streams separately
- **Process Termination**: Graceful (SIGTERM) and forced (SIGKILL) termination with timeout escalation
- **Service Management**: Long-running services with auto-restart and health checks
- **Process Groups**: Manage related processes and create pipelines
- **Timeout Management**: Automatic process termination after specified duration
- **I/O Management**: Send stdin input and retrieve buffered output
- **Security**: Multi-layer security with executable allowlists, argument validation, and resource limits
- **Audit Logging**: Complete operation tracking for security and compliance
## Security
This server implements defense-in-depth security with 6 layers of validation:
1. **Executable Allowlist**: Only pre-approved executables can be launched
2. **Argument Validation**: Command arguments validated for injection attacks
3. **Environment Sanitization**: Dangerous environment variables removed
4. **Resource Limits**: CPU, memory, and time limits prevent resource exhaustion
5. **Privilege Prevention**: No privilege escalation or setuid executables
6. **Audit Logging**: Complete operation tracking
See [SECURITY.md](./SECURITY.md) for detailed security implementation.
## Installation
### Docker (Recommended)
```bash
docker pull digitaldefiance/mcp-process:latest
```
See [DOCKER.md](./DOCKER.md) for detailed Docker usage instructions.
### NPM
```bash
npm install @ai-capabilities-suite/mcp-process
```
### Yarn
```bash
yarn add @ai-capabilities-suite/mcp-process
```
### Global Installation
```bash
npm install -g @ai-capabilities-suite/mcp-process
```
## Quick Start
### Docker Quick Start
```bash
# Pull the image
docker pull digitaldefiance/mcp-process:latest
# Create config directory
mkdir -p config
# Create configuration
cat > config/mcp-process-config.json << EOF
{
"allowedExecutables": ["node", "python3", "npm"],
"maxConcurrentProcesses": 5,
"enableAuditLog": true
}
EOF
# Run with docker-compose
docker-compose up -d
```
See [DOCKER.md](./DOCKER.md) for detailed Docker instructions.
### NPM Quick Start
#### 1. Create Configuration File
```bash
mcp-process --create-config ./mcp-process-config.json
```
This creates a sample configuration file with secure defaults.
### 2. Edit Configuration
Edit `mcp-process-config.json` to add your allowed executables:
```json
{
"allowedExecutables": ["node", "python3", "npm", "git"],
"defaultResourceLimits": {
"maxCpuPercent": 80,
"maxMemoryMB": 1024,
"maxCpuTime": 300
},
"maxConcurrentProcesses": 10,
"maxProcessLifetime": 3600,
"enableAuditLog": true,
"blockShellInterpreters": true,
"blockSetuidExecutables": true,
"allowProcessTermination": true,
"allowGroupTermination": true,
"allowForcedTermination": false,
"allowStdinInput": true,
"allowOutputCapture": true,
"requireConfirmation": false
}
```
### 3. Start the Server
```bash
mcp-process --config ./mcp-process-config.json
```
Or use environment variables:
```bash
export MCP_PROCESS_CONFIG_PATH=./mcp-process-config.json
mcp-process
```
### 4. Connect from Your AI Agent
Configure your AI agent (e.g., Kiro, Claude Desktop) to connect to the MCP server via stdio transport.
## Configuration
### Configuration File Locations
The server looks for configuration in the following order:
1. `--config` command line argument
2. `MCP_PROCESS_CONFIG_PATH` environment variable
3. `MCP_PROCESS_CONFIG` environment variable (JSON string)
4. `./mcp-process-config.json`
5. `./config/mcp-process.json`
### Configuration Options
See [SECURITY.md](./SECURITY.md) for detailed configuration options and security settings.
### Minimal Configuration
```json
{
"allowedExecutables": ["node", "python3"],
"defaultResourceLimits": {
"maxCpuPercent": 80,
"maxMemoryMB": 1024
},
"maxConcurrentProcesses": 10,
"maxProcessLifetime": 3600,
"enableAuditLog": true,
"blockShellInterpreters": true,
"blockSetuidExecutables": true,
"allowProcessTermination": true,
"allowGroupTermination": true,
"allowForcedTermination": false,
"allowStdinInput": true,
"allowOutputCapture": true,
"requireConfirmation": false
}
```
## MCP Tools
The server exposes 12 MCP tools for process management:
### process_start
Launch a new process.
**Parameters:**
- `executable` (string, required): Path to executable
- `args` (string[], optional): Command-line arguments
- `cwd` (string, optional): Working directory
- `env` (object, optional): Environment variables
- `timeout` (number, optional): Timeout in milliseconds
- `captureOutput` (boolean, optional): Whether to capture stdout/stderr
- `resourceLimits` (object, optional): Resource limits
**Returns:**
- `pid` (number): Process ID
- `startTime` (string): ISO timestamp of process start
### process_terminate
Terminate a process.
**Parameters:**
- `pid` (number, required): Process ID
- `force` (boolean, optional): Use SIGKILL instead of SIGTERM
- `timeout` (number, optional): Timeout for graceful termination (ms)
**Returns:**
- `exitCode` (number): Process exit code
- `terminationReason` (string): "graceful" or "forced"
### process_get_stats
Get process resource usage statistics.
**Parameters:**
- `pid` (number, required): Process ID
- `includeHistory` (boolean, optional): Include historical data
**Returns:**
- `cpuPercent` (number): CPU usage percentage
- `memoryMB` (number): Memory usage in MB
- `threadCount` (number): Number of threads
- `ioRead` (number): Bytes read
- `ioWrite` (number): Bytes written
- `uptime` (number): Process uptime in seconds
- `history` (array, optional): Historical statistics
### process_send_stdin
Send input to process stdin.
**Parameters:**
- `pid` (number, required): Process ID
- `data` (string, required): Data to send
- `encoding` (string, optional): Text encoding (default: "utf-8")
**Returns:**
- `bytesWritten` (number): Number of bytes written
### process_get_output
Get captured process output.
**Parameters:**
- `pid` (number, required): Process ID
- `stream` (string, optional): "stdout", "stderr", or "both" (default: "both")
- `encoding` (string, optional): Text encoding (default: "utf-8")
**Returns:**
- `stdout` (string): Captured stdout
- `stderr` (string): Captured stderr
- `stdoutBytes` (number): Stdout buffer size
- `stderrBytes` (number): Stderr buffer size
### process_list
List all managed processes.
**Returns:**
- Array of process information objects with PID, command, state, and uptime
### process_get_status
Get detailed process status.
**Parameters:**
- `pid` (number, required): Process ID
**Returns:**
- `state` (string): "running", "stopped", or "crashed"
- `uptime` (number): Process uptime in seconds
- `stats` (object): Current resource usage statistics
### process_create_group
Create a process group.
**Parameters:**
- `name` (string, required): Group name
- `pipeline` (boolean, optional): Whether to create a pipeline
**Returns:**
- `groupId` (string): Group identifier
### process_add_to_group
Add a process to a group.
**Parameters:**
- `groupId` (string, required): Group identifier
- `pid` (number, required): Process ID
### process_terminate_group
Terminate all processes in a group.
**Parameters:**
- `groupId` (string, required): Group identifier
### process_start_service
Start a long-running service with auto-restart.
**Parameters:**
- `name` (string, required): Service name
- `executable` (string, required): Path to executable
- `args` (string[], optional): Command-line arguments
- `cwd` (string, optional): Working directory
- `env` (object, optional): Environment variables
- `restartPolicy` (object, optional): Restart configuration
- `healthCheck` (object, optional): Health check configuration
**Returns:**
- `serviceId` (string): Service identifier
- `pid` (number): Initial process ID
### process_stop_service
Stop a service and disable auto-restart.
**Parameters:**
- `serviceId` (string, required): Service identifier
## Usage Examples
### Example 1: Run a Simple Command
```typescript
// Launch a process
const result = await mcpClient.callTool("process_start", {
executable: "node",
args: ["--version"],
captureOutput: true,
});
console.log("Process started:", result.pid);
// Wait a moment for it to complete
await new Promise((resolve) => setTimeout(resolve, 1000));
// Get output
const output = await mcpClient.callTool("process_get_output", {
pid: result.pid,
});
console.log("Output:", output.stdout);
```
### Example 2: Monitor Resource Usage
```typescript
// Start a process
const result = await mcpClient.callTool("process_start", {
executable: "python3",
args: ["my_script.py"],
resourceLimits: {
maxCpuPercent: 50,
maxMemoryMB: 512,
},
});
// Monitor resources
const stats = await mcpClient.callTool("process_get_stats", {
pid: result.pid,
includeHistory: true,
});
console.log("CPU:", stats.cpuPercent + "%");
console.log("Memory:", stats.memoryMB + "MB");
```
### Example 3: Interactive Process with Stdin
```typescript
// Start an interactive process
const result = await mcpClient.callTool("process_start", {
executable: "python3",
args: ["-i"],
captureOutput: true,
});
// Send input
await mcpClient.callTool("process_send_stdin", {
pid: result.pid,
data: 'print("Hello from AI agent")\n',
});
// Wait and get output
await new Promise((resolve) => setTimeout(resolve, 500));
const output = await mcpClient.callTool("process_get_output", {
pid: result.pid,
});
console.log("Output:", output.stdout);
```
### Example 4: Long-Running Service
```typescript
// Start a service with auto-restart
const service = await mcpClient.callTool("process_start_service", {
name: "my-api-server",
executable: "node",
args: ["server.js"],
restartPolicy: {
enabled: true,
maxRetries: 3,
backoffMs: 5000,
},
healthCheck: {
command: "curl http://localhost:3000/health",
interval: 30000,
timeout: 5000,
},
});
console.log("Service started:", service.serviceId);
```
### Example 5: Process Group Pipeline
```typescript
// Create a process group
const group = await mcpClient.callTool("process_create_group", {
name: "data-pipeline",
pipeline: true,
});
// Start first process
const proc1 = await mcpClient.callTool("process_start", {
executable: "cat",
args: ["data.txt"],
captureOutput: true,
});
// Add to group
await mcpClient.callTool("process_add_to_group", {
groupId: group.groupId,
pid: proc1.pid,
});
// Start second process (will receive output from first)
const proc2 = await mcpClient.callTool("process_start", {
executable: "grep",
args: ["pattern"],
captureOutput: true,
});
await mcpClient.callTool("process_add_to_group", {
groupId: group.groupId,
pid: proc2.pid,
});
```
## Troubleshooting
### Issue: "Executable not in allowlist"
**Cause:** The executable you're trying to launch is not in the `allowedExecutables` configuration.
**Solution:** Add the executable to your configuration file:
```json
{
"allowedExecutables": ["node", "python3", "/path/to/your/executable"]
}
```
You can use:
- Absolute paths: `/usr/bin/node`
- Basenames: `node`
- Glob patterns: `/usr/bin/*`
### Issue: "Shell interpreters are blocked"
**Cause:** You're trying to launch a shell (bash, sh, cmd.exe, etc.) and `blockShellInterpreters` is enabled.
**Solution:** Either:
1. Set `blockShellInterpreters: false` in your configuration (not recommended)
2. Launch the actual executable directly instead of through a shell
### Issue: "Process not found"
**Cause:** The process has already terminated or the PID is invalid.
**Solution:** Check if the process is still running using `process_list` or `process_get_status`.
### Issue: "CPU limit exceeded" or "Memory limit exceeded"
**Cause:** The process exceeded configured resource limits.
**Solution:** Increase resource limits in your configuration or when launching the process:
```json
{
"defaultResourceLimits": {
"maxCpuPercent": 90,
"maxMemoryMB": 2048
}
}
```
### Issue: "Maximum concurrent processes reached"
**Cause:** You've reached the `maxConcurrentProcesses` limit.
**Solution:**
1. Terminate some running processes
2. Increase `maxConcurrentProcesses` in your configuration
3. Wait for processes to complete
### Issue: "Process stdin not available"
**Cause:** The process stdin is closed or the process doesn't support stdin input.
**Solution:** Ensure the process is still running and was started with stdin enabled.
### Issue: Configuration file not found
**Cause:** The server can't find your configuration file.
**Solution:**
1. Use `--config` flag: `mcp-process --config /path/to/config.json`
2. Set environment variable: `export MCP_PROCESS_CONFIG_PATH=/path/to/config.json`
3. Place config at `./mcp-process-config.json`
### Debugging
Enable debug logging by setting the audit log level:
```json
{
"enableAuditLog": true,
"auditLogLevel": "debug"
}
```
Check the audit log for detailed information about process operations and security violations.
## Development
### Prerequisites
- Node.js >= 18.0.0
- npm >= 8.0.0
### Setup
```bash
# Clone the repository
git clone https://github.com/digital-defiance/ai-capabilities-suite.git
cd ai-capabilities-suite/packages/mcp-process
# Install dependencies
npm install
# Build
npm run build
```
### Testing
```bash
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in watch mode
npm run test:watch
# Run specific test file
npm test -- SecurityManager.spec.ts
```
### Linting
```bash
npm run lint
```
### Building
```bash
# Clean build directory
npm run clean
# Build TypeScript
npm run build
```
### Publishing
```bash
# Publish to npm (requires authentication)
npm run publish:public
```
## Architecture
The MCP Process Server consists of several core components:
- **MCPServer**: Main server implementing MCP protocol
- **SecurityManager**: Multi-layer security validation
- **ProcessLauncher**: Process spawning and configuration
- **ProcessManager**: Process lifecycle management
- **ResourceMonitor**: CPU, memory, and I/O monitoring
- **IOManager**: Stdin/stdout/stderr handling
- **ProcessTerminator**: Graceful and forced termination
- **ServiceManager**: Long-running service management
- **TimeoutManager**: Process timeout enforcement
- **ProcessGroup**: Process group and pipeline management
- **ConfigLoader**: Configuration file loading and validation
## Contributing
Contributions are welcome! Please see the main repository for contribution guidelines:
https://github.com/digital-defiance/ai-capabilities-suite
## License
MIT License - see [LICENSE](./LICENSE) file for details.
## Support
- GitHub Issues: https://github.com/digital-defiance/ai-capabilities-suite/issues
- Email: info@digitaldefiance.org
## Related Projects
- [MCP Filesystem](https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-filesystem) - Filesystem operations for AI agents
- [MCP Recording](https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-recording) - Session recording and playback
- [MCP Debugger](https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-debugger) - MCP protocol debugging tools
## Acknowledgments
Built with:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP protocol implementation
- [pidusage](https://github.com/soyuka/pidusage) - Process resource monitoring
- [which](https://github.com/npm/node-which) - Executable path resolution
- [minimatch](https://github.com/isaacs/minimatch) - Glob pattern matching