MCP Console Automation

🚀 MCP 控制台自动化服务器

MCP 控制台自动化服务器是一个生产就绪的模型上下文协议（MCP）服务器，它使 AI 助手能够与控制台应用程序进行全面交互，监控输出、检测错误并自动化终端工作流程，其工作方式类似于 Playwright 对 Web 浏览器的支持。

🚀 快速开始

MCP 控制台自动化服务器为 AI 助手与控制台应用程序的交互提供了强大支持。以下是快速开始使用该服务器的步骤。

✨ 主要特性

• 全面的终端控制：可同时创建和管理多个控制台会话。
• 交互式输入：发送文本输入和特殊键序列（如 Enter、Tab、Ctrl+C 等）。
• 实时输出监控：实时捕获和分析控制台输出。
• 流式支持：为长时间运行的进程提供高效的流式处理。
• 多控制台类型支持：支持 cmd、PowerShell、bash、zsh、sh 等多种控制台类型。
• 自动错误检测：内置模式用于检测错误、异常和堆栈跟踪。
• 会话管理：可创建、停止和管理多达 50 个并发会话。
• 资源管理：进行内存监控、自动清理和会话限制。
• 命令执行：运行命令并支持超时等待完成。
• 模式匹配：在继续执行之前等待特定的输出模式。
• 跨平台支持：无需本地依赖，可在 Windows、macOS 和 Linux 上运行。

📦 安装指南

Windows（以管理员身份运行 PowerShell）

git clone https://github.com/ooples/mcp-console-automation.git
cd mcp-console-automation
.\install.ps1 -Target claude  # 或者选择 google、openai、custom、all

macOS/Linux

git clone https://github.com/ooples/mcp-console-automation.git
cd mcp-console-automation
chmod +x install.sh
./install.sh --target claude  # 或者选择 google、openai、custom、all

手动安装

git clone https://github.com/ooples/mcp-console-automation.git
cd mcp-console-automation
npm install --production
npm run build

📚 详细文档

配置

