mcp-console-automation

控制台自动化 MCP 服务

Model Context Protocol（MCP）服务，用于受控地与本地控制台应用和远程 SSH 会话交互，包括输出监控、错误检测和长时间运行的工作流。

安全状态

此服务可以执行任意命令并建立远程 SSH 会话。请将其视为具有特权的终端，而非低风险的文档连接器：

• 为命令／会话变更操作启用 MCP 工具审批；
• 优先使用 SSH 密钥或环境变量凭据引用，而非内联机密；
• 使用受限的部署账户，并设置单独的生产审批步骤；
• 除非明确需要诊断信息，否则不要设置 MCP_DEBUG_LOG 和 MCP_LOG_DIR；
• 除非明确需要恢复元数据，否则不要启用会话持久化；
• 仅在需要时安装云、容器和串口集成。

功能

🚀 核心功能

• 全面的终端控制：创建和管理多达 50 个并发控制台会话
• 多协议支持：本地 shell（cmd、PowerShell、pwsh、bash、zsh、sh）和远程 SSH 连接
• 交互式输入：发送文本输入和特殊按键序列（Enter、Tab、Ctrl+C 等）
• 实时输出监控：捕获、筛选和分析控制台输出，并支持高级搜索
• 流式支持：通过模式匹配，高效处理长时间运行进程的流式输出
• 自动错误检测：内置模式，可检测多种语言中的错误、异常和堆栈跟踪
• 跨平台：无需原生依赖，可在 Windows、macOS 和 Linux 上运行

🔐 SSH 和远程连接

• 全面的 SSH 支持：支持密码和密钥身份验证，并支持密码短语
• SSH 选项：自定义端口、连接超时和 keep-alive 设置
• 连接配置文件：保存可重复使用的 SSH 元数据和环境变量凭据引用
• 云平台支持：通过已保存的配置文件连接 Azure、AWS、GCP 和 Kubernetes
• 容器支持：集成 Docker 和 WSL，支持容器化工作流

✅ 测试自动化框架

• 自动化测试用例：内置断言工具，用于验证控制台输出
• 输出断言：验证输出是否包含指定内容、是否匹配正则表达式或是否等于预期值
• 退出代码验证：断言命令退出代码，以检测成功或失败
• 无错误验证：自动检查命令输出中是否存在错误
• 状态快照：保存并比较操作前后的会话状态
• 测试工作流：串联多个断言，完成全面的测试场景

🔄 后台作业执行

• 异步命令执行：在后台运行长时间执行的命令，并完整捕获输出
• 优先级队列系统：为作业设置优先级（1-10 级），以优化资源利用
• 作业监控：跟踪后台作业的状态、进度和完成情况
• 作业控制：取消、暂停或恢复后台操作
• 结果获取：获取已完成作业的完整输出和退出代码
• 资源管理：自动清理已完成的作业，并可配置保留期限

📊 企业级监控和警报

• 系统级指标：跟踪 CPU、内存、磁盘和网络使用情况
• 会话指标：监控各会话的性能和资源消耗
• 实时仪表板：提供可自定义视图的实时监控数据
• 警报系统：针对性能、错误、安全和异常情况发出警报，并设置严重级别
• 自定义监控：为每个会话配置监控间隔、指标和阈值
• 诊断：内置错误分析和会话健康状况验证

📁 配置文件管理

• 连接配置文件：保存 SSH、Docker、WSL 和云平台连接
• 应用程序配置文件：存储常用命令配置（Node.js、Python、.NET、Java、Go、Rust）
• 快速连接：使用已保存的配置文件即时连接，并支持覆盖配置
• 环境变量：按配置文件存储环境配置
• 工作目录管理：为每个配置文件设置默认目录

🔍 高级输出处理

• 正则表达式筛选：使用正则表达式搜索输出（区分大小写／不区分大小写）
• 多模式搜索：使用 AND／OR 逻辑组合多个模式
• 分页：获取指定行范围、开头或结尾的输出
• 按时间筛选：按时间戳筛选输出（绝对时间或相对时间：'5m'、'1h'、'2d'）
• 输出流：实时捕获长时间运行进程的输出
• 缓冲区管理：清除输出缓冲区以减少内存使用

