mcp-pty

一个使用Bun、xterm.js和官方MCP SDK管理持久伪终端会话的MCP服务器，这些会话绑定到MCP客户端。与典型的shell执行不同，它提供了一个跨多个命令调用的持续终端环境。

安装

全局安装（推荐）

bun install -g mcp-pty

本地开发

git clone <repository>
cd mcp-pty
bun install
bun link  # 注册为全局命令

使用

命令行命令（推荐）

# 默认执行（stdio模式）
mcp-pty

# HTTP模式
mcp-pty --transport http --port 6420

# 帮助
mcp-pty --help

直接执行（开发）

# stdio模式
bun run packages/mcp-server/src/index.ts

# HTTP模式
bun run packages/mcp-server/src/index.ts --transport http

配置

配置优先级

1. 命令行参数（最高）：--transport, --port
2. XDG配置文件：~/.config/mcp-pty/config.json
3. 环境变量：MCP_PTY_DEACTIVATE_RESOURCES
4. 默认值：stdio传输，端口6420

XDG配置文件

~/.config/mcp-pty/config.json（或$XDG_CONFIG_HOME/mcp-pty/config.json）:

{
  "transport": "stdio",
  "port": 6420,
  "deactivateResources": false
}

传输层

• stdio：MCP客户端直接运行服务器作为子进程。保证在进程终止时自动清理。1:1客户端-服务器绑定。
• http：作为远程MCP服务器运行。支持多客户端并发会话。基于Hono实现HTTP服务器。通过Server-Sent Events (SSE) 实现实时通知。

环境变量

• MCP_PTY_DEACTIVATE_RESOURCES=true：启用动态工具供应，适用于不支持资源的客户端。
• XDG_CONFIG_HOME：XDG配置目录路径（默认：~/.config）

功能

• 持久PTY会话：跨多个命令调用的持续终端环境
• 双传输支持：stdio用于1:1绑定，HTTP用于支持多客户端的Server-Sent Events
• 高级命令解析：集成normalize-commands处理准确的bash语法（管道、重定向、环境变量）
• 会话管理：基于ULID的会话ID，具有空闲超时和优雅关闭
• 基于资源的接口：现代MCP资源（pty:// URI），并回退到工具模式
• 全面文本支持：完整的Unicode、ANSI转义序列和TUI应用程序
• 交互式输入：实时查询终端状态和处理输入
• 重新连接支持：HTTP传输在客户端重新连接时维持会话连续性
• 安全性：命令规范化、路径验证和资源隔离

API文档

MCP资源

• pty://status：显示活动会话和PTY进程的服务器状态
• pty://processes：列出当前会话中的所有PTY进程及其状态和退出码
• pty://processes/{processId}：特定PTY进程的完整输出历史记录
• pty://control-codes：所有可用控制码的参考（写入输入工具的命名码）

MCP工具

• start：创建新的PTY实例，执行命令并设置工作目录
  • 参数：command（字符串，必需），pwd（字符串，必需绝对路径）
  • 返回：PTY ID和即时输出
• kill：终止特定的PTY实例
  • 参数：processId（字符串，必需）
• list：列出PTY进程及其退出码
• read：读取PTY输出/屏幕缓冲区
• write_input：向PTY标准输入发送输入，返回屏幕状态
  • 模式：安全（输入+ctrlCode）或原始（数据）
  • 参数：processId，input（可选），ctrlCode（可选），data（可选），asCRLF（可选，针对Windows SSH）
  • 返回：屏幕，光标位置，退出码

错误代码

• 使用标准MCP错误响应。

开发

# 类型检查
bun check

# 代码检查
bun run lint

# 测试
bun test

此项目由bun init生成于Bun v1.2.22。Bun是一个快速的一体化JavaScript运行时。

致谢

使用opencode构建（opencode.ai + github sst/opencode）