Name: AI代理进程管理服务器
Author: Digital-Defiance

使用说明

MCP ACS过程服务器

一种模型上下文协议（MCP）服务器，为AI代理提供进程管理和监控功能，具有由可执行的分配列表和资源限制强制执行的严格安全边界。

🔗 仓库

此包现在保存在自己的存储库中： https://github.com/Digital-Defiance/mcp-process

此存储库是 AI功能套件在GitHub上。

特性

进程启动：生成具有指定参数和环境变量的进程
资源监控：实时跟踪CPU、内存、线程数和I/O使用情况
输出捕获：分别捕获和检索stdout和stderr流
过程终止：优雅（SIGTERM）和强制（SIGKILL）终止，超时升级
服务管理：具有自动重启和健康检查功能的长期运行服务
流程组：管理相关流程并创建管道
超时管理：指定持续时间后自动终止进程
I/O管理：发送stdin输入并检索缓冲输出
安全：具有可执行分配列表、参数验证和资源限制的多层安全性
审计日志：完整的安全和合规操作跟踪

安全

此服务器通过6层验证实现了深度防御安全：

可执行许可列表：只能启动预先批准的可执行文件
参数验证：针对注入攻击验证了命令参数
环境消毒：已删除危险环境变量
资源限制：CPU、内存和时间限制可防止资源耗尽
特权预防：没有权限升级或setuid可执行文件
审计日志：完整的操作跟踪

看安全.md 详细的安全实施。

安装

Docker（推荐）

docker pull digitaldefiance/mcp-process:latest

看医生.md 了解详细的Docker使用说明。

NPM

npm install @ai-capabilities-suite/mcp-process

纱线

yarn add @ai-capabilities-suite/mcp-process

全球安装

npm install -g @ai-capabilities-suite/mcp-process

快速开始

Docker快速入门

# 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

看医生.md 了解详细的Docker说明。

NPM快速入门

1.创建配置文件

mcp-process --create-config ./mcp-process-config.json

这将创建一个具有安全默认值的示例配置文件。

2.编辑配置

编辑 mcp-process-config.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.启动服务器

mcp-process --config ./mcp-process-config.json

或者使用环境变量：

export MCP_PROCESS_CONFIG_PATH=./mcp-process-config.json
mcp-process

4.从您的AI代理连接

配置您的AI代理（例如Kiro、Claude Desktop）以通过stdio传输连接到MCP服务器。

配置

配置文件位置

服务器按以下顺序查找配置：

--config 命令行参数
MCP_PROCESS_CONFIG_PATH 环境变量
MCP_PROCESS_CONFIG 环境变量（JSON字符串）
./mcp-process-config.json
./config/mcp-process.json

配置选项

看安全.md 有关详细的配置选项和安全设置。

最小配置

{
  "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工具

服务器公开了12个MCP工具用于流程管理：

进程启动

启动新流程。

参数：

executable （字符串，必填）：可执行文件的路径
args （string[]，可选）：命令行参数
cwd （字符串，可选）：工作目录
env （对象，可选）：环境变量
timeout （数字，可选）：超时时间（毫秒）
captureOutput （boolean，可选）：是否捕获stdout/stderr
resourceLimits （object，可选）：资源限制

退货：

pid （编号）：进程ID
startTime （string）：进程开始的ISO时间戳

进程终止

终止进程。

参数：

pid （数字，必填）：进程ID
force （boolean，可选）：使用SIGKILL而不是SIGTERM
timeout （数字，可选）：优雅终止超时（毫秒）

退货：

exitCode （数字）：进程退出代码
terminationReason （string）：“优雅”或“强迫”

进程_参数统计

获取进程资源使用统计信息。

参数：

pid （数字，必填）：进程ID
includeHistory （布尔值，可选）：包括历史数据

退货：

cpuPercent （数字）：CPU使用率百分比
memoryMB （数字）：内存使用情况（MB）
threadCount （number）：线程数
ioRead （数字）：读取的字节数
ioWrite （数字）：写入的字节数
uptime （数字）：进程正常运行时间（秒）
history （数组，可选）：历史统计

process_send_strin

将输入发送到进程stdin。

参数：

pid （数字，必填）：进程ID
data （string，必填）：要发送的数据
encoding （字符串，可选）：文本编码（默认：“utf-8”）

退货：

bytesWritten （number）：写入的字节数

进程_输出

获取捕获的流程输出。

参数：

pid （数字，必填）：进程ID
stream （字符串，可选）：“stdout”、“stderr”或“both”（默认值：“both）
encoding （字符串，可选）：文本编码（默认：“utf-8”）

退货：

stdout （string）：捕获的stdout
stderr （字符串）：捕获的stderr
stdoutBytes （数字）：标准缓冲区大小
stderrBytes （数字）：Stderr缓冲区大小

进程列表

列出所有管理流程。

退货：

包含PID、命令、状态和正常运行时间的过程信息对象数组

进程_状态

获取详细的流程状态。

参数：

pid （数字，必填）：进程ID

退货：

state （string）：“正在运行”、“停止”或“崩溃”
uptime （数字）：进程正常运行时间（秒）
stats （对象）：当前资源使用统计

进程_创建_组

创建流程组。

参数：

name （字符串，必填）：组名
pipeline （boolean，可选）：是否创建管道

退货：

groupId （string）：组标识符

process_add_togroup

将流程添加到组中。

参数：

groupId （字符串，必填）：组标识符
pid （数字，必填）：进程ID

进程_终止_组

终止组中的所有进程。

参数：

groupId （字符串，必填）：组标识符

process_start_service

通过自动重启启动长时间运行的服务。

参数：

name （string，必填）：服务名称
executable （字符串，必填）：可执行文件的路径
args （string[]，可选）：命令行参数
cwd （字符串，可选）：工作目录
env （对象，可选）：环境变量
restartPolicy （对象，可选）：重新启动配置
healthCheck （对象，可选）：健康检查配置

退货：

serviceId （string）：服务标识符
pid （编号）：初始进程ID

进程停止服务

停止服务并禁用自动重启。

参数：

serviceId （字符串，必填）：服务标识符

使用示例

示例1：运行一个简单命令

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

示例2：监控资源使用情况

// 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");

示例3：与Stdin的交互过程

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

示例4：长期运行服务

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

示例5：流程组管道

// 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,
});

