MCP Context Forge 项目详细介绍

项目概述

MCP Context Forge 是 IBM 开源的一个功能丰富的 FastAPI 驱动的模型上下文协议（MCP）网关，它统一和联合工具、资源、提示、服务器和对等网关，将任何 REST API 包装为符合 MCP 标准的工具或虚拟服务器。该项目支持通过 HTTP/JSON-RPC、WebSocket、服务器发送事件（SSE）和 stdio 传输协议公开所有功能，并提供丰富的交互式管理 UI，以容器形式打包，支持任何 SQLAlchemy 支持的数据库。

核心功能

1. 协议网关功能

• 真正的网关架构：集中化工具、资源和提示注册中心，同时保持官方 MCP 2025-03-26 协议标准
• 多服务器联邦：将多个 MCP 服务器统一到一个端点——自动发现对等节点（mDNS 或显式配置）、健康检查并合并其功能
• 虚拟化服务：将非 MCP 服务虚拟化为"虚拟服务器"，可以注册任何 REST API 或函数端点并在 MCP 语义下公开

2. API 适配功能

• REST 到 MCP 适配器：将任意 REST/HTTP API 适配为 MCP 工具，支持 JSON-Schema 输入验证、重试/速率限制策略和透明的 JSON-RPC 调用
• 协议转换：支持多种传输协议之间的转换（stdio、SSE、Streamable HTTP）

3. 部署和管理

• 完整的管理 UI：提供丰富的传输协议、预构建的开发体验管道和生产级可观测性
• 企业级功能：包含认证授权、缓存、健康检查、指标收集等完整功能

系统架构

该项目采用模块化架构设计：

┌─────────────────┐    ┌──────────────────┐
│  🖥️ Admin UI    │    │  🔐 认证授权      │
│  管理界面        │    │  JWT + Basic     │
└─────────────────┘    └──────────────────┘
         │                        │
         └────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │        🚪 MCP 网关核心        │
    │     协议初始化 Ping 完成      │
    │        联邦管理器              │
    │   传输协议 HTTP WS SSE Stdio  │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │           服务层               │
    │  🧰 工具服务  📁 资源服务      │
    │  📝 提示服务  🧩 服务器服务    │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │          持久化层              │
    │    💾 数据库 SQLAlchemy       │
    │    ⚡ 缓存 Redis/Memory       │
    └───────────────────────────────┘

技术特性

支持的协议和传输

• 完整的 MCP 2025-03-26 支持：initialize、ping、notify、completion、sampling (SSE)，以及 JSON-RPC 回退
• 多传输协议：HTTP/JSON-RPC、WebSocket（ping/pong）、SSE（单向+回传通道）、stdio
• 协议转换：支持不同传输协议之间的无缝转换

联邦和发现

• 自动发现：支持 mDNS 或显式配置的对等网关发现
• 健康检查：定期健康检查，支持故障转移
• 透明合并：将远程注册表透明合并到统一目录中

资源管理

• 模板化 URI：支持参数化的资源 URI
• 智能缓存：LRU+TTL 缓存机制，MIME 类型检测
• 实时订阅：支持 SSE 实时订阅资源变更

提示管理

• Jinja2 模板：强大的模板引擎支持
• Schema 验证：JSON-Schema 强制验证
• 多模态支持：支持多模态内容块
• 版本控制：版本管理和回滚功能

工具管理

• 多类型支持：原生 MCP 或基于 REST 的工具
• 输入验证：完整的输入验证机制
• 重试逻辑：智能重试和速率限制/并发控制

管理和监控功能

Web 管理界面

• 技术栈：HTMX + Alpine.js + Tailwind CSS
• 完整 CRUD：服务器、工具、资源、提示、网关、根目录和指标的完整管理
• 实时监控：实时状态监控和日志查看

认证和授权

• 多种认证方式：Basic 认证、JWT Bearer、自定义头部认证
• 细粒度控制：每个端点的依赖注入控制
• 安全加密：工具认证头部的 AES 加密存储

持久化和迁移

• ORM 支持：异步 SQLAlchemy ORM（SQLite、PostgreSQL、MySQL 等）
• 自动迁移：Alembic 自动数据库迁移
• 连接池：完整的数据库连接池配置

事件系统和可观测性

• 统一事件：WS/SSE 扇出的统一事件包装
• 服务端过滤：服务端事件过滤和回传钩子
• 结构化日志：结构化 JSON 日志记录
• 健康检查：/health 端点和延迟指标装饰器
• 完整指标：每个处理程序的指标收集

开发体验

开发工具

• Makefile 目标：超过 100 个预定义的开发目标
• 代码质量：pre-commit hooks（ruff、black、mypy、isort）
• 实时重载：开发服务器支持实时重载
• 测试覆盖：400+ 个测试用例
• CI/CD：完整的 CI 徽章和自动化流程

部署选项

• 容器化部署：Docker/Podman 支持
• 云原生：IBM Cloud Code Engine 部署支持
• 多环境：开发、测试、生产环境配置
• SSL/TLS：完整的 HTTPS 支持

配置选项

基础配置