快速安装

Windows

git clone https://github.com/ooples/mcp-console-automation.git
cd mcp-console-automation
.\install.ps1 -Target codex

macOS/Linux

git clone https://github.com/ooples/mcp-console-automation.git
cd mcp-console-automation
chmod +x install.sh
./install.sh --target codex

手动安装

git clone https://github.com/ooples/mcp-console-automation.git
cd mcp-console-automation
npm ci
npm run build
codex mcp add console-automation --env LOG_LEVEL=warn -- node "$PWD/dist/mcp/server.js"

配置

Codex 将 MCP 配置存储在 ~/.codex/config.toml 中。安装程序使用 codex mcp add，并安全替换已有的 console-automation 注册项。安装后重启 Codex，并使用 /mcp 验证连接。

对于其他 MCP 客户端，可生成新的 JSON 配置，而不会覆盖现有文件：

.\install.ps1 -Target custom -CustomPath C:\path\to\new-mcp-config.json

npm 包尚未发布，因此 npx console-automation-mcp 和 @mcp/console-automation 不是有效的安装方式。

已保存的 SSH 凭据

console_save_profile 会拒绝内联密码、私钥内容和密码短语。请使用 passwordEnvVar、privateKeyEnvVar 或 privateKeyPath，以及 passphraseEnvVar。配置文件列表响应不会返回凭据值；在操作系统支持 POSIX 模式的情况下，配置文件将仅授予所有者权限。

会话持久化

默认情况下，会话持久化处于禁用状态，因为会话恢复数据可能包含命令、路径和环境值。若要启用，请设置 MCP_SESSION_PERSISTENCE=true。默认文件为 ~/.console-automation-mcp/sessions.json；可通过 MCP_SESSION_PERSISTENCE_PATH 覆盖。除非通过程序化的 SessionManager 配置启用，否则持久化的命令／环境恢复数据仍处于禁用状态。

生产安装程序会移除开发用和可选协议包。本地控制台和 SSH 仍可使用。请仅安装 Docker、云平台、Kubernetes、串行或其他可选适配器所需的对等依赖包。

可用工具（共 40 个）

此 MCP 服务提供 40 个全面的工具，分为 6 个类别：

📚 完整文档

• 完整工具参考 - 40 个工具的详细文档
• 实用示例 - 真实使用示例和模式
• 发布指南 - 如何将此服务列入注册表

工具类别

🖥️ 会话管理（9 个工具）

• console_create_session - 创建本地或 SSH 控制台会话
• console_send_input - 向会话发送文本输入
• console_send_key - 发送特殊按键（Enter、Ctrl+C 等）
• console_get_output - 获取经过筛选／分页的输出，并进行高级搜索
• console_get_stream - 流式获取长时间运行进程的输出
• console_wait_for_output - 等待指定模式
• console_stop_session - 停止会话
• console_list_sessions - 列出所有活动会话
• console_cleanup_sessions - 清理非活动会话

⚡ 命令执行（6 个工具）

• console_execute_command - 执行命令并捕获输出
• console_detect_errors - 分析输出中的错误
• console_get_resource_usage - 获取系统资源统计信息
• console_clear_output - 清除输出缓冲区
• console_get_session_state - 获取会话执行状态
• console_get_command_history - 查看命令历史

📊 监控与告警（6 个工具）

• console_get_system_metrics - 全面的系统指标
• console_get_session_metrics - 会话专属指标
• console_get_alerts - 活动监控告警
• console_get_monitoring_dashboard - 实时仪表板数据
• console_start_monitoring - 启动自定义监控
• console_stop_monitoring - 停止监控

📁 配置文件管理（4 个工具）

• console_save_profile - 保存 SSH/应用连接配置文件
• console_list_profiles - 列出已保存的配置文件
• console_remove_profile - 移除配置文件
• console_use_profile - 使用已保存的配置文件快速连接

🔄 后台任务（9 个工具）

• console_execute_async - 异步执行命令
• console_get_job_status - 检查任务状态
• console_get_job_output - 获取任务输出
• console_cancel_job - 取消正在运行的任务
• console_list_jobs - 列出所有后台任务
• console_get_job_progress - 监控任务进度
• console_get_job_result - 获取完整任务结果
• console_get_job_metrics - 任务执行统计信息
• console_cleanup_jobs - 清理已完成的任务

