Terminal Wingman

终端Wingman MCP服务器

GNU的只读终端访问MCP（模型上下文协议）服务器 screen 会议。通过身份验证和速率限制，提供对屏幕窗口和回滚历史的安全、结构化访问。

特性

• 只读终端访问：读取当前屏幕并回滚历史记录
• 窗口管理：列出窗口并在它们之间切换
• .screenrc意识：自动读取 defscrollback 设置
• 多种身份验证方法：无、基于密码或令牌
• 速率限制：通过可配置的限制防止滥用
• 多个传输：stdio和HTTP
• 健康检查端点：监视服务器状态
• 安全执行：超时保护和自动清理

安装

选项1：预构建二进制文件（推荐）

1. 从以下网址下载适用于您操作系统的最新版本 发布页面.
2. 提取档案（例如。， tar -xzf terminal-wingman_Linux_x86_64.tar.gz).
3. 将二进制文件移动到PATH中的某个位置：

sudo mv terminal-wingman /usr/local/bin/

选项2：从源代码构建

git clone 
cd terminal-wingman
go mod tidy
go build -o terminal-wingman ./cmd

用法

基本用法（HTTP传输）

# Start server with default settings
./terminal-wingman --session work

# Start with authentication
./terminal-wingman \
  --session work \
  --auth-type token \
  --auth-username  \
  --auth-token 

生成身份验证令牌

./terminal-wingman --auth-generate-token --auth-username 

标准运输（适用于Cursor、Claude Code、Windsurf）

./terminal-wingman --session work --transport stdio

命令行选项

Flags:
  --session string              Screen session name (required)
  --max-scrollback-lines int    Override max scrollback lines (default: from .screenrc or 10000)
  --cache-ttl int               Cache TTL in seconds (default: 30)
  --hardcopy-timeout int        Hardcopy timeout in seconds (default: 5)
  --server-host string          MCP server host (default: "localhost")
  --server-port int             MCP server port (default: 8080)
  --transport string            Transport protocol (stdio, streamable-http) (default: "streamable-http")
  --auth-type string            Authentication type (none, password, token) (default: "none")
  --auth-username string        Username for authentication
  --auth-password               Prompt for authentication password
  --auth-password-value string  Password for authentication (NOT RECOMMENDED)
  --auth-token string           Authentication token
  --auth-generate-token         Generate a random token and print it
  --rate-limit                  Enable rate limiting
  --rate-limit-rate float       Requests per second (default: 10)
  --rate-limit-burst int        Maximum burst size (default: 20)
  --log-level string            Logging level (DEBUG, INFO, WARNING, ERROR) (default: "INFO")
  --health-check                Enable health check endpoint at /health

MCP工具

read_terminal

从屏幕窗口读取当前可见的终端内容。

参数:

• window_id （可选）：要读取的窗口ID/编号

示例:

curl -X POST http://localhost:8080/mcp/tools/read_terminal \
  -H "Content-Type: application/json" \
  -d '{}'

read_scrollback

从屏幕窗口读取回滚历史记录。

参数:

• window_id （可选）：要读取的窗口ID/编号
• lines （可选）：行数（默认值：from.screenrc或1000）

示例:

curl -X POST http://localhost:8080/mcp/tools/read_scrollback \
  -H "Content-Type: application/json" \
  -d '{"lines": 2000}'

list_windows

列出屏幕会话中的所有窗口。

示例:

curl -X POST http://localhost:8080/mcp/tools/list_windows \
  -H "Content-Type: application/json" \
  -d '{}'

use_window

切换到特定窗口。

参数:

• window_id （必填）：要切换到的窗口ID/编号

示例:

curl -X POST http://localhost:8080/mcp/tools/use_window \
  -H "Content-Type: application/json" \
  -d '{"window_id": "12"}'

IDE集成

光标集成

添加到您的 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "terminal-wingman": {
      "command": "/path/to/terminal-wingman",
      "args": ["--session", "work", "--transport", "stdio"]
    }
  }
}

通过身份验证：

{
  "mcpServers": {
    "terminal-wingman": {
      "command": "/path/to/terminal-wingman",
      "args": [
        "--session", "work",
        "--transport", "stdio",
        "--auth-type", "token",
        "--auth-username", "your_user_here",
        "--auth-token", "your_token_here"
      ]
    }
  }
}

Windsurf集成

添加到您的 ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "terminal-wingman": {
      "command": "terminal-wingman",
      "args": ["--session", "work", "--transport", "stdio"]
    }
  }
}

{
  "mcpServers": {
    "terminal-wingman": {
      "command": "/path/to/terminal-wingman",
      "args": [
        "--session", "work",
        "--transport", "stdio",
        "--auth-type", "token",
        "--auth-username", "your_user_here",
        "--auth-token", "your_token_here"
      ]
    }
  }
}

Claude代码集成

添加到您的 ~/.claude.json

{
  "mcpServers": {
    "terminal-wingman": {
      "command": "terminal-wingman",
      "args": ["--session", "work", "--transport", "stdio"]
    }
  }
}

{
  "mcpServers": {
    "terminal-wingman": {
      "command": "/path/to/terminal-wingman",
      "args": [
        "--session", "work",
        "--transport", "stdio",
        "--auth-type", "token",
        "--auth-username", "your_user_here",
        "--auth-token", "your_token_here"
      ]
    }
  }
}

回滚配置

终端Wingman自动读取您的 ~/.screenrc 文件为 defscrollback 设置：

# In ~/.screenrc
defscrollback 10000

优先级顺序：

1. 命令行 --max-scrollback-lines 旗帜（最高）
2. .screenrc defscrollback 设置
3. 默认值（默认值1000，最大值10000）

健康检查

当 --health-check 启用后，健康端点可在以下位置获得：

http://localhost:8081/health

安全须知

• 所有操作都是只读的，除了 use_window 切换窗口焦点
• 使用屏幕 hardcopy 安全内容捕获命令
• 所有屏幕命令都有超时保护
• 临时文件会自动清理
• 限速防止滥用
• 身份验证可防止未经授权的访问

建筑

terminal-wingman/
├── cmd/                    # Main application entry point
├── internal/
│   ├── auth/              # Authentication strategies
│   ├── screen/            # Screen session management
│   ├── mcp/               # MCP protocol implementation
│   ├── ratelimit/         # Rate limiting
│   └── server/            # HTTP/transport server
└── pkg/
    ├── types/             # Type definitions
    └── utils/             # Utility functions

测试

# Run with screen session "work"
./terminal-wingman --session work

# Test tools
curl -X POST http://localhost:8080/mcp/tools/list_windows -d '{}'
curl -X POST http://localhost:8080/mcp/tools/read_terminal -d '{"window_id": "12"}'
curl -X POST http://localhost:8080/mcp/tools/read_scrollback -d '{"window_id": "12", "lines": 2000}'
curl -X POST http://localhost:8080/mcp/tools/use_window -d '{"window_id": "11"}'

终端僚机的特点

1. 默认情况下为只读：只有 use_window 修改状态
2. 更安全的执行：用途 screen -X hardcopy 用于内容捕获
3. 更好的错误处理：超时、验证、自动清理
4. 结构化输出：正确的JSON序列化
5. 缓存：减少不必要的屏幕命令执行
6. 两种运输方式：stdio用于游标，HTTP用于测试
7. .screenrc意识：尊重用户的滚动配置
8. 窗口切换：包括 use_window 工具

另见

• GNU屏幕文档
• 模型上下文协议