dogeheng/MCP-server-controller

mcp-terminal 让任何 MCP 客户端（Manus、Claude Desktop、Cursor、自研 Agent……）通过 stdio 在本机创建并控制终端会话：启动命令、按游标增量读取输出、向交互式程序写入、判断“在跑 / 等输入 / 已结束”，并在需要时中断或终止整棵进程树。所有会话默认运行在 macOS Seatbelt 沙箱里，沙箱可写目录可以由你指定。
它不是把单次 exec 包成一个 Tool，而是一个有状态的终端服务：会话里的 cd、export、虚拟环境会保留；长任务不会阻塞调用方；输出不会因为没及时读取而丢失；客户端断开或服务崩溃后，残留进程会被找回并清理。
## 特性一览
| 方面 | 做法 |
| 会话模型 | PTY（node-pty）为默认后端，另有 pipe 后端用于分离 stdout/stderr；每个会话有 sessionid，也可起名（name="devserver"）后用名字引用 |
| 命令边界与退出码 | 向 zsh / bash 注入 OSC 133 shell 集成标记（带每会话随机 nonce，程序伪造的标记会被忽略），terminalexec 返回这条命令自己的输出与退出码，并跟踪 cwd |
| 增量输出 | 单调递增的字节游标；内存环形缓冲 + 磁盘分段溢写；省略游标即“从上次读到的地方继续”；超长输出头尾保留、中间给出可分页的游标 |
| 不阻塞的等待 | until=["commanddone"|"exit"|"input"|"idle: "|"pattern: "] 在服务端等待，带超时、取消和进度通知；默认最多等 10 秒就返回“仍在运行” |
| 交互输入 | terminalsend 支持文本、submit、按键名（C-c、Up、Escape、F5……，自动适配应用光标模式）；检测“等待输入”（前台进程阻塞在 tty 读 + 提示符启发式） |
| 全屏程序 | 基于 @xterm/headless 维护屏幕模型；vim、top、less 等进入备用屏幕时自动返回渲染后的屏幕快照 |
| 输出整理 | 默认去掉 ANSI 颜色与控制序列，\r 进度条折叠为最终状态；view="raw" 可取原始内容 |
| 沙箱 | 每个会话用 sandbox-exec 套一份动态生成的 Seatbelt 配置：可读大部分文件，只能写会话 cwd 和你允许的目录；凭据目录不可读；网络可设 allow / localhost / deny |
| 命令策略 | tree-sitter-bash 解析整条命令（管道、&&、$( )、sh -c "…"、env/xargs/timeout 包装都会展开），内置危险命令规则 + 用户规则，整体取最严 |
| 审批 | 需审批的命令依次尝试：MCP elicitation（客户端支持时）→ macOS 原生对话框 → termctl approve 审批票据；审批与参数摘要绑定、一次性、会过期 |
| 环境变量与脱敏 | 默认白名单继承环境变量，TOKEN、KEY、AWS 等被剥离（rc 文件里再导出的也会在会话内 unset），其值和常见令牌格式在输出中被替换为 [REDACTED:…] |
| 审计 | JSONL 审计日志，按实例做哈希链，termctl audit verify 可检测篡改；只记录输出哈希，不记录输出内容 |
| 生命周期 | 关闭会话时按 SIGHUP → SIGTERM → SIGKILL 升级，覆盖进程组、tty 上的作业和已脱离的 nohup 进程；SQLite 注册表记录会话与观察到的进程组，服务崩溃重启后自动对账并清理孤儿进程 |
## Agent Skill
配套的免费技能包见 skills/mcp-terminal-controller。它指导 Agent 选择一次性命令或持久会话、续读长任务、处理交互输入与审批，并在完成后清理会话。技能包与本项目同为 MIT 许可证。
将 skills/mcp-terminal-controller 文件夹放到客户端支持的 skill 目录，或通过支持该格式的市场加载。技能包不包含 MCP 服务，也不会自动获得终端权限：仍需按下文安装本地服务，并在支持本地 stdio MCP 的客户端中配置连接。macOS 平台限制不变。
## 环境要求
macOS（已在 macOS 26.5 / Apple Silicon 上测试；所用 Seatbelt 规则在较早版本上同样可用，但未逐一验证），Node.js 22.13 及以上（需要内置的 node:sqlite）。不需要 Xcode：node-pty 自带 macOS 预编译二进制，bash 解析器使用 WASM。
## 安装与自检
bash
git clone https://github.com/dogeheng/MCP-server-controller.git
cd MCP-server-controller
npm install # postinstall 会修复 node-pty spawn-helper 的执行权限
npm run build
node dist/bin/termctl.js doctor
doctor 会检查 Node 版本、sandbox-exec、PTY 能否启动、解析器能否加载、当前生效的沙箱与审批配置。可以 npm link 把 mcp-terminal 和 termctl 两个命令放进 PATH，下文为简洁起见直接写命令名。
## 接入 MCP 客户端（stdio）
最简单的方式是让 termctl 生成配置片段，它会写入当前 Node 的绝对路径（GUI 应用启动时 PATH 往往不完整）：
bash
termctl client-config --workspace ~/Projects/demo
输出形如：
json
"mcpServers": {
"terminal": {
"command": "/Users/you/.n/bin/node",
"args": ["/path/to/mcp-terminal/dist/bin/mcp-terminal.js", "--workspace", "/Users/you/Projects/demo"]
Manus：在 Manus 的自定义 MCP（Custom MCP）里选择以 JSON / 命令方式添加，粘贴上面的 mcpServers 片段即可（stdio 形式为 command + args + 可选 env）。添加后先让 Agent 调一次 terminallist 或 terminalrun {"command":"pwd"} 验证。已在 Manus Studio 桌面端实测：服务由本机的 manus-computer-operator 以 stdio 方式拉起，运行在这台 Mac 上；服务进程退出后，下一次工具调用会自动重新拉起。Manus 目前不声明 elicitation 能力，所以需要审批的命令会弹出 macOS 原生对话框，超时后退回到 termctl approve 。修改代码并 npm run build 后，在活动监视器里结束名为 node 且命令行含 dist/bin/mcp-terminal.js 的进程，Manus 下次调用时就会加载新版本。完整测试步骤见 TESTING.md。
Claude Desktop：把片段合并进 ~/Library/Application Support/Claude/claudedesktopconfig.json。其他客户端：只要支持 stdio 传输，配置方式相同。