Interactive Shell MCP

交互式外壳MCP

MCP服务器，用于支持TUI的交互式shell会话。为AI代理提供持久终端、交互式提示导航、渲染屏幕阅读和输出搜索。

演示

为什么存在

大多数AI编码工具独立运行shell命令：每个命令都会启动一个新的shell，交互式提示是不可能的，TUI应用程序只会转储原始转义码。此MCP服务器通过虚拟终端仿真器提供持久的PTY会话(@xterm/headless)因此，代理可以维护shell状态，使用箭头键导航交互式提示，并将渲染的终端屏幕读取为干净的文本。

三种输出模式：

快速开始

git clone https://github.com/lightos/interactive-shell-mcp.git
cd interactive-shell-mcp
npm install && npm run build
claude mcp add interactive-shell node dist/src/server.js

然后问克劳德： *“监视htop并告诉我哪些CPU使用最多”*

特性

• 通过TUI应用程序读取渲染屏幕 @xterm/headless
• waitForIdle 在所有阅读工具中（不再在睡眠中猜测）
• 使用文本和正则表达式模式匹配进行屏幕搜索
• 基于行/列坐标的矩形区域提取
• Shell别名：bash、zsh、fish、sh、dash、ksh、powershell.exe、pwsh、cmd.exe
• 空闲10分钟后自动清理，进程退出后60秒检测退出代码
• 跨平台：Unix/Linux/macOS+Windows

用例

• 交互式脚手架和迁移: npx create-next-app, drizzle-kit push, prisma migrate, npm init，或任何基于查询器/clack的CLI
• 系统监控: htop, btop, top, iftop, duf 具有过程搜索和区域提取功能
• DevOps TUI: lazydocker, lazygit, k9s, terraform console
• 远程会话: ssh 进入服务器，包括通过SSH嵌套的TUI应用程序
• 数据库CLIs: psql, mysql, redis-cli, mongosh 在交互模式下
• 网络工具: netcat/ncat, nmap, airodump-ng, tcpdump
• REPL和调试器: python, node, irb, gdb/lldb
• 文本编辑器: vim, nano, emacs -nw

MCP配置

克劳德代码（CLI）

claude mcp add interactive-shell node /path/to/interactive-shell-mcp/dist/src/server.js

克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

VS代码/光标

添加到MCP设置(.vscode/mcp.json 或 ~/.cursor/mcp.json):

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

工具参考

start_shell_session

使用虚拟终端模拟器生成一个新的PTY shell。

退货 { sessionId, cols, rows }

send_shell_input

将输入写入PTY。默认情况下附加回车符。

read_shell_output

读取PTY的输出。三种模式：流媒体（默认）、快照、屏幕。

屏幕模式返回元数据中的光标位置、终端尺寸和备用缓冲区状态。

get_screen_region

从屏幕的矩形区域提取文本。

get_screen_cursor

获取光标位置和当前行文本。

退货 { cursor: { x, y }, currentLine, isAlternateBuffer }

search_screen

在终端屏幕上搜索文本或正则表达式。最多返回50场比赛。

退货 { results: [{ row, col, text }], count }

list_sessions

列出所有具有元数据的活动会话。没有参数。

退货 { sessions: [{ sessionId, shell, cols, rows, isAlternateBuffer, idleSeconds }] }

resize_shell

调整活动会话的终端大小。

end_shell_session

关闭PTY并清理资源。

用法示例

这些显示了构建集成的开发人员的MCP工具调用模式。最终用户只是自然地与他们的AI代理交谈。

阅读TUI应用程序

await send_shell_input(sessionId, "htop");
const { output, metadata } = await read_shell_output(sessionId, {
  mode: "screen",
  waitForIdle: 500
});
// output: rendered htop as clean text (CPU bars, process table, etc.)
// metadata.isAlternateBuffer: true (htop uses alternate screen)

// Extract just the process list (rows 6-30)
const processes = await get_screen_region(sessionId, {
  startRow: 6, startCol: 0, endRow: 30, endCol: 120,
  trimWhitespace: true
});

导航交互式提示

// Send arrow keys and enter in raw mode
await send_shell_input(sessionId, "\\x1b[B", { raw: true });  // down arrow
await send_shell_input(sessionId, " ", { raw: true });         // space to select
await send_shell_input(sessionId, "\\r", { raw: true });       // enter to confirm

// Read what the prompt looks like now
const screen = await read_shell_output(sessionId, {
  mode: "screen", waitForIdle: 300
});

等待命令输出

await send_shell_input(sessionId, "npm install");
const output = await read_shell_output(sessionId, {
  waitForIdle: 1000  // wait for 1s of silence
});

搜索内容

// Find all error lines
const errors = await search_screen(sessionId, {
  pattern: "error|Error|ERROR",
  regex: true,
  waitForIdle: 500
});
// [{ row: 12, col: 0, text: "Error" }, ...]

会话行为

• 自动清理：空闲时间超过10分钟的会话将自动处理
• 出口检测：当shell退出时，工具返回 "Session exited with code N" 持续60秒，而不是一般的无效ID错误
• 贝壳合金：只能生成已知的shell（bash、zsh、fish、sh、dash、ksh、powershell.exe、pwsh、cmd.exe）。未知值将恢复为平台默认值。

许可证

麻省理工学院