<div align="right"> <a href="README.EN.md">🌐 English</a> </div>

Terminal Capture MCP Server

基于 Model Context Protocol 的通用终端输出捕获服务器，为 AI 代理提供命令行进程管理能力。

适用于任何命令行工具：Android/iOS 调试、构建工具、日志监控、服务器运维、网络诊断等。

使用 FastMCP v1.x（Python SDK）构建。

---

功能特性

• 一次性执行 — 运行命令，获取完整 stdout/stderr
• 后台进程 — 长时间运行的进程（logcat、构建监控）持续捕获输出
• 循环缓冲区 — 每个进程独立缓冲区，可配置最大行数（默认 10,000）
• 丰富过滤 — 正则搜索、Android logcat 级别（V/D/I/W/E/F）、标签匹配、时间范围
• 进程生命周期管理 — 启动、停止、列出、清除缓冲区
• MCP 资源 — 进程输出和状态以 URI 形式暴露

MCP 工具

工具	描述
terminal_exec	同步执行命令并返回完整输出
terminal_spawn	在后台启动命令并持续捕获输出
terminal_read	读取后台进程的捕获输出（支持过滤）
terminal_stop	停止后台进程（SIGTERM → 5s 后 SIGKILL）
terminal_list	列出所有托管进程的状态和缓冲区统计
terminal_clear	清除进程的输出缓冲区（不终止进程）
terminal_filter	使用正则跨进程搜索输出

MCP 资源

资源	描述
terminal://processes	所有进程概览
terminal://{pid}/output	进程的完整缓冲输出
terminal://{pid}/status	进程状态信息（JSON）

快速开始

环境要求

• Python 3.10+
• mcp>=1.27

安装依赖

pip install mcp>=1.27

在 OpenCode 中配置

添加到你的 opencode.json：

{
  "mcp": {
    "terminal-capture": {
      "type": "local",
      "command": ["python3", "/path/to/terminal-capture/server.py"],
      "enabled": true
    }
  }
}

使用示例

# 一次性执行：检查设备连接
terminal_exec(["adb", "devices"])

# 后台进程：捕获 logcat 输出
terminal_spawn(["adb", "logcat"], name="logcat")

# 过滤后台输出：只查看 Error 级别的 ActivityManager 日志
terminal_read(process_id=1, grep="Error", tag="ActivityManager")

# 跨进程搜索崩溃/异常
terminal_filter(pattern="crash|exception")

# 停止进程
terminal_stop(process_id=1)

架构

┌─────────────────────────────────────────────┐
│  Terminal Capture MCP Server                │
│                                             │
│  ProcessManager（进程管理器）                │
│  ├── exec()       — 一次性同步命令          │
│  ├── spawn()      — 后台进程                │
│  ├── stop()       — 优雅终止                │
│  └── list()       — 查询托管进程            │
│                                             │
│  每个进程独立 OutputBuffer（循环缓冲区）      │
│  ├── append(stream, text)  追加一行输出      │
│  ├── read(filters...)      读取并过滤输出    │
│  └── clear()               清空缓冲区        │
│                                             │
│  LogcatParser（可选）                        │
│  └── extract_level() / has_tag()            │
│      提取日志级别 / 匹配标签                │
└─────────────────────────────────────────────┘

适用场景

支持度	场景	示例命令	说明
✅	📱 Android 调试	adb logcat, adb devices, adb shell dumpsys	LogcatParser 专用解析器，支持 level/tag 过滤
✅	🔨 构建监控	gradle assembleDebug, npm run build, mvn compile	纯 stdout 输出，后台进程持续捕获
✅	📋 日志追踪	tail -f /var/log/*, journalctl -f	后台进程核心场景，循环缓冲区完美适配
✅	🌐 网络诊断	ping, curl -v, netstat	一次性或持续输出均可
✅	📦 包管理	npm install, pip install, brew install	一次性执行，等待完成后返回输出
⚠️	🍎 iOS 调试	xcodebuild, xcrun simctl	命令可运行，但无专用 iOS 日志解析器
⚠️	🐳 容器管理	docker logs -f, kubectl logs -f, docker compose up	依赖集群配置，输出格式无解析器
⚠️	🖥 服务器运维	top -b, dmesg -w, vmstat 1	需使用 batch 模式，不支持交互式 TUI 工具
❌	🖥 htop	htop	交互式 TUI，subprocess 无法分配 TTY
❌	🌐 tcpdump	tcpdump	需 root 权限，原始输出为二进制

✅ 完全支持 — 核心能力覆盖，有专用解析器或格式兼容 ⚠️ 部分支持 — 命令可运行，但缺乏专用解析或依赖外部环境 ❌ 不支持 — 技术限制无法正常工作

相关链接

• MCP 协议规范
• FastMCP 文档
• OpenCode MCP 指南