ghcr.io/ibm/mcp-context-forge:5f1dd0a61b789dd4bf020e5ada2a927d322a1b1f

ContextForge

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

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

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

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

---

目录

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

---

📌 快速链接

---

概述与目标

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

目前支持：

• 跨多个MCP和REST服务的联合
• A2A（智能体到智能体）集成，用于外部AI智能体（OpenAI、Anthropic、自定义）
• 通过基于反射的自动服务发现实现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提取

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

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

🧠 统一注册中心

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

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

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

🔍 OpenTelemetry可观测性

• 厂商无关的追踪，支持OpenTelemetry（OTLP）协议
• 多后端支持：Phoenix（专注LLM）、Jaeger、Zipkin、Tempo、DataDog、New Relic
• 分布式追踪，覆盖联合网关和服务
• 工具、提示词、资源和网关操作的自动埋点
• 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%60mcp-contextforge-gateway%60%E3%80%82

---

概要;：（使用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以自定义设置（尤其是密码！）

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️⃣ 复制并自定义配置
# 下载示例环境文件
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example" -OutFile ".env.example"
Copy-Item .env.example .env
# 编辑.env文件以自定义设置

# 或者设置环境变量（仅当前会话）
$Env:MCPGATEWAY_UI_ENABLED = "true"
$Env:MCPGATEWAY_ADMIN_API_ENABLED = "true"
#
> [!NOTE] API的基本认证默认禁用（API_ALLOW_BASIC_AUTH=false）
$Env:JWT_SECRET_KEY = "my-test-key-but-now-longer-than-32-bytes"
$Env:PLATFORM_ADMIN_EMAIL = "admin@example.com"
$Env:PLATFORM_ADMIN_PASSWORD = "changeme"
$Env:PLATFORM_ADMIN_FULL_NAME = "Platform Administrator"

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

# 可选：后台运行
# Start-Process -FilePath "mcpgateway.exe" -ArgumentList "--host 0.0.0.0 --port 4444"

# 4️⃣ 生成Bearer令牌并进行冒烟测试
$Env: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 $Env: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 -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/ — 通用升级流程
• MIGRATION.md — 破坏性变更和分步升级说明
• CHANGELOG.md — 版本历史和破坏性变更

API 参考

服务器运行时提供交互式 API 文档：

• http://localhost:4444/docs — 可直接在浏览器中尝试 API 调用
• http://localhost:4444/redoc — 浏览完整的端点参考

快速认证：

# 生成 JWT 令牌
export TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
--username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)

# 测试 API 访问
curl -H "Authorization: Bearer $TOKEN" http://localhost:4444/health

有关涵盖所有端点的详细 curl 示例，请参阅 **https://ibm.github.io/mcp-context-forge/manage/api-usage/**%E3%80%82

---

测试

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

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

有关详细的故障排除指南，请参阅 **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：

星标历史与项目活跃度