MCP 适配

@ai-zen/socket-pty/mcp 提供一套 MCP server（stdio 传输），把终端操作暴露为 MCP 工具。

定位：MCP 适配层是代理 Agent 与多个 socket-pty 进程之间的管理者和中转者：

• 不持有 socket-pty 进程 / 不持有 pty。
• 对外无状态：每个工具都带 address（socket 地址），自包含、无默认、无发现。
• 内部连接池复用：spawn 只创建孤儿进程，后续工具经 ConnectionPool（按地址复用连接）中转。

在 MCP 宿主中注册

{
  "mcpServers": {
    "socket-pty": {
      "command": "npx",
      "args": ["@ai-zen/socket-pty", "mcp"]
    }
  }
}

工具

工具	参数	返回
spawn	command, cwd?, cols?, rows?	address（字符串）
read	address, top?/bottom?/start?+end?	屏幕文本
write	address, action	写入成功（含字节数）
wait	address, match?, timeout?	匹配结果 + 屏幕
resize	address, cols, rows	成功/失败
status	address	{ running, exitCode, pid }
kill	address	成功/失败

spawn 的 command 与平台

spawn 的 command 与 CLI / 程序化接口一致，遵循平台约束：

• Windows 上应传 powershell.exe / cmd.exe（带 .exe 后缀），传 powershell / bash 会启动失败（node-pty 在 Windows 不对裸命令名做 PATH 搜索）。

spawn 的地址来源

spawn 由 MCP 管理器自分配本机临时端点，并在工具返回中给出该 address：

• Unix：unix:/tmp/pty-mcp-<pid>-<时间戳>-<随机>.sock
• Windows：tcp:127.0.0.1:<port>（先探测分配一个空闲端口）

该 address 由管理器分配并返回给调用方，作为后续工具的 address 参数使用。会话为孤儿进程（detached + unref），常驻直到被 kill；管理器 / Agent 退出都不影响其存活。

spawn 的自动分配仅存在于 MCP 内部——管理器既分配地址又持有使用，地址始终在其掌握中。对外提供端点（serve / createSocketPty）则必须显式定址。

编程式引入

import { serveMCP, MCPManager, ConnectionPool } from "@ai-zen/socket-pty/mcp";

• serveMCP()：启动标准 MCP server（stdio），连接宿主。
• MCPManager：提供 spawn / read / write / wait / resize / status / kill 方法，经内部 ConnectionPool（按地址复用连接，JSON-RPC 2.0）分发到对应 serve 进程。
• ConnectionPool：socket 连接池，按 address 缓存活跃连接，负责 JSON-RPC 2.0 信封封装、按 id 分发、超时兜底（默认 15000ms）。

也可通过 CLI 直接启动：socket-pty mcp（stdio 传输，不与宿主之外对话）。

相关文档

• 快速开始
• API 参考