byteforge-aegis-mcp

Только для чтения MCP-сервер для административного API ByteForge Aegis, развернутый как контейнер за nginx с аутентификацией Gatekeeper.

Почему

Агентам, работающим с Aegis и интеграциями арендаторов, постоянно требуется отвечать на вопрос «что на самом деле настроено в продакшене?» — установлен ли URL вебхука, включен ли allow_self_registration, какие сайты существуют, существует ли этот пользователь. До появления этого сервера на этот вопрос отвечали с помощью самодельных curl-запросов с мастер-ключом API, или не отвечали вовсе — однажды запрос на предоставление арендатора был подписан частично на основе предположения, потому что конфигурацию сайта нельзя было прочитать.

Related MCP server: readonly-mcp-akamai

Только для чтения по построению

Каждый инструмент соответствует GET. Клиент Aegis, который здесь обернут, также предоставляет create_site, update_site, delete_site, delete_user и другие — ни один из них здесь недоступен, и добавлять их не следует. Ценность этого сервера в том, что его можно передать агенту без возможности изменить состояние продакшена. Мутирующий сервер, если он когда-либо понадобится, должен быть в отдельном и отдельно авторизованном развертывании.

Инструменты

aegis_get_site и aegis_list_users принимают как домен, так и UUID. Административный API обращается к сайтам только по UUID (utils/identifiers.py resolve_site отклоняет не-UUID), поэтому домен сначала разрешается через публичный поиск by-domain — вызывающие почти всегда знают домен, а не UUID.

Секреты в ответах

Чтение сайтов включает полные значения tenant_api_key, webhook_secret и mailgun_api_key. Это был осознанный выбор @jmazzahacks вместо возврата булевых значений о наличии. Следствие: все, что здесь прочитано, попадает в транскрипт вызывающего агента, поэтому ответы не следует вставлять в тикеты или другие общие поверхности. AEGIS_MASTER_API_KEY охватывает все сайты на экземпляре.

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

См. example.env.

Локальная разработка

uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install -r requirements.txt

AEGIS_API_URL=https://aegis.example.com \
AEGIS_MASTER_API_KEY=... \
MCP_TRANSPORT=stdio \
python aegis_mcp_server.py

Виртуальное окружение находится в .venv/, а не в корне репозитория, как в соседних репозиториях Aegis — uv venv отказывается создавать его в непустой директории.

Чтобы протестировать его по сети так, как он развернут:

MCP_TRANSPORT=streamable-http FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=8931 \
AEGIS_API_URL=... AEGIS_MASTER_API_KEY=... python aegis_mcp_server.py &

curl -s -X POST http://127.0.0.1:8931/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

tools/list, который успешно выполняется без предшествующего initialize, является сигналом того, что включен режим без сохранения состояния.

Сборка и публикация

./build-publish.sh            # or --no-cache

Публикует ghcr.io/jmazzahacks/byteforge-aegis-mcp:<n> и :latest, затем обновляет VERSION. VERSION находится в .gitignore и полностью управляется скриптом — никогда не редактируйте его вручную.

В отличие от byteforge-aegis, этот образ не встраивает VERSION в себя, поэтому порядок записи после сборки в скрипте здесь корректен. Если когда-либо будет добавлена конечная точка версии, запись должна быть перемещена до docker build, иначе каждый образ будет сообщать версию на одну позади.

Развертывание

Работает за зонтичным виртуальным хостом mcp.<domain> с аутентификацией Gatekeeper auth_request. См. nginx-mcp-aegis.conf для блока location. Контейнер не публикует порт хоста — nginx обращается к нему по имени контейнера в общей сети Docker, что важно, поскольку мастер-ключ делает прямое раскрытие неприемлемым.

Транспорт

streamable-http с stateless_http=True. Не SSE: когда долгоживущий SSE GET Claude Code умирает, он переподключается без повторного запуска initialize, сервер сначала видит tools/call, и возникающий -32602 блокирует клиента до ручной перезагрузки /mcp. Stateless streamable-http не имеет состояния на сессию, которое можно было бы потерять, поэтому такой сбой структурно невозможен.