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

# Terminal Capture MCP Server

基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的通用终端输出捕获服务器，为 AI 代理提供命令行进程管理能力。

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

使用 [FastMCP](https://github.com/jlowin/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`

### 安装依赖

```bash
pip install mcp>=1.27
```

### 在 OpenCode 中配置

添加到你的 `opencode.json`：

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

### 使用示例

```python
# 一次性执行：检查设备连接
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 协议规范](https://modelcontextprotocol.io/)
- [FastMCP 文档](https://github.com/jlowin/fastmcp)
- [OpenCode MCP 指南](https://opencode.ai/)