API网关适配系统

┌──────────────────────────────────────────────────────────────────────┐
│                       MCP Smart API Gateway                          │
│                                                                      │
│  ┌─────────────┐    ┌────────────────────────────┐                   │
│  │  MCP Route   │───▶│        McpService           │                  │
│  │  (Session +  │    │  initialize / tools/list    │                  │
│  │   Auth +     │    │  / tools/call               │                  │
│  │  RateLimit)  │    └─────────────┬──────────────┘                  │
│  └─────────────┘                  │                                  │
│                                    │                                  │
│  ┌────────────────┐   ┌───────────▼──────────────┐                   │
│  │  ToolRegistry   │   │    AdaptationEngine       │                  │
│  │ (config-driven) │   │  validate → map → call    │                  │
│  └───────┬────────┘   │  → shape response          │                  │
│          │            └───────────┬──────────────┘                   │
│  ┌───────▼────────┐               │                                  │
│  │  ConfigLoader   │   ┌──────────▼───────────┐                      │
│  │ YAML/JSON/OAS   │   │    RestConnector      │                     │
│  └────────────────┘   │  httpx + 幂等重试      │                     │
│                        └──────────┬───────────┘                      │
│                                   │                                  │
├───────────────────────────────────┼──────────────────────────────────┤
│  辅助组件:                         │                                  │
│  · ApiKeyAuth (双 Key 鉴权)        │                                  │
│  · SlidingWindowRateLimiter       │                                  │
│  · SessionManager (会话生命周期)   │                                  │
│  · SQLite (access_log / audit)    │                                  │
│  · watchfiles (配置自动重载)       │                                  │
│  · Dashboard (前端管理界面)        │                                  │
└───────────────────────────────────┼──────────────────────────────────┘
                                    │
                                    ▼
                         下游 REST API 服务

MCP Client / LLM ──POST /mcp (JSON-RPC 2.0)──▶ Gateway ──REST──▶ 下游 API

MCPgateway/
├── app/                          # 应用主包
│   ├── __main__.py               # CLI 入口 (python -m app)
│   ├── main.py                   # FastAPI 应用工厂、lifespan 组装、中间件、watchfiles
│   ├── settings.py               # 配置类，读取 .env 和环境变量
│   ├── api/                      # 路由层
│   │   ├── mcp_routes.py         # POST /mcp (JSON-RPC)、DELETE /mcp (终止会话)
│   │   ├── admin_routes.py       # /admin/reload、/admin/rollback、/admin/tools、/admin/status
│   │   └── health_routes.py      # GET /health
│   ├── core/                     # 核心业务逻辑
│   │   ├── mcp_service.py        # JSON-RPC 方法分发 (initialize / tools/list / tools/call)
│   │   ├── tool_registry.py      # 工具快照管理、reload / rollback、变更摘要
│   │   ├── config_loader.py      # YAML/JSON 配置文件加载、OpenAPI 预览生成
│   │   ├── schema_generator.py   # OpenAPI 3.x → ToolConfig 自动转换
│   │   ├── adaptation_engine.py  # 参数校验 → 请求映射 → REST 调用 → 响应整形
│   │   ├── rest_connector.py     # httpx 异步 HTTP 客户端，支持幂等重试
│   │   ├── response_mapper.py    # 响应路径提取、字段白名单、文本模板
│   │   ├── error_mapper.py       # 统一错误分类与 JSON-RPC 错误码映射
│   │   ├── errors.py             # GatewayError 数据类
│   │   ├── auth.py               # API Key 鉴权（网关 Key + 管理 Key）
│   │   ├── rate_limit.py         # 滑动窗口限流器
│   │   └── session_manager.py    # MCP 会话管理（创建/初始化/过期清理/终止）
│   ├── db/                       # 持久化层
│   │   ├── database.py           # aiosqlite 初始化、WAL 模式、建表与迁移
│   │   └── repositories.py       # ConfigAuditRepository / AccessLogRepository
│   ├── models/                   # 数据模型
│   │   ├── jsonrpc.py            # JSON-RPC 2.0 请求/响应 Pydantic 模型
│   │   └── tool_config.py        # ToolConfig / ToolMeta / HttpTarget / 映射模型
│   └── utils/
│       └── logging.py            # 结构化 JSON 日志、请求 ID 上下文、敏感字段脱敏
├── configs/                      # 配置文件目录
│   ├── tools/                    # 工具配置（YAML/JSON，每文件一个工具）
│   │   ├── get_user.yaml         # 查询用户信息
│   │   ├── create_order.yaml     # 创建订单（嵌套 body 映射）
│   │   ├── get_baidu_suggestion.yaml  # 百度搜索建议（外部 API）
│   │   ├── probe_slow.yaml       # 慢响应探针
│   │   ├── probe_failure.yaml    # 失败探针
│   │   └── probe_retry.yaml      # 重试探针
│   └── openapi/
│       └── mock_api.yaml         # OpenAPI 3.x 文档（管理接口预览用）
├── static/
│   └── index.html                # 前端管理界面（仪表盘 + MCP 调试工具）
├── scripts/
│   ├── mock_rest_api.py          # 模拟下游 REST 服务 (:9001)
│   ├── run_experiments.py        # 自动化实验脚本
│   ├── llm_demo.py               # LLM 端到端演示（OpenAI 兼容 API + MCP 网关）
│   └── verify_dashboard.py       # Playwright 仪表盘截图验证
├── tests/                        # 测试套件（10 个文件，100+ 测试用例）
├── pyproject.toml                # 项目元数据与依赖
├── .env.example                  # 环境变量模板
└── HANDOFF.md                    # 项目交接文档

