ghcr.io/ibm/mcp-context-forge:amd64-b8b4d94dced0c416ee3defd65aac068ad699e7ef

ContextForge

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

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

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

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

---

目录

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

---

📌 快速链接

---

概述与目标

ContextForge 是一个开源注册中心和代理，用于联邦任何[***] API，提供集中式治理、发现和可观测性。它优化代理和工具调用，并支持插件。有关更多详情，请参见https://ibm.github.io/mcp-context-forge/architecture/roadmap/%E3%80%82

目前支持以下功能：

• 跨多个MCP和REST服务的联邦
• A2A（代理到代理）集成，用于外部AI代理（OpenAI、***、自定义代理）
• gRPC到MCP转换，通过基于自动反射的服务发现实现
• 将遗留API虚拟化为MCP兼容的工具和服务器
• 通过HTTP、JSON-RPC、WebSocket、SSE（可配置保活机制）、标准输入输出和流式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提取

• 支持请求头、令牌和自定义认证

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

🧠 统一注册中心

• 提示词（Pro*s）**：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/**%E3%80%82

---

快速开始 - PyPI

ContextForge在https://pypi.org/project/mcp-contextforge-gateway/%E4%B8%8A%E5%8F%91%E5%B8%83%EF%BC%8C%E5%8C%85%E5%90%8D%E4%B8%BA mcp-contextforge-gateway。

---

概要： （使用uv的单命令）

# 使用环境变量快速启动
BASIC_AUTH_PASSWORD=pass \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
PLATFORM_ADMIN_EMAIL=admin@example.com \
PLATFORM_ADMIN_PASSWORD=changeme \
PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

# 更优方式：使用提供的.env.example
cp .env.example .env
# 编辑.env自定义设置
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

📋 前提条件

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

1 - 安装与运行（可直接复制粘贴）

# 1️⃣ 隔离环境 + 从pypi安装
mkdir mcpgateway && cd mcpgateway
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣ 复制并自定义配置
# 下载示例环境文件
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env
# 编辑.env自定义设置（尤其是密码！）

3️⃣ 生成承载令牌并进行API冒烟测试

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
--username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)

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

🐳 Docker（单容器）

docker run -d --name mcpgateway \
-p 4444:4444 \
-e MCPGATEWAY_UI_ENABLED=true \
-e MCPGATEWAY_ADMIN_API_ENABLED=true \
-e HOST=0.0.0.0 \
-e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \
-e AUTH_REQUIRED=true \
-e PLATFORM_ADMIN_EMAIL=admin@example.com \
-e PLATFORM_ADMIN_PASSWORD=changeme \
-e PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \
-e DATABASE_URL=sqlite:///./mcp.db \
-e SECURE_COOKIES=false \
ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

查看日志并生成API密钥

docker logs -f mcpgateway
docker run --rm -it ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3 \
python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes

浏览至 http://localhost:4444/admin 并使用PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD登录。

高级配置：持久化存储、主机网络、离线部署

持久化SQLite数据库：

mkdir -p $(pwd)/data && touch $(pwd)/data/mcp.db && chmod 777 $(pwd)/data
docker run -d --name mcpgateway --restart unless-stopped \
-p 4444:4444 -v $(pwd)/data:/data \
-e DATABASE_URL=sqlite:////data/mcp.db \
-e MCPGATEWAY_UI_ENABLED=true -e MCPGATEWAY_ADMIN_API_ENABLED=true \
-e HOST=0.0.0.0 -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \
-e PLATFORM_ADMIN_EMAIL=admin@example.com -e PLATFORM_ADMIN_PASSWORD=changeme \
ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

主机网络（访问本地MCP服务器）：

docker run -d --name mcpgateway --network=host \
-v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
-e MCPGATEWAY_UI_ENABLED=true -e HOST=0.0.0.0 -e PORT=4444 \
ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

离线部署（无互联网）：

docker build -f Containerfile.lite -t mcpgateway:airgapped .
docker run -d --name mcpgateway -p 4444:4444 \
-e MCPGATEWAY_UI_AIRGAPPED=true -e MCPGATEWAY_UI_ENABLED=true \
-e HOST=0.0.0.0 -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \
mcpgateway:airgapped

升级

有关升级说明、迁移指南和回滚流程，请参见：

• https://ibm.github.io/mcp-context-forge/manage/upgrade/ — 通用升级流程
• CHANGELOG.md — 版本历史和破坏性变更

测试

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

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

---

项目结构

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。

---

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

---

贡献指南

1. Fork 仓库，创建功能分支。
2. 运行 make lint 并修复所有问题。
3. 确保 make test 测试通过。
4. 提交包含已签名提交的 PR（git commit -s）。

有关完整指南，请参见 CONTRIBUTING.md；有关如何提交错误报告、请求功能以及查找可参与的问题，请参见 **https://github.com/IBM/mcp-context-forge/issues/2502**%E3%80%82

---

变更日志

完整的变更日志可在此处查看：CHANGELOG.md

许可证

根据 Apache License 2.0 许可 - 详见 LICENSE

核心作者与维护者

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

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

星标历史与项目活动