Terminator

功能

• 跨平台支持：适用于 macOS 和 Linux
• 可配置超时：为命令执行设置自定义超时值
• 安全执行：命令在受控环境中运行，并提供适当的错误处理
• 平台感知：自动检测并适配宿主平台
• 灵活的 Shell 支持：可配置用于执行命令的 Shell
• GUI 应用支持：自动转发 X11 应用所需的 DISPLAY 环境变量
• 多种传输模式：
  • STDIO 模式，适用于传统 MCP 客户端
  • 🌐 StreamableHTTP 传输：符合标准的基于 HTTP 的 MCP 传输方式，适用于 Web 集成
• 灵活的会话管理：可使用任意会话 ID，无需预先注册
• 🎉 持久 Shell 会话：在命令之间保留 Shell 状态（工作目录、环境变量等）

快速开始

# Build the server
make build

# Run in HTTP mode with StreamableHTTP transport
./mcp-terminal-server --http --port 8080

# Run in STDIO mode (default)
./mcp-terminal-server

🚀 快速测试

测试 StreamableHTTP 传输

# Start server in HTTP mode
./mcp-terminal-server --http --port 8080

# Test MCP initialization
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'

# Test tools listing (use session ID from initialize response)
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Execute a command
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "execute_command", "arguments": {"command": "echo Hello StreamableHTTP!"}}}'

测试持久 Shell

# Test persistent shell functionality
chmod +x examples/persistent_shell_examples.sh
./examples/persistent_shell_examples.sh

文档

📚 完整文档

• 快速入门指南 - 几分钟内即可开始使用
• 入门指南 - 全面的设置和配置说明
• Vercel AI SDK 集成 - 连接到 Vercel AI SDK
• 架构概览 - 系统设计和模块化结构

可用工具

1. execute_command - 在超时限制内执行单条命令
2. persistent_shell - 在持久 Shell 会话中执行命令
3. session_manager - 管理 Shell 会话（列出、关闭）

环境变量

服务支持以下环境变量：

• MCP_COMMAND_TIMEOUT - 命令默认超时时间，单位为秒（默认值：30）
• MCP_SHELL - 用于执行命令的自定义 Shell（Unix 上的默认值：/bin/bash）
• DISPLAY - GUI 应用使用的 X11 显示器（自动转发给命令）

GUI 应用支持

服务会自动将 DISPLAY 环境变量转发给所有已执行的命令，使 GUI 应用能够在正确的显示器上打开。此功能适用于非持久命令和持久 Shell 会话。

示例：启动 GUI 应用

# Set DISPLAY when starting the server
DISPLAY=:0 ./mcp-terminal-server

# GUI applications launched through MCP will use the correct display
# e.g., xterm, firefox, gedit, etc.

服务端点

以 HTTP 模式运行时（使用 --http 标志），服务会提供：

• POST /mcp - 用于所有 MCP 操作的 StreamableHTTP 传输端点
  • 支持 initialize、tools/list、tools/call 方法
  • 已认证的请求必须包含 Mcp-Session-Id 请求头
  • 对 initialize 调用，会在响应头中返回会话 ID

MCP 协议支持

此服务实现了 Model Context Protocol 规范：

• JSON-RPC 2.0 通信
• 基于 UUID 会话 ID 的会话管理
• 具有结构化输入/输出的工具执行
• 使用标准 JSON-RPC 错误代码的错误处理

平台支持

• macOS（darwin）：全面支持 — AMD64 和 ARM64
• Linux：全面支持 — AMD64 和 ARM64
• Docker：通过 buildx 提供多架构支持

集成

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "terminal": {
      "command": "/path/to/mcp-terminal-server",
      "env": {
        "MCP_COMMAND_TIMEOUT": "30",
        "DISPLAY": ":0"
      }
    }
  }
}

Docker

# Run AMD64 image
docker run --rm -p 8080:8080 terminal-mcp:latest-linux-amd64 --http --port 8080

# Run ARM64 image  
docker run --rm -p 8080:8080 terminal-mcp:latest-linux-arm64 --http --port 8080

# Run with persistent shell session
docker run --rm -p 8080:8080 -v /tmp:/tmp terminal-mcp:latest-linux-amd64 --http --port 8080

其他 MCP 客户端

此服务遵循标准 MCP 协议，应可与任何兼容的 MCP 客户端配合使用。

开发

构建

# Build for current platform
make build

# Build for all platforms
make build-all

# Build Docker images
make docker-build

# Build and push Docker images
REGISTRY=your-registry.com make docker-push

# Build DXT package for distribution
make dxt

依赖项

• github.com/mark3labs/mcp-go — MCP Go 库
• Go 1.23+（自动管理）

生产环境部署

在生产环境中，建议使用适当的进程管理和安全措施运行此服务：

进程管理

• s6：轻量级进程监控，支持自动重启
• systemd：功能全面的服务管理，支持资源限制
• Docker：通过安全隔离进行容器化部署
• Supervisor：基于 Python 的进程管理

安全功能

• 非 root 用户运行：使用专用用户账户运行，以限制权限
• 资源限制：限制 CPU、内存和文件访问
• 网络隔离：仅绑定到 localhost，以增强安全性
• AppArmor/SELinux：额外的强制访问控制
• 文件权限：仅允许访问必要的目录

📋 详细设置说明请参阅 进程管理指南

与 Iris Agent 集成

此 MCP 服务由 Iris Computer Use Agent 使用，这是我们的高级计算机操作 Agent，可自动执行终端交互。

许可证

本项目按原样提供，仅用于开发目的。