✅ 测试自动化（6 个工具）

• console_assert_output - 断言输出符合条件
• console_assert_exit_code - 断言退出代码
• console_assert_no_errors - 验证未发生错误
• console_save_snapshot - 保存会话状态快照
• console_compare_snapshots - 比较状态差异
• console_assert_state - 断言会话状态

快速入门示例

创建本地会话

const session = await console_create_session({
  command: "npm",
  args: ["run", "dev"],
  detectErrors: true
});

通过 SSH 连接

const session = await console_create_session({
  command: "bash",
  consoleType: "ssh",
  sshOptions: {
    host: "example.com",
    username: "user",
    privateKeyPath: "~/.ssh/id_rsa"
  }
});

使用断言运行测试

const session = await console_create_session({
  command: "npm",
  args: ["test"]
});

await console_assert_output({
  sessionId: session.sessionId,
  assertionType: "contains",
  expected: "All tests passed"
});

后台任务执行

const job = await console_execute_async({
  sessionId: session.sessionId,
  command: "npm run build",
  priority: 8
});

const status = await console_get_job_status({
  jobId: job.jobId
});

更多示例请参阅 docs/EXAMPLES.md

使用场景

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

// Create a session for the dev server
const session = await console_create_session({
  command: "npm",
  args: ["run", "dev"],
  detectErrors: true
});

// Wait for server to start
await console_wait_for_output({
  sessionId: session.sessionId,
  pattern: "Server running on",
  timeout: 10000
});

// Monitor for errors
const errors = await console_detect_errors({
  sessionId: session.sessionId
});

2. 交互式调试会话

// Start a Python debugging session
const session = await console_create_session({
  command: "python",
  args: ["-m", "pdb", "script.py"]
});

// Set a breakpoint
await console_send_input({
  sessionId: session.sessionId,
  input: "b main\n"
});

// Continue execution
await console_send_input({
  sessionId: session.sessionId,
  input: "c\n"
});

// Step through code
await console_send_key({
  sessionId: session.sessionId,
  key: "n"
});

3. 使用错误检测进行自动化测试

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

// Check for test failures
const errors = await console_detect_errors({
  text: result.output
});

if (errors.hasErrors) {
  console.log("Test failures detected:", errors);
}

4. 交互式命令行工具自动化

// Start an interactive CLI tool
const session = await console_create_session({
  command: "mysql",
  args: ["-u", "root", "-p"]
});

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

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

// Run SQL commands
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 子进程和 ssh2：用于本地命令执行和 SSH 会话
• @modelcontextprotocol/sdk：MCP 协议实现
• TypeScript：提供类型安全性和更好的开发体验
• Winston：用于结构化日志记录

核心组件

1. ConsoleManager：管理终端会话、输入/输出和生命周期
2. ErrorDetector：分析输出以检测错误和异常
3. MCP 服务：通过 MCP 工具提供控制台功能
4. 会话管理：处理多个并发控制台会话

要求

• Node.js >= 18.0.0
• Windows、macOS 或 Linux 操作系统
• 可选的串行端口集成可能需要平台构建工具。

测试

运行静态验证、构建、MCP 冒烟测试和测试套件：

npm run lint
npm run typecheck
npm run build
npm run test:mcp
npm run test:logger
npm run test:installer
npm run test:package
npm test

故障排除

常见问题

1. 权限被拒绝错误：确保服务有权启动进程
2. 可选原生依赖项错误：仅在启用串行端口集成时安装平台构建工具
3. 会话无响应：检查命令是否需要 TTY 交互
4. 未捕获输出：某些应用可能会直接写入终端，绕过 stdout

贡献

欢迎贡献！欢迎提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到该分支（git push origin feature/AmazingFeature）
5. 创建 Pull Request

许可证

MIT 许可证——详情请参阅 LICENSE 文件

支持

如有问题、疑问或建议，请在 GitHub 上提交 issue： https://github.com/ooples/mcp-console-automation/issues

路线图

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