交互式Shell MCP

提供通过node-pty实现的完整终端模拟支持的交互式shell会话管理的MCP服务器。

概述

交互式Shell MCP（模型上下文协议）服务器使LLMs能够创建和管理交互式shell会话。它提供了持久的shell环境，在其中可以顺序执行命令并保持状态，类似于人类使用终端的方式。

特性

• 创建和管理多个并发shell会话
• 完整的终端模拟，具有正确的TTY支持
• 跨命令的持久shell状态
• 支持交互式程序（如vim、nano等）
• 跨平台支持（Unix/Linux/macOS上的bash，Windows上的PowerShell）
• 智能输出处理，自动模式检测
• 快照模式，用于持续更新的终端应用程序
• 可配置的输出大小限制，以防止内存溢出
• 自动检测终端控制序列

可用工具

start_shell_session

启动一个新的PTY shell，并返回一个唯一的会话ID。

• 输入：无
• 输出：{ sessionId: string }

send_shell_input

将输入写入PTY，并自动处理换行符。

• 输入：
  • sessionId (string)：shell的会话ID
  • input (string)：要发送到shell的输入
• 输出：成功确认

read_shell_output

从PTY进程返回输出，支持两种模式：

• 流模式（默认）：返回自上次读取以来的缓冲输出，并清除缓冲区

• 快照模式：返回当前终端屏幕状态而不清除（适用于top、htop、airodump-ng等应用）

• 输入：

  • sessionId (string)：shell的会话ID
  • mode (string, 可选)：输出模式 - "streaming"（默认）或"snapshot"
  • maxBytes (number, 可选)：要返回的最大字节数（默认：100KB，最大：1MB）
  • snapshotSize (number, 可选)：要捕获的快照缓冲区大小（默认：50KB）

• 输出：

  {
    "output": "string",
    1. "metadata": {
      "mode": "streaming|snapshot",
      "totalBytesReceived": number,
      "truncated": boolean,
      "originalSize": number,
      "isSnapshot": boolean,
      "snapshotTime": number
    }
  }
  

end_shell_session

关闭PTY并清理资源。

• 输入：
  • sessionId (string)：要关闭的shell的会话ID
• 输出：成功确认

安装

npm install
npm run build

MCP配置

要将此MCP服务器与Claude Desktop或VS Code一起使用，请在您的MCP设置文件中添加以下配置：

Claude Desktop

在macOS上添加到~/Library/Application Support/Claude/claude_desktop_config.json，或在Windows上添加到%APPDATA%\Claude\claude_desktop_config.json：

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

VS Code (Cursor)

添加到~/.cursor/mcp.json：

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

请将/path/to/interactive-shell-mcp替换为您实际安装的路径。

使用示例

注意：下面的示例演示了LLM如何与这个MCP服务器交互。这些不是可以直接运行的JavaScript代码，而是展示了预期的工具调用模式。

处理高输出命令

当处理产生大量输出或持续刷新屏幕的命令（如airodump-ng、htop、top）时，使用快照模式：

// 示例展示LLM如何调用这些工具：
// 启动一个会话
const { sessionId } = await start_shell_session();

// 运行airodump-ng
await send_shell_input(sessionId, "sudo airodump-ng wlan0mon");

// 在快照模式下读取输出以获取当前屏幕状态
const result = await read_shell_output(sessionId, {
  mode: "snapshot"
});

处理常规命令

对于生成流式输出的普通命令：

// 示例展示LLM如何调用这些工具：
// 使用默认的流模式
const output = await read_shell_output(sessionId);

// 或者明确设置非常大输出的大小限制
const output = await read_shell_output(sessionId, {
  maxBytes: 50000  // 只返回最后50KB
});

输出模式解释

• 流模式：适合常规命令。返回自上次读取以来的所有输出，并清除缓冲区。
• 快照模式：适合持续更新的应用程序。返回当前终端屏幕状态而不清除。当服务器检测到终端控制序列时，会自动切换到此模式。

调试

为了独立运行服务器进行调试：

npm start

这将在标准I/O上启动服务器，主要用于测试安装和调试问题。

许可证

MIT </中文翻译>