digitaldefiance/mcp-process

MCP ACS 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

This repository is part of the https://github.com/Digital-Defiance/ai-capabilities-suite on GitHub.

Table of Contents

• Features
• Security
• Installation
• Quick Start
• Configuration
• MCP Tools
• Usage Examples
• Troubleshooting
• Development
• 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 ***s
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 for detailed security implementation.

Installation

Docker (Recommended)

bash
docker pull digitaldefiance/mcp-process:latest

See 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 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 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 (unit, integration, and e2e)
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

# Run only e2e tests
npm run test:e2e

# Run minimal e2e smoke tests (quick validation)
npm run test:e2e:minimal

End-to-End (E2E) Testing

The MCP ACS Process Server includes comprehensive e2e tests that validate the complete system behavior by spawning the server as a child process and communicating via stdio using JSON-RPC protocol. These tests ensure the server works correctly in real-world usage scenarios.

E2E Test Structure:

• server.e2e.spec.ts - Comprehensive e2e tests covering all MCP tools and protocol features
• server.minimal.e2e.spec.ts - Quick smoke tests for basic functionality validation (< 30 seconds)

Running E2E Tests:

bash
# Run comprehensive e2e tests
npm run test:e2e

# Run minimal smoke tests for quick feedback
npm run test:e2e:minimal

# Run e2e tests with specific pattern
npm test -- --testPathPattern=e2e.spec.ts

# Run e2e tests with verbose output
npm test -- --testPathPattern=e2e.spec.ts --verbose

What E2E Tests Validate:

• MCP protocol initialization and handshake
• Tool discovery via tools/list
• Process launch operations with security enforcement
• Process monitoring and resource statistics
• Process termination (graceful and forced)
• Output capture (stdout/stderr)
• Service management with auto-restart
• Error handling and validation
• Security policy enforcement
• Resource limit enforcement
• Timeout handling
• JSON-RPC protocol compliance

E2E Test Requirements:

1. The server must be built before running e2e tests: npm run build
2. Tests spawn the server from dist/cli.js
3. Tests communicate via stdio using JSON-RPC 2.0 protocol
4. All spawned processes are cleaned up after tests complete

Debugging E2E Test Failures:

If e2e tests fail, follow these steps:

1. Ensure the server is built:

   bash
   npm run build
   

2. Check if the CLI exists:

   bash
   ls -la dist/cli.js
   

3. Run tests with verbose output:

   bash
   npm test -- --testPathPattern=e2e.spec.ts --verbose
   

4. Check for server startup errors:

   • E2E tests capture server stderr output
   • Look for error messages in test output
   • Common issues: missing dependencies, permission errors, port conflicts

5. Verify server can start manually:

   bash
   node dist/cli.js --help
   

6. Run minimal tests first:

   bash
   npm run test:e2e:minimal
   

   If minimal tests pass but comprehensive tests fail, the issue is likely with specific functionality rather than basic server operation.

7. Check process cleanup:

   bash
   # List any orphaned node processes
   ps aux | grep node
   

8. Enable debug logging: Set DEBUG=* environment variable to see detailed logs:

   bash
   DEBUG=* npm test -- --testPathPattern=e2e.spec.ts
   

Common E2E Test Issues:

**CI Environment *ations:

E2E tests are designed to run in CI environments with the following ***ations:

• Headless operation: No display server required
• Timeout adjustments: CI environments get 50% longer timeouts
• Process cleanup: All processes cleaned up even on test failure
• No interactive input: Tests run fully automated
• Resource constraints: Tests handle slower CI environments gracefully

CI Configuration Example:

yaml
# .github/workflows/test.yml
- name: Build
  run: npm run build

- name: Run minimal e2e tests
  run: npm run test:e2e:minimal

- name: Run full test suite
  run: npm test
  env:
    CI: true

Property-Based Testing:

E2E tests include property-based tests using fast-check to validate universal properties:

• JSON-RPC request/response ID matching
• Concurrent request handling
• Process launch with random allowed executables
• Security rejection for blocked executables

These tests run multiple iterations with randomly generated inputs to ensure correctness across a wide range of scenarios.

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 ACS 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 file for details.

Support

• GitHub Issues: https://github.com/digital-defiance/ai-capabilities-suite/issues
• *** <***>

Related Projects

• https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-filesystem - Filesystem operations for AI agents
• https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-recording - Session recording and playback
• https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-debugger - MCP protocol debugging tools

Acknowledgments

Built with:

• https://github.com/modelcontextprotocol/sdk - MCP protocol implementation
• https://github.com/soyuka/pidusage - Process resource monitoring
• https://github.com/npm/node-which - Executable path resolution
• https://github.com/isaacs/minimatch - Glob pattern matching