python --version

cd 你的项目路径\MCPgateway

dir pyproject.toml
# Linux/macOS: ls pyproject.toml

python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Windows CMD
.venv\Scripts\activate.bat

# Linux/macOS
source .venv/bin/activate

pip install -e .[dev]

copy .env.example .env
# Linux/macOS: cp .env.example .env

cd 你的项目路径\MCPgateway
.venv\Scripts\Activate.ps1
python scripts/mock_rest_api.py

INFO:     Uvicorn running on http://127.0.0.1:9001 (Press CTRL+C to quit)

cd 你的项目路径\MCPgateway
.venv\Scripts\Activate.ps1
python -m app

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

curl http://127.0.0.1:8000/health

{"status":"ok","gateway":{"status":"ready","version":"...","tool_count":6,...}}

cd 你的项目路径\MCPgateway
.venv\Scripts\Activate.ps1
python scripts/run_experiments.py

pytest

┌─────────────────────────────────────────────────────┐
│  终端 1                终端 2              终端 3     │
│  ────────              ────────            ────────  │
│  mock_rest_api.py  →   python -m app  →   实验/测试  │
│  (端口 9001)           (端口 8000)        (可选)     │
│                                                      │
│  ⚠ 顺序很重要：先启动终端 1，再启动终端 2              │
└─────────────────────────────────────────────────────┘

Client                          Gateway
  │                                │
  ├──POST /mcp {initialize}───────▶│  创建会话，返回 mcp-session-id
  │◀──200 {serverInfo, caps}───────┤
  │                                │
  ├──POST /mcp {notifications/     │  标记会话已初始化
  │    initialized}────────────────▶│
  │◀──202────────────────────────┤
  │                                │
  ├──POST /mcp {tools/list}────────▶│  获取工具列表
  │◀──200 {tools:[...]}───────────┤
  │                                │
  ├──POST /mcp {tools/call}────────▶│  调用工具 → 转发到下游 REST API
  │◀──200 {content, meta}─────────┤
  │                                │
  ├──DELETE /mcp───────────────────▶│  终止会话
  │◀──204────────────────────────┤

tool_meta:
  name: get_user
  title: 查询用户信息
  description: 根据用户ID查询用户的基本信息，包括姓名、邮箱、部门和角色。
  version: "1.0.0"
  tags: ["用户", "查询"]

input_schema:
  type: object
  properties:
    user_id:
      type: integer
      description: Numeric user identifier.
    verbose:
      type: boolean
      description: Whether to request verbose output.
  required: ["user_id"]
  additionalProperties: false

http_target:
  method: GET
  base_url: http://127.0.0.1:9001
  path: /users/{user_id}
  timeout_seconds: 5
  retry_count: 1

request_mapping:
  path_map:
    user_id: user_id
  query_map:
    verbose: verbose

response_mapping:
  result_path: data
  field_whitelist: ["id", "name", "email", "role"]
  include_http_meta: true
  text_template: "用户 {name} 的邮箱是 {email}，角色为 {role}。"

error_mapping:
  status_map:
    "404": DOWNSTREAM_ERROR
    "500": DOWNSTREAM_ERROR
  default_code: DOWNSTREAM_ERROR
  expose_downstream_body: true

curl -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: dev-api-key" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"clientInfo\":{\"name\":\"my-client\",\"version\":\"1.0.0\"}}}"

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "serverInfo": {"name": "mcp-smart-api-gateway", "version": "0.1.0"},
    "capabilities": {"tools": {"listChanged": true}, "logging": {}}
  }
}

curl -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: dev-api-key" \
  -H "mcp-session-id: <上一步返回的 session id>" \
  -d "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}"

curl -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: dev-api-key" \
  -H "mcp-session-id: <session id>" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}"

curl -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: dev-api-key" \
  -H "mcp-session-id: <session id>" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"get_user\",\"arguments\":{\"user_id\":1,\"verbose\":true}}}"

# 查看网关状态
curl -H "x-api-key: dev-admin-key" http://127.0.0.1:8000/admin/status

# 查看已注册工具
curl -H "x-api-key: dev-admin-key" http://127.0.0.1:8000/admin/tools

# 手动重载配置
curl -X POST -H "x-api-key: dev-admin-key" http://127.0.0.1:8000/admin/reload

# 回滚到前一版本
curl -X POST -H "x-api-key: dev-admin-key" http://127.0.0.1:8000/admin/rollback

python scripts/mock_rest_api.py    # 终端 1
python -m app                      # 终端 2
python scripts/run_experiments.py  # 终端 3

用户提问 → 大模型推理 → 工具选择 → MCP 网关 → 下游 REST API → 大模型生成回答

# 设置 OpenAI API Key（支持任何 OpenAI 兼容 API）
# PowerShell
$env:OPENAI_API_KEY = "sk-xxx"
# 可选：自定义 API 地址和模型
$env:OPENAI_BASE_URL = "https://api.openai.com/v1"
$env:OPENAI_MODEL = "gpt-4o-mini"

python scripts/llm_demo.py

pytest