mcp-context-forge

环境要求

• Python 3.11 环境（官方 Dev Container 内置 Python 3.11）
• 必须提供 JWT_SECRET_KEY 与 AUTH_ENCRYPTION_SECRET，缺失则网关无法启动
• Docker 或 Podman，用于容器化部署（可选用 PostgreSQL + Redis 完整栈）
• 注意：arm64 目前不支持生产环境，Apple Silicon 需用 Rosetta 跑容器或改用 PyPI 安装
• 源码方式需要 make 与项目依赖（make venv install-dev）

安装与启动步骤

1. 1创建虚拟环境

   新建目录并创建隔离的 Python 虚拟环境，避免污染系统环境；Windows 用 .\.venv\Scripts\Activate.ps1 激活。

   mkdir mcpgateway && cd mcpgateway
   python3 -m venv .venv && source .venv/bin/activate

   复制

2. 2安装网关包

   从 PyPI 安装 mcp-contextforge-gateway；README 也给出 uv 方式，可先 uv venv 再 uv pip install。

   pip install --upgrade pip
   pip install mcp-contextforge-gateway

   复制

3. 3生成必要密钥

   网关在任何环境（含本地开发）都要求这两个密钥，用官方脚本生成真实密钥后再启动。

   python3 -m mcpgateway.scripts.init_secrets

   复制

4. 4准备 .env 文件

   复制示例配置并用脚本把生成的真实密钥回填到 .env，占位值会导致启动失败。

   cp .env.example .env
   python3 -m mcpgateway.scripts.init_secrets --patch-env .env

   复制

5. 5容器启动全栈

   在仓库根目录用 Make 目标启动 PostgreSQL、Redis、3 个网关副本与 Nginx；需已存在含真实密钥的 .env。

   make compose-up

   复制

6. 6源码方式运行

   从源码安装开发依赖并构建 Admin UI，然后由 gunicorn 在 4444 端口提供网关服务。

   make venv install-dev
   make serve

   复制

7. 7代理示例服务

   用 mcpgateway.translate 把标准输入输出的 MCP 时间服务器暴露为 SSE 服务，端口 8003，可换成 podman。

   python3 -m mcpgateway.translate --stdio "docker run --rm -i ghcr.io/ibm/fast-time-server:latest -transport=stdio" --expose-sse --port 8003

   复制

关键配置

如何确认成功

compose 启动后 Nginx 监听 :8080；执行 make serve 时 gunicorn 监听 :4444 即表示网关已启动成功。

常见问题

注意事项

• JWT_SECRET_KEY 与 AUTH_ENCRYPTION_SECRET 在包括本地开发在内的所有环境都是必填项，网关不会以占位值启动。
• docker compose up -d 默认不本地构建镜像，而是使用 GHCR 预构建镜像，本地构建需要 CI 才能产出的 wheel 闭包。
• 当前 arm64 不支持生产环境，M1/M2 等 Apple Silicon 机器建议用 Rosetta 或 PyPI 安装。
• 完整配置包含 300+ 环境变量，按认证、缓存、SSO、可观测性等分类，详见官方 Configuration Reference。