使用说明

MCP网关

AI代理和下游API的生产就绪统一入口点，实现模型上下文协议（MCP）.

快速入门（本地-5分钟）

先决条件

工具	最低版本	检查
Python	3.10+	`python3 --version`
点数	23+	`pip3 --version`
制作	任何	`make --version`
Docker （可选）	24+	`docker --version`

macOS：通过以下方式安装Python 家酿: brew install python@3.12 视窗：从以下位置安装Python python.org，然后使用 make 通过WSL或Git Bash。

选项A——直接用Python运行（建议用于开发）

# 1. Clone / open the project folder
cd mcp-gateway

# 2. One-command setup (creates virtualenv + installs deps + copies .env)
make setup

# 3. Start the gateway
make run

网关开始于 http://localhost:8080.

在上打开交互式API文档 http://localhost:8080/docs.

选项B——使用Docker Compose运行（全栈）

# Starts gateway + Redis + Prometheus + Grafana + Jaeger
make docker-up

服务	URL
网关API	http://localhost:8080
API文档	http://localhost:8080/docs
格拉法纳	http://localhost:3000（管理员/管理员）
普罗米修斯	http://localhost:9091
耶格尔（痕迹）	http://localhost:16686

手动设置（逐步）

如果你不想使用 make:

# 1. Create virtual environment
python3 -m venv .venv
source .venv/bin/activate          # macOS/Linux
# .venv\Scripts\activate           # Windows

# 2. Install dependencies
pip install -e ".[dev]"

# 3. Copy environment config
cp .env.example .env

# 4. Create log directory
mkdir -p logs

# 5. Start the gateway
uvicorn src.main:app --host 0.0.0.0 --port 8080 --reload

配置

所有配置都在 .env 文件（复制自 .env.example 在设置期间）。

按键设置

# Auth — who can call the gateway
GATEWAY_AUTH_ENABLED=true
GATEWAY_API_KEYS_FILE=config/api_keys.json      # your API keys

# Upstream APIs — what the gateway proxies to
GATEWAY_UPSTREAM_CONFIG_FILE=config/upstreams.json

# Rate limiting
GATEWAY_RATE_LIMIT__DEFAULT_RPM=60             # requests per minute per identity
GATEWAY_RATE_LIMIT__BURST_ALLOWANCE=10

# Debug / dev mode
GATEWAY_DEBUG=true
GATEWAY_ENVIRONMENT=development

添加您自己的上游API

编辑 config/upstreams.json:

[
  {
    "name": "my-api",
    "url": "https://api.example.com",
    "description": "My downstream API",
    "upstream_token": "your-bearer-token-here",
    "timeout_seconds": 30,
    "tags": ["internal"]
  }
]

添加API密钥

编辑 config/api_keys.json:

[
  {
    "key": "my-secret-key-001",
    "owner": "your-name",
    "allowed_upstreams": [],
    "rate_limit_rpm": -1,
    "scopes": ["read", "write"]
  }
]

试试看

网关运行后，打开一个新终端并尝试以下操作：

健康检查（无需身份验证）

curl http://localhost:8080/health

列出已配置的上游

curl http://localhost:8080/upstreams \
  -H "X-Api-Key: dev-key-alice-001"

发送MCP初始化请求

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: dev-key-alice-001" \
  -d '{
    "version": "1.0",
    "request": {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2024-11-05",
        "clientInfo": {"name": "my-agent", "version": "1.0"}
      }
    }
  }'

注册AI代理（获取会话令牌）

curl -X POST http://localhost:8080/agents/register \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: dev-key-alice-001" \
  -d '{
    "agent_name": "my-llm-agent",
    "agent_version": "1.0.0",
    "requested_upstreams": [],
    "requested_scopes": ["read", "write"]
  }'

使用代理令牌调用MCP

# Replace <token> with the token from the register response
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Agent-Token: <token>" \
  -d '{
    "request": {
      "jsonrpc": "2.0",
      "id": 2,
      "method": "tools/list"
    }
  }'

