Interactive Shell MCP

MCP-сервер для интерактивных сеансов оболочки с поддержкой TUI. Предоставляет ИИ-агентам постоянные терминалы, интерактивную навигацию по подсказкам, чтение отрисованного экрана и поиск по выводу.

Демонстрация

Зачем это нужно

Большинство инструментов для кодинга с ИИ запускают команды оболочки изолированно: каждая команда начинает новую оболочку, интерактивные подсказки невозможны, а TUI-приложения просто выводят «сырые» escape-коды. Этот MCP-сервер предоставляет постоянные PTY-сеансы с эмулятором виртуального терминала (@xterm/headless), чтобы агенты могли сохранять состояние оболочки, перемещаться по интерактивным подсказкам с помощью клавиш со стрелками и читать отрисованные экраны терминала как обычный текст.

Три режима вывода:

Быстрый старт

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

Затем спросите Claude: "отслеживай htop и скажи, что потребляет больше всего CPU"

Функции

• Чтение отрисованного экрана из TUI-приложений через @xterm/headless

• waitForIdle для всех инструментов чтения (больше не нужно угадывать с sleep)

• Поиск по экрану с использованием текста и регулярных выражений

• Извлечение прямоугольных областей с координатами строк/столбцов

• Белый список оболочек: 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 или любой CLI на базе inquirer/clack

• Мониторинг системы: htop, btop, top, iftop, duf с поиском процессов и извлечением областей

• DevOps TUI: lazydocker, lazygit, k9s, terraform console

• Удаленные сеансы: ssh на серверы, включая вложенные TUI-приложения через SSH

• CLI баз данных: psql, mysql, redis-cli, mongosh в интерактивном режиме

• Сетевые инструменты: netcat/ncat, nmap, airodump-ng, tcpdump

• REPL и отладчики: python, node, irb, gdb/lldb

• Текстовые редакторы: vim, nano, emacs -nw

Конфигурация MCP

Claude Code (CLI)

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

Claude Desktop

Добавьте в ~/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 Code / Cursor

Добавьте в настройки 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-оболочки с эмулятором виртуального терминала.

Возвращает { sessionId, cols, rows }

send_shell_input

Запись ввода в PTY. По умолчанию добавляет возврат каретки.

read_shell_output

Чтение вывода из PTY. Три режима: streaming (по умолчанию), snapshot, screen.

Режим screen возвращает позицию курсора, размеры терминала и состояние альтернативного буфера в метаданных.

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 для разработчиков, создающих интеграции. Конечные пользователи просто общаются со своим ИИ-агентом естественным образом.

Чтение 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 минут, автоматически удаляются

• Обнаружение выхода: Когда оболочка завершается, инструменты возвращают "Session exited with code N" в течение 60 секунд вместо общей ошибки о неверном ID

• Белый список оболочек: Можно запускать только известные оболочки (bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe). Неизвестные значения возвращаются к платформе по умолчанию.

Лицензия

MIT