hitl-mcp
MCP-сервер, через который агент задает вопросы человеку и ждет ответа; ответы приходят через MCP или HTTP API.
- 128 ★ репозитория
- Последний коммит
Расширенный доступ
Почему такой уровень
- По таймауту сервер сам отвечает на вопросы значениями по умолчанию, и подтверждение может пройти без человека.
- HTTP API по умолчанию слушает все интерфейсы на порту 3000.
Установка
- Работает в
Ручная установка
git clone https://github.com/ZenlixAI/hitl-mcp.git && cd hitl-mcp && npm install && npm run devВ README стоит заглушка `<your-repo-url>`, здесь подставлен адрес репозитория. Альтернатива: образ Docker из `Dockerfile`.
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- По таймауту сервер сам отвечает на вопросы значениями по умолчанию, и подтверждение может пройти без человека.
- HTTP API по умолчанию слушает все интерфейсы на порту 3000.
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
hitl-mcp хранит вопросы агента к человеку и выдает ответы обратно. Агент создает вопросы инструментом `hitl_ask` и сразу вызывает `hitl_wait`. Человек отвечает в своем интерфейсе: пункт из списка, несколько пунктов, текст, да или нет, число в диапазоне. Допустим частичный ответ, пропуск необязательных вопросов и отмена. Все вопросы привязаны к области вызова: идентификатор агента и идентификатор сессии из заголовков. Два агента не пересекаются, даже если задают одинаковые вопросы. Ожидание относится ко всей области, а не к одному вопросу, в режиме `progressive` оно срабатывает после каждого ответа. То же состояние доступно через HTTP API с префиксом `/api/v1`, поэтому панель оператора или бэкенд показывают вопросы и отправляют ответы. Хранилище по умолчанию в памяти, для нескольких процессов подключают Redis.
Для кого. Разработчикам агентных систем, которым нужна пауза на подтверждение человеком с отдельным интерфейсом для оператора.
Подходит, если
- Агент перед выкладкой должен получить от дежурного ответ да или нет.
- Нескольким агентам нужны уточнения, и ответы нельзя путать между сессиями.
- Оператор отвечает на вопросы агента в собственной веб-панели, а не в консоли.
- Подтверждение приходит порциями, и агент реагирует на каждую.
Не подходит, если
- Нужен готовый интерфейс с кнопками: готовой панели в проекте нет.
- Нужна очередь задач или оркестратор бизнес-процессов: сервер хранит только вопросы.
- Ответ на подтверждение нельзя подменять значением по умолчанию.
Пример запроса к агенту
Перед удалением веток спроси у меня через hitl_ask, подтверждаю ли я, и дождись ответа через hitl_wait.MCP
- Транспорт
- http
- Авторизация
- не нужна
Переменные окружения
MCP_URL- Публичный адрес сервера для метаданных MCP, по умолчанию `http://0.0.0.0:3000`.
HITL_STORAGE- Хранилище: `memory` по умолчанию или `redis`.
HITL_REDIS_URL- Адрес Redis, если выбрано `redis`.
Ограничения
Готового интерфейса для человека нет: вопросы забирает ваш бэкенд или панель через HTTP API. Установка идет из исходников или образа Docker. По истечении таймаута, по умолчанию 900 секунд, сервер сам отвечает на оставшиеся вопросы значениями по умолчанию, например `true` для логического вопроса, поэтому для критичных подтверждений задавайте `default_answer` явно. Память не переживает перезапуск, для долговременного хранения нужен Redis. Версия сервера в настройках по умолчанию 0.1.0.
Как отключить. Удалите запись `hitl-mcp` из конфигурации MCP-клиента и остановите сервер или контейнер. Если подключали Redis, ключи с префиксом `hitl` очистите отдельно.
Частые вопросы
Как запустить hitl-mcp локально?
Клонируйте репозиторий, выполните `npm install` и `npm run dev`. Сервер слушает порт 3000: MCP на `/mcp`, HTTP API на `/api/v1`.
Какие типы вопросов есть?
Пять типов: `single_choice`, `multi_choice`, `text`, `boolean` и `range`. У варианта `single_choice` могут быть дополнительные поля, обязательные проверяются.
Что произойдет, если человек не ответит?
После таймаута сервер сам ответит значениями по умолчанию и пометит такие ответы признаком автоответа. Для логического вопроса по умолчанию берется `true`.
Как включить Redis?
Задайте `HITL_STORAGE=redis` и `HITL_REDIS_URL`. Тогда таймауты и ожидание работают между несколькими экземплярами сервера.
Как не смешивать вопросы разных агентов?
Передавайте заголовки `x-agent-identity` и `x-agent-session-id`: вместе они задают область вызова, и вопросы разных областей не пересекаются.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
MCP-серверыMCP-сервер на Node.js, через который агент управляет устройствами Home Assistant и правит его автоматизации
Open Agent Email — свой почтовый сервер для ИИ-агентов: ящики, ответы в ветке письма, одобрение человеком, вебхуки и MCP на 96 инструментов
Hycli по адресу сайта и цели собирает типизированный CLI и MCP-инструменты, работая в вашей браузерной сессии без утечки куки.
MCP-сервер Apideck: агент работает с более чем 200 бизнес-системами: бухгалтерией, HRIS, CRM и файлами через единый API
MCP-сервер для Home Assistant: агент читает состояние умного дома и управляет устройствами через ваш экземпляр
MCP-сервер для управления Windows: агент открывает приложения, кликает и печатает, читает состояние окон и интерфейса, работает с файлами и PowerShell
Коротко о README
README объясняет модель вопросов, область вызова и режимы ожидания, затем перечисляет MCP-инструменты, маршруты HTTP API и переменные окружения. Отдельные разделы посвящены архитектуре, метрикам и эксплуатации.