MCP Terminal Bridge

终点桥

*无头但强大*

MCP（模型上下文协议）服务器，使AI助手能够无缝控制终端/TUI应用程序并与之交互。

概述

该服务器充当AI助手（如Claude）和终端应用程序之间的桥梁，提供：

• 使用PTY仿真启动终端应用程序
• 支持ANSI的可视化输出捕获
• 键盘输入模拟
• 终端状态信息

当前实施状态

第一阶段：基础（完成✅)

• ✅ 所有9个MCP工具均已实施并正常工作
• ✅ 具有自动清理功能的会话管理
• ✅ PTY终端控制包装
• ✅ 具有基本ANSI支持的屏幕缓冲区
• ✅ 特殊按键映射（箭头、功能键、Ctrl序列）
• ✅ 多种输出格式（普通、原始、ansi）
• ✅ 并发会话支持
• ✅ 使用Makefile构建系统

第2阶段：核心功能（完成✅)

• ✅ 增强的ANSI解析器（支持CSI、SGR、OSC、DCS等）
• ✅ 支持SIGWINCH处理的终端大小调整
• ✅ 全程结构化日志记录
• ✅ 支持回滚缓冲区（1000行）
• ✅ 所有单元测试均已通过
• ✅ 使用ANSI序列的正确renderRaw（）
• ✅ 多种输出格式，包括回滚

第3阶段：测试和稳健性（进行中🚧)

• ✅ 综合集成测试框架
• ✅ 对所有9个MCP工具进行测试
• ✅ 测试应用程序（回声、菜单、进度）
• ✅ 18个集成测试中有13个通过
• 🚧 错误恢复和会话管理
• 🚧 性能优化

快速开始

# Install dependencies
go mod download

# Build the server
make build

# Build test applications
make test-apps

# Run the server (stdio mode)
./bin/terminalbridge

# Or run directly
go run cmd/server/main.go

# Run tests
make test

# Test with example app (in another terminal)
cd test/apps
./echo

MCP工具

launch_app

启动一个新的终端应用程序。

{
  "command": "vim",
  "args": ["test.txt"],
  "env": {"TERM": "xterm-256color"}
}

view_屏幕

获取当前终端内容。

{
  "session_id": "session-123",
  "format": "plain"  // or "raw", "ansi", "scrollback"
}

输出格式：

• plain：仅文本，无ANSI转义序列
• raw：带ANSI转义序列的全端子输出
• ansi：显示光标位置的调试格式▮
• scrollback：包括回滚缓冲区历史记录

send_keys

将键盘输入发送到终端。

{
  "session_id": "session-123",
  "keys": "Hello World"  // or "Enter", "Ctrl+C", etc.
}

其他工具

• get_cursor_position：获取当前光标位置
• get_screen_size：获取终端尺寸
• resize_terminal：调整终端窗口的大小
• restart_app：重新启动会话
• stop_app：终止会话
• list_sessions：列出所有活动会话

配置

环境变量：

• MCP_PORT：当前stdio实现中未使用
• MAX_SESSIONS：最大并发会话数（默认值：100）
• SESSION_TIMEOUT：空闲超时时间（分钟）（默认值：30）
• LOG_LEVEL：日志记录级别（默认值：info）

实现注意事项

• 用途 mark3labs/mcp-go v0.31.0适用于MCP协议
• 用途 creack/pty v1.1.24用于终端仿真
• 在标准输入/输出模式下运行
• 会话清理每5分钟运行一次
• 默认终端尺寸：80x24（可通过调整大小 resize_terminal 工具）
• 结构化JSON日志记录到stderr（可通过LOGLEVEL配置）
• 增强的ANSI解析器支持最常见的转义序列

发展

看 project.md 完成技术设计和 progress.md 对于当前的发展状况。

测试

# Run all tests
make test

# Run with coverage
make test-coverage

# Run integration tests
make test-integration

# Run specific test suites
make test-terminal    # Terminal package tests
make test-session     # Session manager tests

许可证

麻省理工学院