ghcr.io/ibm/mcp-context-forge:ef2ded1685eb6d2ea772d0328b07788803a6702a

ContextForge

一个开源注册中心和代理，用于联合MCP、A2A和REST/gRPC API，提供集中式治理、发现和可观测性。优化智能体（Agent）和工具调用，并支持插件。

ContextForge 是一个开源注册中心和代理，可将工具、智能体（Agent）和API联合到一个简洁的端点，供您的AI客户端使用。它在您的AI基础设施中提供集中式治理、发现和可观测性：

• 工具网关（Tools Gateway） — MCP、REST、gRPC到MCP的转换以及TOON压缩
• 智能体网关（Agent Gateway） — A2A协议、OpenAI兼容和Anthropic智能体路由
• API网关（API Gateway） — REST服务的速率限制、身份验证、重试和反向代理
• 插件可扩展性（Plugin Extensibility） — 40多种插件，用于额外的传输方式、协议和集成
• 可观测性（Observability） — 使用Phoenix、Jaeger、Zipkin和其他OTLP后端的OpenTelemetry追踪

它作为完全兼容的MCP服务器运行，可通过PyPI或Docker部署，并通过Redis支持的联合和缓存扩展到Kubernetes上的多集群环境。

---

目录

• 概述与目标
• 快速开始 - PyPI
• 快速开始 - 容器
• VS Code开发容器
• 安装
• 升级
• 配置
• 运行
• 云部署
• API参考
• 测试
• 项目结构
• 开发
• 故障排除
• 贡献

---

📌 快速链接

---

概述与目标

ContextForge 是一个开源注册中心和代理，用于联合任何https://modelcontextprotocol.io（MCP）服务器、A2A服务器或REST/gRPC API，提供集中式治理、发现和可观测性。它优化智能体和工具调用，并支持插件。有关更多详细信息，请参见https://ibm.github.io/mcp-context-forge/architecture/roadmap/。

目前支持：

• 跨多个MCP和REST服务的联合
• A2A（智能体到智能体）集成，用于外部AI智能体（OpenAI、Anthropic、自定义）
• 通过基于自动反射的服务发现实现gRPC到MCP的转换
• 将遗留API虚拟化为符合MCP的工具和服务器
• 通过HTTP、JSON-RPC、WebSocket、SSE（支持可配置的保活机制）、标准输入输出（stdio）和可流式HTTP进行传输
• 用于实时管理、配置和日志监控的管理UI（支持隔离环境部署）
• 内置身份验证、重试和速率限制，支持用户范围的OAuth令牌和无条件X-Upstream-Authorization头
• 使用Phoenix、Jaeger、Zipkin和其他OTLP后端的OpenTelemetry可观测性
• 通过Docker或PyPI实现可扩展部署，支持Redis后端缓存和多集群联合

有关即将推出的功能列表，请查看https://ibm.github.io/mcp-context-forge/architecture/roadmap/

---

🔌 具有协议灵活性的网关层

• 联合任何MCP服务器或REST API
• 允许您选择MCP协议版本（例如，2025-11-25）
• 为多样化后端提供单一、统一的接口

🧩 REST/gRPC服务的虚拟化

• 将非MCP服务包装为虚拟MCP服务器
• 通过最少配置注册工具、提示词和资源
• 通过服务器反射协议实现gRPC到MCP的转换
• 自动服务发现和方法内省

🔁 REST到MCP工具适配器

• 将REST API适配为工具，具有：

• 自动JSON Schema提取

• 支持标头、令牌和自定义身份验证

• 重试、超时和速率限制策略

🧠 统一注册中心

• 提示词（Prompts）：Jinja2模板、多模态支持、回滚/版本控制
• 资源（Resources）：基于URI的访问、MIME检测、缓存、SSE更新
• 工具（Tools）：原生或适配的，具有输入验证和并发控制

📈 管理UI、可观测性与开发体验

• 管理UI使用HTMX 2.0.3（捆绑）+ Alpine.js构建
• 实时日志查看器，具有过滤、搜索和导出功能
• 身份验证：基本认证（Basic）、JWT或自定义方案
• 结构化日志、健康检查端点、指标
• 7000+测试、Makefile目标、热重载、提交前钩子

🔍 OpenTelemetry可观测性

• 支持OpenTelemetry（OTLP）协议的厂商无关追踪
• 多后端支持：Phoenix（专注LLM）、Jaeger、Zipkin、Tempo、DataDog、New Relic
• 跨联合网关和服务的分布式追踪
• 工具、提示词、资源和网关操作的自动 instrumentation
• LLM特定指标：令牌使用量、成本、模型性能
• 禁用时零开销，支持优雅降级

