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 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 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 for detailed security implementation.

Installation

Docker (Recommended)

See DOCKER.md for detailed Docker usage instructions.

NPM

Yarn

Global Installation

Quick Start

Docker Quick Start

See DOCKER.md for detailed Docker instructions.

NPM Quick Start

1. Create Configuration File

This creates a sample configuration file with secure defaults.

2. Edit Configuration

Edit mcp-process-config.json to add your allowed executables:

3. Start the Server

Or use environment variables:

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

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

Example 2: Monitor Resource Usage

Example 3: Interactive Process with Stdin

Example 4: Long-Running Service

Example 5: Process Group Pipeline

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:

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:

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:

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

Testing

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:

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:

   npm run build

2. Check if the CLI exists:

   ls -la dist/cli.js

3. Run tests with verbose output:

   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:

   node dist/cli.js --help

6. Run minimal tests first:

   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:

   # List any orphaned node processes ps aux | grep node

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

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

Common E2E Test Issues:

CI Environment Considerations:

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

• 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:

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

Building

Publishing

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

• Email: info@digitaldefiance.org

Related Projects

• MCP Filesystem - Filesystem operations for AI agents

• MCP Recording - Session recording and playback

• MCP ACS Debugger - MCP protocol debugging tools

Acknowledgments

Built with:

• @modelcontextprotocol/sdk - MCP protocol implementation

• pidusage - Process resource monitoring

• which - Executable path resolution

• minimatch - Glob pattern matching