director-shell-mcp

director-shell-mcp — это небольшой MCP-сервер для агентов, работающих в режиме директора. Он использует транспорт MCP stdio, чтобы предоставить контролируемый «запасной выход» для записи файлов, выполнения Python-кода для исследования данных, запуска shell-команд и контроля над фоновыми заданиями, запущенными отдельно. Команды запускаются только тогда, когда агент явно вызывает инструмент; сервер сам по себе не запускает оболочку.

Установка

Требуется Node.js 18 или новее. Из этого каталога:

npm install

Запустите сервер напрямую с помощью:

node C:/path/to/director-shell-mcp/index.js

Related MCP server: shell-0

Регистрация в OMP (основной способ)

Основным клиентом является среда Oh My Pi (OMP). Добавьте эту точную конфигурацию в пользовательский ~/.omp/agent/mcp.json (или в проектный .omp/mcp.json):

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

Для stdio-серверов поле type можно опустить. После редактирования конфигурации выполните /mcp reload, а затем /mcp test director-shell в OMP.

Регистрация в универсальном MCP-клиенте

Другие MCP-клиенты обычно принимают эквивалентную stdio-регистрацию:

{
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

Справочник инструментов

Все инструменты возвращают JSON-объект в текстовом содержимом MCP. Ошибки возвращаются как ошибки инструментов MCP с полем error в форме предложения.

shell_run

Выполняет команду до завершения. Параметры:

• command (строка, обязательный): текст команды.

• cwd (строка, необязательный): рабочая директория.

• timeout_ms (целое число, необязательный): по умолчанию 60 000; максимум 600 000.

• shell (powershell, cmd или bash, необязательный): по умолчанию PowerShell на Windows и Bash в остальных случаях.

Результат содержит exit_code, duration_ms и объекты stdout/stderr. Каждый поток включает до примерно 50 КиБ предварительного текста. Если поток превышает этот предел, его объект также включает truncated: true и full_output_path, указывающий на временный файл с полным потоком. Тайм-аут возвращает ошибку инструмента MCP с понятным сообщением и частичным результатом.

write_file

Записывает UTF-8 текст в абсолютный путь к файлу. Параметры:

• path (строка, обязательный): абсолютный путь к файлу.

• content (строка, обязательный): текст для записи.

• append (логическое, необязательный): добавлять вместо замены; по умолчанию false.

• create_dirs (логическое, необязательный): создавать отсутствующие родительские каталоги; по умолчанию true.

Результат содержит path, bytes_written, created (был ли файл до вызова) и appended.

edit_file

Заменяет текст в UTF-8 файле по абсолютному пути. Параметры:

• path (строка, обязательный): абсолютный путь к файлу.

• old_text (строка, обязательный): непустой текст для поиска.

• new_text (строка, обязательный): заменяющий текст.

• replace_all (логическое, необязательный): заменять все вхождения; по умолчанию false.

Без replace_all параметр old_text должен встречаться ровно один раз. Ноль или несколько совпадений возвращают ошибку инструмента MCP и оставляют файл без изменений. Результат содержит path и replacements.

run_python

Выполняет Python-код до завершения с ограниченным выводом и тайм-аутом. На Windows сервер сначала пробует запускатель py, затем python; на других системах сначала python3, затем python, кэшируя первую рабочую исполняемую программу. Параметры:

• code (строка, обязательный): исходный код Python.

• cwd (строка, необязательный): рабочая директория для процесса Python.

• timeout_ms (целое число, необязательный): по умолчанию 60 000; максимум 600 000.

• args (массив строк, необязательный): значения, передаваемые как sys.argv[1:].

Результат содержит exit_code, duration_ms, объекты stdout/stderr и python_executable. Потоки вывода ограничены и сбрасываются во временные файлы с тем же поведением, что и в shell_run. Тайм-аут возвращает ошибку инструмента MCP с понятным сообщением и частичным результатом.

job_start

Запускает отдельную команду, которая продолжает работу после возврата вызова инструмента. Параметры:

• command (строка, обязательный)

• cwd (строка, необязательный)

• shell (powershell, cmd или bash, необязательный)

• name (строка, необязательный, читаемая метка)

Результат содержит job_id, pid, log_paths (stdout, stderr и combined) и путь exit_marker. Метаданные сохраняются в формате JSON в %LOCALAPPDATA%/director-shell-mcp/jobs/<jobId>/, поэтому задания остаются обнаруживаемыми после перезапуска сервера.

job_status

Читает сохранённое состояние задания. Параметры:

• job_id (строка, обязательный): идентификатор, возвращённый job_start.

• tail_lines (целое число, необязательный): по умолчанию 40; максимум 1 000.

Результат содержит running, exit_code (когда доступен), runtime_ms, started_at и output_tail из объединённого журнала. Отдельная обёртка записывает exit_code.txt при завершении команды, сохраняя код выхода при перезапусках сервера.

job_kill

Завершает задание, запущенное этим сервером. Принимает job_id. На Windows использует taskkill /T /F для завершения дерева процессов обёртки. Уже завершённые задания остаются без изменений.

job_list

Перечисляет все допустимые сохранённые задания с их job_id, необязательным name, pid, состоянием running, кодом выхода и временем запуска.

grep_files

Рекурсивно ищет по абсолютному файлу или каталогу, используя JavaScript-регулярное выражение, без необходимости в ripgrep. Поиск пропускает node_modules, .git, bin, obj, dist и target, игнорирует файлы размером более 5 МиБ и двоичные файлы, а также останавливается при достижении лимита результатов. Параметры:

• pattern (строка, обязательный): исходный код JavaScript-регулярного выражения.

• path (строка, обязательный): абсолютный путь к файлу или каталогу.

• glob (строка, необязательный): простой фильтр имени файла с использованием * и ?.

• case_sensitive (логическое, необязательный): по умолчанию false.

• max_results (целое число, необязательный): по умолчанию 200; максимум 1 000.

• context_lines (целое число, необязательный): строки до и после каждого совпадения; по умолчанию 0; максимум 5.

Результат содержит matches с file, line_number, line, before и after, а также files_scanned и truncated. Недопустимые регулярные выражения возвращают ошибку инструмента MCP.

job_wait

Ожидает завершения существующего отдельного задания, опрашивая сохранённый маркер выхода каждые 500 мс. Параметры:

• job_id (строка, обязательный): идентификатор, возвращённый job_start.

• timeout_ms (целое число, необязательный): по умолчанию 60 000; максимум 600 000.

• tail_lines (целое число, необязательный): по умолчанию 40; максимум 1 000.

Результат имеет те же поля, что и job_status, и добавляет timed_out. Истечение времени ожидания, пока задание ещё выполняется, является нормальным результатом с timed_out: true, а не ошибкой MCP.

lock_acquire и lock_release

Предоставляют меж-агентский именованный мьютекс, сохраняемый в %LOCALAPPDATA%/director-shell-mcp/locks/. Имена содержат только буквы, цифры, _, . и - и имеют длину не более 64 символов. lock_acquire принимает name (обязательный), wait_ms (необязательный, по умолчанию 0, максимум 600 000) и необязательный note; возвращает name, UUID token и acquired_at. Захват использует атомарное создание каталога и восстанавливает блокировки, чей записанный процесс-владелец больше не жив. Ошибка удержания блокировки идентифицирует её pid, примечание (если есть) и длительность. lock_release принимает name и token владельца; неверные токены и свободные блокировки являются ошибками и не изменяют блокировку.

screenshot

Захватывает полный виртуальный экран или видимое окно верхнего уровня в PNG на Windows с помощью System.Drawing и Windows API. Параметры:

• target (screen или window, необязательный): по умолчанию screen.

• window_title (строка, обязательный для window): подстрока заголовка видимого окна без учёта регистра.

• output_path (абсолютный .png, необязательный): по умолчанию файл с меткой времени во временном выходном каталоге.

Результат содержит path, width, height, target и совпавший window_title для захвата окна. Возвращает понятную ошибку «не поддерживается» на не-Windows системах и понятную ошибку «нет совпадений», когда запрошенное окно не найдено.

process_list

Возвращает доступный только для чтения список процессов на Windows. Параметры:

• name_filter (строка, необязательный): подстрока имени процесса или пути к исполняемому файлу без учёта регистра.

• max_results (целое число, необязательный): по умолчанию 100; максимум 1 000.

Каждый процесс содержит pid и name, а также включает path, started_at и working_set_bytes, когда доступны. Результат также содержит truncated.

file_lockers

Сообщает о процессах, удерживающих открытый файл на Windows, через API Restart Manager. Принимает path (обязательный), который должен быть абсолютным путём к существующему файлу, и возвращает { path, lockers }. Каждый блокировщик содержит pid, app_name и app_type; незаблокированный файл — это успешный результат с пустым массивом lockers. На не-Windows системах возвращается понятная ошибка «не поддерживается».

Проверка

Запустите лёгкий сквозной смоук-тест (он использует только echo и PowerShell sleep):

npm run smoke

Смоук-тест запускает новый MCP-сервер через stdio, выполняет инициализацию, перечисляет все пятнадцать инструментов, проверяет запись файлов, точное редактирование текста, выполнение Python и передачу аргументов, завершение команд и захват вывода, проверяет отдельные задания во время их выполнения и после завершения, проверяет grep, wait, блокировки, скриншоты, список процессов и обнаружение блокировщиков файлов через Restart Manager, проверяет сохранение через job_list и проверяет обработку тайм-аута команд.

Лицензия

MIT