直接代理到上游

curl -X POST http://localhost:8080/mcp/notion \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: dev-key-alice-001" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

常用命令

make run           # Start gateway (http://localhost:8080)
make run-reload    # Start with hot-reload (auto-restarts on code change)
make test          # Run all tests
make test-unit     # Run unit tests only
make lint          # Lint code with ruff
make format        # Auto-format code
make typecheck     # Type check with mypy
make docker-up     # Start full stack (gateway + Redis + monitoring)
make docker-down   # Stop Docker stack
make clean         # Remove virtualenv and caches

项目结构

mcp-gateway/
├── src/
│   ├── main.py                    ← Entry point
│   ├── core/
│   │   ├── app.py                 ← App factory + middleware wiring
│   │   ├── config.py              ← All configuration (env + JSON)
│   │   └── state.py               ← Shared HTTP pool + rate buckets
│   ├── protocol/
│   │   ├── mcp_types.py           ← MCP message types
│   │   └── validator.py           ← Request validation pipeline
│   ├── routing/
│   │   ├── mcp_router.py          ← MCP method handling
│   │   └── proxy.py               ← Reverse proxy with retries
│   ├── security/
│   │   ├── auth.py                ← API Key + OAuth JWT + Agent auth
│   │   └── agent_registry.py      ← Agent session management
│   ├── middleware/
│   │   ├── rate_limiter.py        ← Token-bucket rate limiting
│   │   ├── logging_mw.py          ← Structured JSON access logs
│   │   └── circuit_breaker.py     ← Per-upstream circuit breaker
│   └── observability/
│       ├── telemetry.py           ← OpenTelemetry + Prometheus
│       └── health.py              ← /health, /readyz, /metrics
├── config/
│   ├── api_keys.json              ← API credentials
│   └── upstreams.json             ← Downstream API definitions
├── tests/
│   ├── unit/                      ← Fast, isolated tests
│   └── integration/               ← Full stack tests
├── deploy/k8s/                    ← Kubernetes manifests
├── monitoring/                    ← Prometheus + Grafana configs
├── Dockerfile                     ← Multi-stage production image
├── docker-compose.yml             ← Local dev stack
├── Makefile                       ← Developer commands
└── .env.example                   ← Config template

认证

网关支持三种身份验证方法，在每次请求时都按顺序尝试：

方法	标题	示例
API密钥	`X-Api-Key`	`X-Api-Key: dev-key-alice-001`
代理令牌	`X-Agent-Token`	`X-Agent-Token: <jwt>`
OAuth承载者	`Authorization`	`Authorization: Bearer <jwt>`

公共路径（无需身份验证）： /health, /readyz, /metrics, /docs

关键终点

端点	方法	身份验证	描述
`/health`	GET	无	活体检测
`/readyz`	GET	无	准备状态+上游健康状况
`/metrics`	GET	无	普罗米修斯指标
`/docs`	GET	无	Swagger用户界面
`/mcp`	POST	必需	MCP协议端点
`/mcp/{upstream}`	POST	必需	直接上游代理
`/agents/register`	POST	必填	注册AI代理
`/agents/sessions`	GET	必填	列出活动会话
`/upstreams`	GET	必需	列出配置的上游
`/config/info`	GET	必需	网关配置信息

故障排除

ModuleNotFoundError: No module named 'src' → 确保你在 mcp-gateway/ 目录，而不是子目录。 → Run pip install -e ".[dev]" 从项目根开始。

401 Unauthorized → 添加标题 -H "X-Api-Key: dev-key-alice-001" 根据您的要求。 → Check config/api_keys.json 包含您正在使用的密钥。

Address already in use （端口8080） → 更改端口： uvicorn src.main:app --port 8090 → 或更新 GATEWAY_PORT=8090 在你的 .env 文件。

429 Too Many Requests → 你已达到利率上限。等待一分钟或增加 GATEWAY_RATE_LIMIT__DEFAULT_RPM 在 .env.

文档

完整的架构文档： docs/ARCHITECTURE.md