byteforge-aegis-mcp

ByteForge Aegis管理APIに対する読み取り専用のMCPサーバーで、Gatekeeper認証付きのnginxの背後にコンテナとしてデプロイされています。

なぜ必要か

Aegisおよびテナント統合に取り組むエージェントは、「本番環境で実際に何が設定されているのか？」という問いに繰り返し答える必要があります。Webhook URLが設定されているか、allow_self_registrationが有効か、どのサイトが存在するか、このユーザーが存在するかなどです。このサーバーが登場する前は、そのような問いにはマスターAPIキーを使った手動のcurlで答えていました。あるいは全く答えられず、サイト設定を読み戻せなかったため、テナントプロビジョニングリクエストが主張に基づいて部分的に承認されたこともありました。

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はリポジトリルートではなく.venv/にあります。これは兄弟のAegisリポジトリとは異なります。uv venvは空でないディレクトリに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はgitignoreされており、スクリプトが完全に管理します。手動で編集しないでください。

byteforge-aegisとは異なり、このイメージはVERSIONを自身に焼き付けません。そのため、ここではスクリプトのビルド後の書き込み順序が正しく機能します。もしバージョンエンドポイントが追加された場合、書き込みはdocker buildの前に移動する必要があります。そうしないと、すべてのイメージが1バージョン古いものを報告することになります。

デプロイメント

Gatekeeper auth_request認証を使用するmcp.<domain>統合バーチャルホストの背後で動作します。ロケーションブロックについてはnginx-mcp-aegis.confを参照してください。コンテナはホストポートを公開しません。nginxは共有Dockerネットワーク上のコンテナ名で到達します。これは、マスターキーが直接の露出を許容しないため重要です。

トランスポート

stateless_http=Trueを使用したstreamable-http。SSEではありません。Claude Codeの長期間存続するSSE GETが停止すると、initializeを再実行せずに再接続し、サーバーが最初にtools/callを認識し、結果として-32602が発生して手動で/mcpをリロードするまでクライアントが動かなくなります。ステートレスなstreamable-httpには失うべきセッションごとの状態がないため、そのような障害は構造的に発生し得ません。