byteforge-aegis-mcp

一个只读的 MCP 服务器，通过 ByteForge Aegis 管理 API 运行，部署为 nginx 后方的容器，并带有 Gatekeeper 认证。

为什么

负责 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/ 而非仓库根目录，因为兄弟 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。容器不暴露主机端口——nginx 通过共享 Docker 网络上的容器名称访问它，这一点很重要，因为主密钥使得直接暴露不可接受。

传输协议

streamable-http 配合 stateless_http=True。不使用 SSE：当 Claude Code 长期存在的 SSE GET 连接死亡时，它会重新连接但不会重新运行 initialize，服务器会先收到 tools/call，由此产生的 -32602 错误会卡住客户端，直到手动重新加载 /mcp。无状态 streamable-http 没有每个会话的状态可丢失，因此该故障在结构上不可能发生。