# 应用基础配置
APP_NAME=MCP Gateway
HOST=0.0.0.0
PORT=4444
DATABASE_URL=sqlite:///./mcp.db
APP_ROOT_PATH=/gateway  # 可选的子路径前缀

认证配置

# Basic 认证（管理界面和 API）
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme

# JWT 配置
JWT_SECRET_KEY=my-test-key
JWT_ALGORITHM=HS256
TOKEN_EXPIRY=10080  # 分钟

# 认证控制
AUTH_REQUIRED=true
AUTH_ENCRYPTION_SECRET=my-test-salt

联邦配置

# 联邦功能
FEDERATION_ENABLED=true
FEDERATION_DISCOVERY=false
FEDERATION_PEERS=["http://peer1:4444","http://peer2:4444"]
FEDERATION_TIMEOUT=30
FEDERATION_SYNC_INTERVAL=300

快速开始

使用 Docker 运行

docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e HOST=0.0.0.0 \
  -e JWT_SECRET_KEY=my-secret-key \
  -e BASIC_AUTH_USER=admin \
  -e BASIC_AUTH_PASSWORD=changeme \
  -e AUTH_REQUIRED=true \
  -e DATABASE_URL=sqlite:///./mcp.db \
  ghcr.io/ibm/mcp-context-forge:latest

本地开发

# 创建虚拟环境并安装依赖
make venv install serve

# 或者手动安装
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444

生成认证令牌

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)

API 使用示例

协议初始化

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "protocol_version":"2025-03-26",
    "capabilities":{},
    "client_info":{"name":"MyClient","version":"1.0.0"}
  }' \
  http://localhost:4444/protocol/initialize

注册工具

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "name":"clock_tool",
    "url":"http://localhost:9000/rpc",
    "description":"Returns current time",
    "input_schema":{
      "type":"object",
      "properties":{"timezone":{"type":"string"}},
      "required":[]
    }
  }' \
  http://localhost:4444/tools

创建提示模板

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "name":"greet",
    "template":"Hello, {{ user }}!",
    "argument_schema":{
      "type":"object",
      "properties":{"user":{"type":"string"}},
      "required":["user"]
    }
  }' \
  http://localhost:4444/prompts

部署到 IBM Cloud Code Engine

项目提供了完整的 IBM Cloud Code Engine 部署支持：

环境配置

IBMCLOUD_REGION=us-south
IBMCLOUD_RESOURCE_GROUP=default
IBMCLOUD_PROJECT=my-codeengine-project
IBMCLOUD_CODE_ENGINE_APP=mcpgateway
IBMCLOUD_IMAGE_NAME=us.icr.io/myspace/mcpgateway:latest
IBMCLOUD_API_KEY=your_api_key_here

部署命令

make ibmcloud-check-env      # 检查环境变量
make ibmcloud-cli-install    # 安装 IBM Cloud CLI
make ibmcloud-login          # 登录 IBM Cloud
make ibmcloud-ce-login       # 选择 Code Engine 项目
make ibmcloud-tag            # 标记容器镜像
make ibmcloud-push           # 推送到 IBM Container Registry
make ibmcloud-deploy         # 部署到 Code Engine

项目结构

mcpgateway/
├── admin.py                    # FastAPI 路由和管理 UI 控制器
├── cache/
│   └── resource_cache.py      # 资源的内存 LRU+TTL 缓存
├── config.py                  # Pydantic 设置加载器
├── db.py                      # SQLAlchemy ORM 模型和数据库设置
├── federation/
│   ├── discovery.py           # 对等网关发现
│   ├── forward.py             # RPC 转发逻辑
│   └── manager.py             # 联邦协调和健康检查
├── handlers/
│   └── sampling.py            # MCP 流式采样请求处理器
├── services/
│   ├── completion_service.py  # 提示和资源参数完成逻辑
│   ├── gateway_service.py     # 对等网关注册和管理
│   ├── prompt_service.py      # 提示模板 CRUD 和渲染
│   ├── resource_service.py    # 资源注册、检索、订阅
│   ├── server_service.py      # 服务器注册和健康监控
│   └── tool_service.py        # 工具注册、调用、指标
├── transports/
│   ├── sse_transport.py       # 服务器发送事件传输
│   ├── stdio_transport.py     # stdio 传输
│   └── websocket_transport.py # WebSocket 传输
└── utils/
    ├── create_jwt_token.py    # JWT 生成和检查工具
    └── verify_credentials.py # FastAPI 认证依赖

开发和贡献

开发环境设置

# 安装开发依赖
make install-dev

# 运行代码检查
make lint

# 运行测试
make test

# 运行覆盖率测试
make coverage

代码质量工具

项目集成了多种代码质量工具：

• 格式化：black、isort、autoflake
• 静态分析：mypy、pylint、pyright、pyre
• 安全扫描：bandit、pip-audit
• 复杂度分析：radon、wily
• 依赖检查：fawltydeps、pip-licenses

总结

MCP Context Forge 是一个功能完整、生产就绪的模型上下文协议网关解决方案，特别适合企业级 LLM 应用的工具集成和管理需求。它不仅实现了 MCP 协议的完整功能，还提供了丰富的扩展功能，如联邦发现、协议转换、虚拟化服务等，是构建复杂 AI 应用生态系统的理想基础设施组件。