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 應用生態系統的理想基礎設施組件。