ghcr.io/ibm/mcp-context-forge:1e5efe9b2a745732d55b5d209c706beb31b67bd5

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头
• OpenTelemetry可观测性，支持Phoenix、Jaeger、Zipkin和其他OTLP后端
• 通过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或自定义方案
• 结构化日志、健康检查端点、指标
• 7,000+测试、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`。

---

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

TLDR — 使用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 - 安装与运行（适合复制粘贴）

Windows (PowerShell) 快速启动

# 1️⃣ 隔离环境 + 从 PyPI 安装
mkdir mcpgateway ; cd mcpgateway
python3 -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣ 下载 .env.example 并生成实际密钥
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example" -OutFile ".env.example"
Copy-Item .env.example .env

# 生成加密安全的密钥到 .env.secrets
python3 -m mcpgateway.scripts.init_secrets

# 将生成的密钥补丁到 .env 中（替换 __REPLACE_ME__ 占位符）
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣ 启动网关
mcpgateway.exe --host 0.0.0.0 --port 4444

# 4️⃣ 生成 Bearer 令牌并进行冒烟测试
$Env:JWT_SECRET_KEY = (Get-Content .env | Select-String '^JWT_SECRET_KEY=').ToString().Split('=')[1]
$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `
--username admin@example.com --exp 10080 --secret $Env:JWT_SECRET_KEY

curl -s -H "Authorization: Bearer $Env:MCPGATEWAY_BEARER_TOKEN" `
http://127.0.0.1:4444/version | jq

您将获得：

• 🗄️ PostgreSQL - 生产就绪型数据库，包含55+张表
• 🚀 ContextForge - 全功能网关，带管理界面
• 📊 Redis - 高性能缓存和会话存储
• 🔧 管理工具 - pgAdmin、Redis Insight，用于数据库管理
• 🌐 Nginx 代理 - 端口8080上的缓存反向代理

🚑 运行中容器的冒烟测试

curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
http://localhost:4444/health | jq
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
http://localhost:4444/tools | jq
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
http://localhost:4444/version | jq

📚 完整配置参考

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

---

运行

快速参考

开发服务器（Uvicorn）

make dev # Uvicorn 在 :8000 端口运行，带自动重载和 SQLite
# 或
./run.sh --reload --log debug --workers 2

run.sh 是 uvicorn 的包装脚本，用于加载 .env 文件、支持重载并将参数传递给服务器。

主要标志：

生产服务器（Gunicorn）

make serve # Gunicorn 在 :4444 端口运行，带多个工作进程
make serve-ssl # Gunicorn 带 HTTPS 在 :4444 端口运行（使用 ./certs）

Docker Compose（完整栈）

make compose-up # 启动完整栈：PostgreSQL、Redis、3 个网关副本、Nginx 在 :8080 端口
make compose-sso # 启动带 Keycloak 的 SSO 栈，Keycloak 在 :8180 端口
make sso-test-login # 运行 SSO 冒烟测试（提供程序 + 登录 URL + 测试用户）
make compose-logs # 跟踪所有服务的日志
make compose-down # 停止栈

手动启动（Uvicorn）

uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444 --workers 4

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 - Distinguished Engineer, Agentic AI

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

星级历史与项目活动