故障排除

问题：“可执行文件不在allowlist中”

原因： 您尝试启动的可执行文件不在 allowedExecutables 配置。

解决方案： 将可执行文件添加到配置文件中：

{
  "allowedExecutables": ["node", "python3", "/path/to/your/executable"]
}

您可以使用：

绝对路径： /usr/bin/node
基础名称： node
球状图案： /usr/bin/*

问题：“Shell解释器被阻止”

原因： 您正试图启动一个shell（bash、sh、cmd.exe等），并且 blockShellInterpreters 已启用。

解决方案： 要么：

集 blockShellInterpreters: false 在您的配置中（不推荐）
直接启动实际的可执行文件，而不是通过shell

问题：“找不到进程”

原因： 进程已终止或PID无效。

解决方案： 使用检查进程是否仍在运行 process_list 或 process_get_status.

问题：“超出CPU限制”或“超出内存限制”

原因： 进程超出了配置的资源限制。

解决方案： 在配置或启动流程时增加资源限制：

{
  "defaultResourceLimits": {
    "maxCpuPercent": 90,
    "maxMemoryMB": 2048
  }
}

问题：“已达到最大并发进程数”

原因： 您已到达 maxConcurrentProcesses 限制。

解决方案：

终止一些正在运行的进程
增加 maxConcurrentProcesses 在您的配置中
等待进程完成

问题：“进程stdin不可用”

原因： 进程stdin已关闭或进程不支持stdin输入。

解决方案： 确保进程仍在运行，并且是在启用stdin的情况下启动的。

问题：找不到配置文件

原因： 服务器找不到您的配置文件。

解决方案：

使用 --config 标志： mcp-process --config /path/to/config.json
设置环境变量： export MCP_PROCESS_CONFIG_PATH=/path/to/config.json
将配置放置在 ./mcp-process-config.json

调试

通过设置审核日志级别启用调试日志记录：

{
  "enableAuditLog": true,
  "auditLogLevel": "debug"
}

查看审核日志，了解有关流程操作和安全违规的详细信息。

发展

先决条件

Node.js>=18.0.0
npm>=8.0.0

设置

# 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

测试

# 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

端到端（E2E）测试

MCP ACS Process Server包括全面的e2e测试，通过将服务器生成为子进程并使用JSON-RPC协议通过stdio进行通信来验证完整的系统行为。这些测试确保服务器在实际使用场景中正常工作。

E2E测试结构：

server.e2e.spec.ts -全面的e2e测试，涵盖所有MCP工具和协议功能
server.minimal.e2e.spec.ts -用于基本功能验证的快速烟雾测试（<30秒）

运行E2E测试：

# 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

E2E测试验证了什么：

MCP协议初始化和握手
通过工具/列表发现工具
通过安全执法处理启动操作
过程监控和资源统计
进程终止（优雅和强制）
输出捕获（stdout/stderr）
具有自动重启功能的服务管理
错误处理和验证
安全策略执行
资源限制执行
超时处理
JSON-RPC协议合规性

E2E测试要求：

在运行e2e测试之前，必须先构建服务器： npm run build
测试从以下位置生成服务器 dist/cli.js
测试使用JSON-RPC 2.0协议通过stdio进行通信
测试完成后，所有生成的进程都会被清理干净

调试E2E测试失败：

如果e2e测试失败，请执行以下步骤：

确保服务器已构建：
```
npm run build
```
检查CLI是否存在：
```
ls -la dist/cli.js
```

运行具有详细输出的测试：

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

检查服务器启动错误：
- E2E测试捕获服务器stderr输出
- 在测试输出中查找错误消息
- 常见问题：缺少依赖关系、权限错误、端口冲突
验证服务器是否可以手动启动：
```
node dist/cli.js --help
```
先运行最小测试：
```
npm run test:e2e:minimal
```
如果最低限度的测试通过，但全面的测试失败，则问题可能是特定功能而不是基本的服务器操作。

检查流程清理：

# List any orphaned node processes
ps aux | grep node

启用调试日志记录： 集 DEBUG=* 查看详细日志的环境变量：
```
DEBUG=* npm test -- --testPathPattern=e2e.spec.ts
```

常见的E2E测试问题：

问题	原因	解决方案
“找不到服务器可执行文件”	服务器未构建或路径错误	运行 `npm run build`
“服务器启动失败”	启动时服务器崩溃	检查测试日志中的stderr输出
“请求超时”	服务器没有响应	增加超时或检查服务器日志
“进程未清理”	测试清理失败	运行 `npm test -- --forceExit`
“端口已在使用中”	之前的测试未清理	杀死孤立进程
“权限被拒绝”	权限不足	检查dist/cli.js上的文件权限

CI环境注意事项：

E2E测试旨在在CI环境中运行，并考虑以下因素：

无头操作：不需要显示服务器
超时调整：CI环境超时时间延长50%
流程清理：即使测试失败，所有流程也已清理干净
无交互式输入：测试完全自动化运行
资源限制：测试可以优雅地处理较慢的CI环境

CI配置示例：

# .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

基于属性的测试：

E2E测试包括基于属性的测试，使用 fast-check 验证通用属性：

JSON-RPC请求/响应ID匹配
并发请求处理
使用随机允许的可执行文件启动进程
对被阻止的可执行文件进行安全拒绝

这些测试使用随机生成的输入运行多次迭代，以确保在各种场景中的正确性。

代码检查

npm run lint

建筑

# Clean build directory
npm run clean

# Build TypeScript
npm run build

出版

# Publish to npm (requires authentication)
npm run publish:public

建筑

MCP ACS Process Server由几个核心组件组成：

MCP服务器：实现MCP协议的主服务器
安全经理：多层安全验证
ProcessLauncher：进程生成和配置
进程管理器：流程生命周期管理
资源监视器：CPU、内存和I/O监控
IOMmanager：Stdin/stortout/stderr处理
进程终止程序：善意和强制终止
服务经理：长期运行服务管理
超时管理器：进程超时强制
工艺组：流程组和管道管理
配置加载器：配置文件加载和验证

贡献

欢迎投稿！请参阅主存储库以获取贡献指南： https://github.com/digital-defiance/ai-capabilities-suite

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

支持

GitHub问题： https://github.com/digital-defiance/ai-capabilities-suite/issues
电子邮件： info@digitaldefiance.org

致谢

内置：

@模型上下文协议/sdk -MCP协议实现
使用率 -过程资源监控
哪个 -可执行路径解析
小匹配 -球形图案匹配

使用说明

MCP ACS过程服务器

🔗 仓库

目录

特性

安全

安装

Docker（推荐）

NPM

纱线

全球安装

快速开始

Docker快速入门

NPM快速入门

1.创建配置文件

2.编辑配置

3.启动服务器

4.从您的AI代理连接

配置

配置文件位置

配置选项

最小配置

MCP工具

进程启动

进程终止

进程_参数统计

process_send_strin

进程_输出

进程列表

进程_状态

进程_创建_组

process_add_togroup

进程_终止_组

process_start_service

进程停止服务

使用示例

示例1：运行一个简单命令

示例2：监控资源使用情况

示例3：与Stdin的交互过程

示例4：长期运行服务

示例5：流程组管道

故障排除

问题：“可执行文件不在allowlist中”

问题：“Shell解释器被阻止”

问题：“找不到进程”

问题：“超出CPU限制”或“超出内存限制”

问题：“已达到最大并发进程数”

问题：“进程stdin不可用”

问题：找不到配置文件

调试

发展

先决条件

设置

测试

端到端（E2E）测试

代码检查

建筑

出版

建筑

贡献

许可证

支持

相关项目

致谢

相关 MCP

文件与终端管理MCP服务

进程执行工具

K8s MCP服务器

Shell命令执行服务器

React开发协议服务

React开发协议服务