针对 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "console-automation": {
      "command": "npx",
      "args": ["@mcp/console-automation"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

针对其他 MCP 客户端

# 启动服务器
mcp-console --log-level info

# 或者使用 npx
npx @mcp/console-automation --log-level info

可用工具（共 12 个）

console_create_session

创建一个新的控制台会话以运行命令。 参数：

• command（必需）：要执行的命令
• args：命令参数数组
• cwd：工作目录
• env：环境变量对象
• detectErrors：启用自动错误检测（默认值：true）
• timeout：会话超时时间（毫秒）

示例：

{
  "command": "python",
  "args": ["script.py"],
  "cwd": "/path/to/project",
  "detectErrors": true
}

console_send_input

向活动的控制台会话发送文本输入。 参数：

• sessionId（必需）：会话 ID
• input（必需）：要发送的文本

console_send_key

向控制台会话发送特殊键序列。 参数：

• sessionId（必需）：会话 ID
• key（必需）：要发送的键（如 enter、tab、up、down、ctrl+c、escape 等）

console_get_output

从控制台会话中检索输出。 参数：

• sessionId（必需）：会话 ID
• limit：要返回的最大输出行数

console_wait_for_output

等待控制台中出现特定的输出模式。 参数：

• sessionId（必需）：会话 ID
• pattern（必需）：要等待的正则表达式模式
• timeout：超时时间（毫秒，默认值：5000）

console_execute_command

执行命令并等待完成。 参数：

• command（必需）：要执行的命令
• args：命令参数
• cwd：工作目录
• env：环境变量
• timeout：执行超时时间

console_detect_errors

分析控制台输出中的错误和异常。 参数：

• sessionId：要分析的会话 ID
• text：要分析的直接文本（如果不使用会话）

console_stop_session

停止活动的控制台会话。 参数：

• sessionId（必需）：要停止的会话 ID

console_list_sessions

列出所有活动的控制台会话。

console_resize_session

调整会话的终端尺寸。 参数：

• sessionId（必需）：会话 ID
• cols（必需）：列数
• rows（必需）：行数

console_clear_output

清除会话的输出缓冲区。 参数：

• sessionId（必需）：会话 ID

使用场景

1. 运行和监控开发服务器

// 为开发服务器创建一个会话
const session = await console_create_session({
  command: "npm",
  args: ["run", "dev"],
  detectErrors: true
});

// 等待服务器启动
await console_wait_for_output({
  sessionId: session.sessionId,
  pattern: "Server running on",
  timeout: 10000
});

// 监控错误
const errors = await console_detect_errors({
  sessionId: session.sessionId
});

2. 交互式调试会话

// 启动 Python 调试会话
const session = await console_create_session({
  command: "python",
  args: ["-m", "pdb", "script.py"]
});

// 设置断点
await console_send_input({
  sessionId: session.sessionId,
  input: "b main\n"
});

// 继续执行
await console_send_input({
  sessionId: session.sessionId,
  input: "c\n"
});

// 单步执行代码
await console_send_key({
  sessionId: session.sessionId,
  key: "n"
});

3. 带错误检测的自动化测试

// 运行测试
const result = await console_execute_command({
  command: "pytest",
  args: ["tests/"],
  timeout: 30000
});

// 检查测试失败情况
const errors = await console_detect_errors({
  text: result.output
});

if (errors.hasErrors) {
  console.log("检测到测试失败:", errors);
}

4. 交互式 CLI 工具自动化

// 启动交互式 CLI 工具
const session = await console_create_session({
  command: "mysql",
  args: ["-u", "root", "-p"]
});

// 输入密码
await console_wait_for_output({
  sessionId: session.sessionId,
  pattern: "Enter password:"
});

await console_send_input({
  sessionId: session.sessionId,
  input: "mypassword\n"
});

// 运行 SQL 命令
await console_send_input({
  sessionId: session.sessionId,
  input: "SHOW DATABASES;\n"
});

错误检测模式

服务器内置了用于检测常见错误类型的模式：

• 通用错误（error:、ERROR:、Error:）
• 异常（Exception:、exception）
• 警告（Warning:、WARNING:）
• 致命错误
• 操作失败
• 权限/访问被拒绝
• 超时
• 堆栈跟踪（Python、Java、Node.js）
• 编译错误
• 语法错误
• 内存错误
• 连接错误

开发

从源代码构建

npm install
npm run build

在开发模式下运行

npm run dev

运行测试

npm test

类型检查

npm run typecheck

代码检查

npm run lint

架构

服务器采用以下技术构建：

• node-pty：用于创建和管理伪终端
• @modelcontextprotocol/sdk：MCP 协议实现
• TypeScript：提供类型安全和更好的开发体验
• Winston：用于结构化日志记录

核心组件

1. ConsoleManager：管理终端会话、输入/输出和生命周期
2. ErrorDetector：分析输出中的错误和异常
3. MCP Server：通过 MCP 工具公开控制台功能
4. Session Management：处理多个并发控制台会话

要求

• Node.js >= 18.0.0
• Windows、macOS 或 Linux 操作系统
• 无需额外的构建工具！

测试

运行包含的测试套件以验证功能：

node test-functionality.js

故障排除

常见问题

1. 权限被拒绝错误：确保服务器有权限生成进程。
2. node-pty 编译错误：安装适用于您平台的构建工具。
3. 会话无响应：检查命令是否需要 TTY 交互。
4. 输出未捕获：某些应用程序可能直接写入终端，绕过了 stdout。

贡献

欢迎贡献代码！请随时提交拉取请求。

1. 分叉仓库
2. 创建您的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m '添加一些惊人的功能')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开拉取请求

🔧 技术细节

生产状态 ✅

此服务器已完全准备好投入生产，具备以下特性：

• ✅ 无需本地编译（移除了 node-pty 依赖）
• ✅ 全面的跨平台支持（Windows、macOS、Linux）
• ✅ 对长时间运行的进程提供流式支持
• ✅ 支持多种控制台类型（cmd、PowerShell、bash、zsh、sh）
• ✅ 资源管理和自动清理
• ✅ 全面的错误处理和恢复
• ✅ 为所有主要 MCP 客户端提供简单的安装脚本
• ✅ 所有测试通过（请参阅 test-functionality.js）

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

如有问题、疑问或建议，请在 GitHub 上创建一个问题： https://github.com/yourusername/mcp-console-automation/issues

路线图

• [ ] 添加对终端录制和回放的支持
• [ ] 实现会话持久化和恢复
• [ ] 为特定语言添加更多错误检测模式
• [ ] 支持终端多路复用（tmux/screen 集成）
• [ ] 基于 Web 的终端查看器
• [ ] 会话共享和协作功能
• [ ] 性能分析工具
• [ ] 与流行的 CI/CD 系统集成