herdr-mcp

MCP-сервер, который даёт агенту программирования управление запущенным сеансом терминала Herdr: перечисление рабочих областей, вкладок, панелей и агентов, чтение вывода панелей, отправка запросов другим агентам, отправка нажатий клавиш, выполнение команд, ожидание состояния или вывода, а также разделение и закрытие панелей.

Это тонкий мост через stdio. Каждый инструмент обращается к CLI herdr, который уже говорит с сокетным API Herdr и отвечает JSON-конвертами. Никакого демона, портов, конфигурационных файлов и аутентификации нет.

Требования

• herdr установлен и находится в PATH (или укажите переменную HERDR_BIN с полным путём к нему).

• Запущенная сессия Herdr. Сервер работает с той сессией, которую CLI herdr определяет из окружения (HERDR_SOCKET_PATH / HERDR_SESSION).

• Python 3.12+ и uv.

Related MCP server: HT MCP Server

Запуск

Из локального клона:

uv run herdr-mcp

Прямо с GitHub, без клонирования:

uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcp

Процесс обслуживает MCP через stdio, поэтому ничего не выводит в stdout; журнал идет в stderr (HERDR_MCP_LOG_LEVEL=DEBUG для трассировки аргументов).

Конфигурация клиента

Claude Code:

claude mcp add herdr -- uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcp

Универсальный JSON mcpServers (Claude Desktop, Cursor, Codex и другие):

{
  "mcpServers": {
    "herdr": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/aelaguiz/herdr-mcp", "herdr-mcp"],
      "env": {}
    }
  }
}

Из локального клона вместо этого:

{
  "mcpServers": {
    "herdr": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/herdr-mcp", "herdr-mcp"]
    }
  }
}

Инструменты

Идентификаторы панелей выглядят как w17:p1, идентификаторы вкладок как w17:t1, идентификаторы рабочих областей как w17. Инструменты для агентов принимают идентификатор панели или имя агента. Каждый инструмент возвращает разобранный объект result из JSON-обёртки herdr; read_pane возвращает обычный текст.

Сбои из CLI (неизвестная панель, тайм-аут, неработающий сокет) возвращаются как ошибки MCP-инструментов с кодом и сообщением об ошибке от самого herdr, чтобы модель могла исправить своё поведение.

Безопасность

Без аутентификации, без песочницы, только локальный stdio. Любой клиент, который может запустить этот сервер, способен выполнять произвольные команды в ваших терминальных панелях и читать всё, что появляется на экране, включая содержимое панелей агентов. Подключайте его только к доверенным клиентам на вашей машине.

Окружение

Всё остальное в окружении передаётся без изменений — так CLI находит нужный сокет сессии.

Разработка

uv sync
uv run pytest -q

Модульные тесты запускают сервер через in-memory клиент SDK, взаимодействуя со скриптом-заглушкой herdr, поэтому они никогда не касаются реальной сессии.