byteforge-aegis-mcp

ByteForge Aegis 관리 API를 위한 읽기 전용 MCP 서버로, Gatekeeper 인증을 사용하는 nginx 뒤에 컨테이너로 배포됩니다.

왜 필요한가

Aegis 및 테넌트 통합 작업을 수행하는 에이전트는 "프로덕션에 실제로 구성된 것이 무엇인가?"라는 질문에 반복적으로 답해야 합니다. — 웹훅 URL이 설정되어 있는지, allow_self_registration이 켜져 있는지, 어떤 사이트가 존재하는지, 해당 사용자가 존재하는지. 이 서버가 있기 전에는 이 질문에 마스터 API 키를 담은 수동 curl 명령어로 답하거나, 전혀 답하지 못했습니다. 사이트 구성을 읽어낼 수 없었기 때문에 한 번은 단정(assertion)에 기반하여 테넌트 프로비저닝 요청이 승인되기도 했습니다.

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"}'

initialize 없이 성공하는 tools/list는 상태 비저장 모드가 켜져 있다는 신호입니다.

빌드 및 게시

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

ghcr.io/jmazzahacks/byteforge-aegis-mcp:<n> 및 :latest를 게시한 후 VERSION을 업데이트합니다. VERSION은 git에 무시되며 스크립트가 전적으로 소유합니다. 수동으로 편집하지 마세요.

byteforge-aegis와 달리 이 이미지는 VERSION을 자체적으로 포함시키지 않으므로, 스크립트의 쓰기-후-빌드 순서가 여기서는 올바릅니다. 버전 엔드포인트가 추가될 경우 쓰기는 docker build 이전으로 이동해야 하며, 그렇지 않으면 모든 이미지가 한 버전 뒤처진 값을 보고하게 됩니다.

배포

Gatekeeper auth_request 인증을 사용하는 mcp.<domain> 통합 vhost 뒤에서 실행됩니다. 위치 블록은 nginx-mcp-aegis.conf를 참조하세요. 컨테이너는 호스트 포트를 게시하지 않습니다. nginx는 공유 도커 네트워크에서 컨테이너 이름으로 접근합니다. 마스터 키가 직접 노출을 허용하지 않기 때문에 이 방식이 중요합니다.

전송 방식

stateless_http=True를 사용한 streamable-http입니다. SSE가 아닙니다. Claude Code의 장기 실행 SSE GET이 끊어지면 initialize를 다시 실행하지 않고 재연결되고, 서버는 tools/call을 먼저 수신하며, 결과적으로 발생하는 -32602 오류는 수동으로 /mcp를 다시 로드할 때까지 클라이언트를 멈추게 합니다. 상태 비저장 streamable-http는 세션별 상태가 없으므로 이러한 장애가 구조적으로 불가능합니다.