有关Phoenix、Jaeger和其他后端的设置指南，请参见**https://ibm.github.io/mcp-context-forge/manage/observability/**。

---

快速开始 - PyPI

ContextForge 在 https://pypi.org/project/mcp-contextforge-gateway/ 上发布，包名为 mcp-contextforge-gateway。

---

[!WARNING] JWT_SECRET_KEY 和 AUTH_ENCRYPTION_SECRET 在每个环境中都是必需的——包括本地开发。 网关没有这些密钥将无法启动。首次运行前，使用 python3 -m mcpgateway.scripts.init_secrets 生成真实密钥。

简明步骤 — 使用 uv 的单命令：

# 1️⃣ 生成安全密钥（创建 .env.secrets）
python3 -m mcpgateway.scripts.init_secrets

# 2️⃣ 导出生成的值
export JWT_SECRET_KEY="$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)"
export AUTH_ENCRYPTION_SECRET="$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)"

# 3️⃣ 启动网关
JWT_SECRET_KEY="$JWT_SECRET_KEY" \
AUTH_ENCRYPTION_SECRET="$AUTH_ENCRYPTION_SECRET" \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
PLATFORM_ADMIN_EMAIL=admin@example.com \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

📋 前提条件

• Python ≥ 3.11
• curl + jq - 仅用于最后一个冒烟测试步骤

1 - 安装与运行（适合复制粘贴）

快速启动 - 容器

使用来自GHCR的官方OCI镜像，支持Docker或Podman。 请注意：目前生产环境不支持arm64架构。如果您在例如搭载Apple Silicon芯片（M1、M2等）的MacOS上运行，可以使用Rosetta运行容器，或通过PyPi安装。

🚀 快速启动 - Docker Compose

☸️ 快速入门 - Helm（Kubernetes）

使用企业级功能部署到 Kubernetes：

# 添加 Helm 仓库（待可用时）
# helm repo add mcp-context-forge https://ibm.github.io/mcp-context-forge
# helm repo update

# 目前，请使用本地图表
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge/charts/mcp-stack

# 首先生成密钥
python3 -m mcpgateway.scripts.init_secrets
JWT_SECRET=$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)
ENC_SECRET=$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)

# 使用 PostgreSQL 安装（默认）
# 重要：替换为真实密码 — 生产环境中不要使用 'changeme'
helm install mcp-gateway . \
--set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \
--set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD= \
--set mcpContextForge.secret.BASIC_AUTH_PASSWORD= \
--set "mcpContextForge.secret.JWT_SECRET_KEY=${JWT_SECRET}" \
--set "mcpContextForge.secret.AUTH_ENCRYPTION_SECRET=${ENC_SECRET}"

# 检查部署状态
kubectl get pods -l app.kubernetes.io/name=mcp-context-forge

# 端口转发以访问管理界面
kubectl port-forward svc/mcp-gateway-mcp-context-forge 4444:80
# 访问：http://localhost:4444/admin

# 生成 API 令牌（从 pod 环境中读取 JWT_SECRET_KEY）
kubectl exec deployment/mcp-gateway-mcp-context-forge -- \
python3 -m mcpgateway.utils.create_jwt_token \
--username admin@yourcompany.com --exp 10080 --secret "${JWT_SECRET}"

[!NOTE] SSRF 说明：Helm 默认启用严格的 SSRF 设置（SSRF_ALLOW_PRIVATE_NETWORKS=false）。如果您注册集群内工具 URL（例如 fast-time 或 fast-test 服务），请通过 mcpContextForge.config.SSRF_ALLOWED_NETWORKS 仅允许您的集群 CIDR，或者对于仅限本地的基准测试设置，可临时将 SSRF_ALLOW_PRIVATE_NETWORKS 设置为 true。详见 docs/docs/manage/configuration.md#ssrf-protection 和 docs/docs/deployment/helm.md。

企业级功能：

• 🔄 自动扩缩容 - 基于 CPU/内存目标的 HPA
• 🗄️ 数据库选择 - PostgreSQL（生产环境）、SQLite（开发环境）
• 📊 可观测性 - Prometheus 指标、OpenTelemetry 追踪
• 🔒 安全性 - RBAC、网络策略、密钥管理
• 🚀 高可用性 - 带 Redis 集群的多副本部署
• 📈 监控 - 内置 Grafana 仪表板和告警

✏️ Docker/Podman 提示

• .env 文件 - 将所有 -e FOO= 行放入一个文件中，并用 --env-file .env 替换它们。参考提供的 https://github.com/IBM/mcp-context-forge/blob/main/.env.example。
• 固定标签 - 为了可重现构建，使用明确的版本（例如 1.0.0-RC-3）而非 latest。
• JWT 令牌 - 在运行的容器中生成一个（从容器环境读取密钥）：

docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token \
--username admin@example.com --exp 10080 --secret "${JWT_SECRET_KEY}"

• 升级 - 停止、移除容器，然后使用相同的 -v $(pwd)/data:/data 挂载重新运行；数据库和配置将保持不变。

📚 完整配置参考

有关按类别（身份验证、缓存、SSO、可观测性等）组织的 300 多个环境变量的完整列表，请参阅 **https://ibm.github.io/mcp-context-forge/manage/configuration/**。

---

运行

快速参考

make test # 运行单元测试
make lint # 运行所有代码检查工具
make doctest # 运行文档测试
make coverage # 生成覆盖率报告

有关文档测试的详细信息，请参见https://ibm.github.io/mcp-context-forge/development/doctest-coverage/。

---

项目结构

mcpgateway/ # 核心 FastAPI 应用
├── main.py # 入口点
├── config.py # Pydantic Settings 配置
├── db.py # SQLAlchemy ORM 模型
├── schemas.py # Pydantic 验证模式
├── services/ # 业务逻辑层（50+ 服务）
├── routers/ # HTTP 端点定义
├── middleware/ # 横切关注点
└── transports/ # SSE、WebSocket、标准输入输出、可流式 HTTP

tests/ # 测试套件（7,000+ 测试用例）
docs/docs/ # 完整文档（MkDocs）
charts/ # Kubernetes/Helm 图表
plugins/ # 插件框架及实现
mcp-servers/ # 示例/测试 MCP 服务器（见下方说明）

[!NOTE] mcp-servers/ 目录包含不受支持的示例和测试服务器，其中大多数源自社区贡献，仅用于演示和集成测试目的。它们通常缺乏会话管理、持久化状态、多租户、身份验证以及其他生产环境所需的功能。这些服务器未经过与 ContextForge 核心代码库相同的审查、测试和安全验证流程，不应在生产环境中运行。

安全： 切勿在本地文件系统上直接运行不受信任的 MCP 服务器。始终使用具有受限功能的沙箱、容器或微虚拟机（如 gVisor、Fire***er）。注册任何远程 MCP 服务器（包括公共目录中的服务器）时应谨慎行事——在授予网关访问权限之前，请自行进行安全评估。

有关完整结构，请参见 CONTRIBUTING.md 或运行 tree -L 2。

---

开发

make dev # 带自动重载的开发服务器（:8000）
make test # 运行测试套件
make lint # 运行所有代码检查工具
make coverage # 生成覆盖率报告

运行 make 查看所有可用目标。

有关开发工作流，请参见：

• https://ibm.github.io/mcp-context-forge/development/developer-workstation/
• https://ibm.github.io/mcp-context-forge/development/building/

---

故障排除

常见问题及解决方案：

.env，然后重试 | | docker compose up失败并显示SecurityConfigurationError: jwt_secret_key|.env文件缺失或包含REPLACE_ME占位符。运行cp .env.example .env && python3 -m mcpgateway.scripts.init_secrets --patch-env .env| |docker compose up失败 —mcpgateway/nginx-cache 拉取访问被拒绝 | nginx 镜像必须本地构建：docker compose build nginx| |make dev— 8000 端口无响应 | 检查终端是否有SecurityConfigurationError— 运行make ensure-secrets后重试。在 WSL2 上使用http://127.0.0.1:8000` 而非 localhost | | macOS 上 SQLite 出现 "disk I/O error" | 避免使用 iCloud 同步目录；使用 ~/mcp-context-forge/data | | WSL2 上 4444 端口无法访问 | 在 Docker Desktop 中配置 WSL 集成 | | 网关立即退出 | 运行 cp .env.example .env && python3 -m mcpgateway.scripts.init_secrets --patch-env .env | | ModuleNotFoundError | 运行 make install-dev |

有关详细的故障排除指南，请参见 **https://ibm.github.io/mcp-context-forge/manage/troubleshooting/**。

---

贡献

1. Fork 仓库，创建功能分支。
2. 运行 make lint 并修复所有问题。
3. 保持 make test 通过（显示绿色）。
4. 提交带有签名的 PR（git commit -s）。

有关完整指南，请参见 CONTRIBUTING.md，有关如何提交错误、请求功能和查找可处理问题，请参见 **https://github.com/IBM/mcp-context-forge/issues/2502**。

---

变更日志

完整的变更日志可在此处找到：CHANGELOG.md

许可证

根据 Apache License 2.0 许可 - 参见 LICENSE

核心作者和维护者

• Mihai Criveti - 杰出工程师，智能体 AI

特别感谢所有贡献者帮助我们改进 ContextForge：

星级历史和项目活动