Agent Gateway

统一 JSON-RPC 协议内核 · 传输层薄适配 · 可插拔中间件管道
让 AI Agent（Trae / Dify / Cursor）安全操控本地环境的 MCP 网关

目录

• 快速开始
• 项目背景
  • 适用场景
  • 核心特点
  • 生态适配关系
• 架构说明
  • 调用链路架构
  • 项目目录结构
• 内置工具
• 运行模式
• 平台接入
  • Trae / Cursor 接入
  • Dify 接入
• 配置说明
  • 默认配置位置
  • 配置优先级
  • 关键配置项速查
  • 自定义配置步骤
• 多租户
  • 默认租户
  • 使用方式
  • 自定义租户
• Docker 部署
  • 构建镜像
  • 使用 docker-compose 启动
  • 访问服务
  • 验证部署
  • docker-compose 服务说明
• 安全设计
• 结构化日志
• 测试指南
  • 测试入口说明
  • 运行全部测试
  • 测试样例：缓存命中率
• 质量保障
• 文档体系
• 版本演进
• License

快速开始

git clone https://github.com/wuwo1979/agent.git && cd agent
pip install -r requirements/runtime.txt
python main.py                                    # 启动 HTTP 网关（端口 9090）

验证服务：

# 健康检查
curl.exe -s http://localhost:9090/api/v1/health

# 列出工具
curl.exe -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

{
  "status": "healthy",
  "server": "MCP 本地工具网关",
  "version": "2.0.0",
  "protocol_handlers": 11,
  "tools": 17,
  "providers": 5,
  "active_sessions": 0
}

{
  "result": {
    "tools": [
      {"name": "read_file",    "description": "读取指定文件内容"},
      {"name": "write_file",   "description": "写入内容到指定文件"},
      {"name": "run_command",  "description": "在终端中执行命令（沙箱保护）"},
      {"name": "query",        "description": "执行数据库查询"},
      {"name": "web_fetch",    "description": "获取网页或 API 内容"},
      {"name": "llm_call",     "description": "调用本地大模型（Ollama）"}
    ]
  }
}

项目背景

MCP Agent Gateway 是一个基于 MCP (Model Context Protocol) 协议的工具网关。

它实现了 MCP 协议的 JSON-RPC 内核，将本地工具（文件读写、终端命令、数据库查询、网页抓取、Ollama 推理）封装为 MCP 工具接口，通过 STDIO 或 HTTP 传输层暴露给 AI Agent 调用。

并不会替代 Agent 本身的能力，而是作为一个可选的本地工具后端，在您需要 Agent 操控本地环境时提供安全可控的工具接口。

适用场景

• 在 Trae / Cursor 中通过 MCP STDIO 接入，让 Agent 调用本地文件、终端、数据库等工具
• 在 Dify 中通过 HTTP + OpenAPI Schema 导入，作为自定义工具节点使用
• 需要为本地工具调用添加安全管控（路径沙箱、命令注入拦截、权限隔离）时
• 需要统一的日志追踪和审计能力时

核心特点

生态适配关系

┌─────────────────────────────────────────────────────────────────┐
│                         AI Agent 生态                            │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌───────┐ │
│  │  Trae   │  │  Cursor │  │ VS Code │  │  Dify   │  │Ollama │ │
│  │ (STDIO) │  │ (STDIO) │  │ (STDIO) │  │ (HTTP)  │  │(HTTP) │ │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘  └───┬───┘ │
│       └────────────┴────────────┴────────────┴────────────┘     │
│                              │                                  │
│                     ┌────────▼────────┐                        │
│                     │  MCP Agent      │                        │
│                     │  Gateway        │                        │
│                     │  (统一协议内核)  │                        │
│                     └────────┬────────┘                        │
│                              │                                  │
│                     ┌────────▼────────┐                        │
│                     │  本地资源        │                        │
│                     │  文件·终端·DB   │                        │
│                     └─────────────────┘                        │
└─────────────────────────────────────────────────────────────────┘

• Trae / Cursor / VS Code: 通过 MCP STDIO 协议接入，网关作为 MCP Server 运行
• Dify: 通过 HTTP REST + OpenAPI Schema 导入工具
• Ollama: 作为后端推理服务，网关转发 LLM 请求并添加故障隔离

架构说明

调用链路架构

                    AI Agent (Trae / Dify / Cursor)
                            │
                    ┌───────▼────────────────────────────┐
                    │  传输层 Transport (薄适配)           │
                    │  STDIOTransport · HTTPTransport     │
                    │  职责：协议解析 + 会话管理          │
                    └───────┬────────────────────────────┘
                            │ JSONRPCRequest
                    ┌───────▼────────────────────────────┐
                    │  MCPProtocolHandler (唯一执行入口)   │
                    │                                    │
                    │  ┌─ Middleware Pipeline ──────────┐ │
                    │  │  [Auth] → [RateLimit] →       │ │
                    │  │  [Audit] → [Cache]            │ │
                    │  └───────────────────────────────┘ │
                    │                                    │
                    │  ToolRegistry (17 tools)           │
                    │  5 providers: filesystem/terminal/ │
                    │  database/web/llm                  │
                    └───────┬────────────────────────────┘
                            │
                    ┌───────▼────────────────────────────┐
                    │  本地资源 (沙箱安全)                 │
                    │  文件系统 · 终端 · SQLite/MySQL ·   │
                    │  Ollama 推理                        │
                    └────────────────────────────────────┘

架构特点：

1. 唯一入口：所有请求（无论 STDIO 还是 HTTP）最终汇聚到 MCPProtocolHandler
2. 中间件管道：认证 → 限流 → 审计 → 缓存，请求经过管道后执行工具
3. 传输层薄适配：传输层只做协议解析，不含业务逻辑，新增传输方式只需实现接口
4. 沙箱隔离：工具层对本地资源的访问受路径白名单、命令黑名单、参数化查询保护

图：网关架构分层图 — Agent → 传输层 → 协议内核 → 中间件管道 → 工具层 → 本地资源

项目目录结构

LLM/
├── main.py                    # 入口，支持 --mode stdio / --demo / --status
├── mcp_gateway/               # 核心网关
│   ├── server.py              # 服务装配 + 中间件初始化
│   ├── protocol.py            # 协议内核 + 中间件管道（唯一执行入口）
│   ├── transport.py           # 传输层（STDIO/HTTP 薄适配）
│   ├── api.py                 # REST → JSON-RPC 适配器（Dify 专用）
│   ├── security.py            # 认证 / 限流 / 策略引擎
│   ├── audit.py               # 审计日志
│   ├── tenancy.py             # 多租户管理
│   └── tools/                 # 5 个工具提供者，共 17 个工具
│       ├── filesystem.py      # ✅ 已实现
│       ├── terminal.py        # ✅ 已实现
│       ├── database.py        # ✅ 已实现
│       ├── web.py             # ✅ 已实现
│       └── llm.py             # ✅ 已实现
├── core/                      # 基础设施
│   ├── types.py               # JSON-RPC 类型定义
│   ├── exceptions.py          # 统一异常体系
│   └── structured_log.py      # 结构化 JSON 日志 + request_id 追踪
├── config/                    # YAML 配置（default.yaml + config.example.yaml）
│   ├── default.yaml           # 默认配置（无需修改即可运行）
│   ├── config.example.yaml    # 带注释的完整配置模板
│   └── loader.py              # 配置加载器（YAML + 环境变量合并）
├── docker/                    # Docker 部署
│   ├── Dockerfile             # 多阶段构建，基于 python:3.11-slim
│   └── docker-compose.yml     # 网关 + Ollama + ChromaDB 编排
├── tests/                     # 162 个测试
│   ├── test_mcp.py            # MCP 协议单元测试（pytest 自动发现）
│   ├── test_integration.py    # 集成测试（pytest 自动发现）
│   ├── test_security.py       # 56 项安全专项测试（pytest 自动发现）
│   ├── test_agent.py          # 调度测试（pytest 自动发现）
│   ├── test_scenarios.py      # 端到端场景测试（独立运行: python tests/test_scenarios.py --all）
│   └── benchmark.py           # 性能基准（独立运行）
├── docs/                      # 文档 + 截图 + 架构图 + 性能图表
│   ├── assets/                # 架构图 SVG + 性能图表 PNG
│   ├── screenshots/           # 实机运行截图
│   ├── 错误码对照表.md         # JSON-RPC 错误码定义
│   └── smoke_test.py          # 冒烟测试（独立运行）
├── scripts/                   # 辅助脚本
│   ├── setup_mcp.py           # 一键配置 Trae / Cursor / VS Code
│   └── gen_perf_chart.py      # 性能图表生成（matplotlib）
└── requirements/
    ├── runtime.txt            # 运行时依赖（pip install）
    └── dev.txt                # 开发依赖（测试 + 代码风格）

内置工具

体验全部工具：python main.py --demo

运行模式

高级启动选项：

python main.py --host 0.0.0.0 --port 9090          # 自定义监听地址
python main.py --config config/myconfig.yaml        # 自定义配置文件
python main.py --mode stdio 2>gateway.log           # STDIO 模式，日志重定向

平台接入

Trae / Cursor 接入

在 MCP 设置中添加：

{
  "mcpServers": {
    "agent-mcp-gateway": {
      "command": "python",
      "args": ["F:/项目路径/main.py", "--mode", "stdio"],
      "env": {
        "MCP_API_KEY": "your-api-key",
        "MCP_WORKSPACE": "F:/项目路径"
      }
    }
  }
}

一键配置脚本：python scripts/setup_mcp.py

Dify 接入

在「自定义工具」中导入 OpenAPI Schema：

• Schema URL：http://localhost:9090/api/v1/openapi.json
• 认证方式：X-API-Key 请求头

图：Dify 自定义工具 — 导入 OpenAPI Schema

实测运行截图：

图左：状态仪表盘 · 图右：Trae MCP 工具列表

配置说明

默认配置位置

配置文件位于 config/ 目录：

config/
├── default.yaml            # 默认配置（无需修改即可运行）
└── config.example.yaml     # 带注释的完整配置模板（自定义时参考）

配置优先级

高  环境变量 ${VAR_NAME}          (如 export MCP_SERVER_PORT=8080)
 ↓  自定义配置文件 --config path   (如 python main.py --config config/myconfig.yaml)
低  默认配置文件 default.yaml     (无需修改)

关键配置项速查

自定义配置步骤

# 1. 复制模板
cp config/config.example.yaml config/myconfig.yaml

# 2. 修改配置（编辑文件）
# 3. 使用自定义配置启动
python main.py --config config/myconfig.yaml

多租户

网关内置多租户能力，不同接入端使用不同的 API Key 隔离资源。

默认租户

使用方式

HTTP 请求时在 Header 中传入 API Key：

# 使用 admin 权限
curl.exe -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: admin-key-001" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

# 使用 ollama 租户
curl.exe -X POST http://localhost:9090/api/v1/tools/call \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ollama-key-001" \
  -d '{"tool":"llm_call","params":{"prompt":"hello"}}'

自定义租户

编辑 config/config.example.yaml 中的 tenancy 段：

tenancy:
  enabled: true
  tenants:
    - id: "my_tenant"
      label: "自定义租户"
      api_keys: ["my-custom-key"]
      file_whitelist: ["/my/project/path"]
      allowed_tools: ["read_file", "write_file", "run_command"]

支持租户列表查询：

curl.exe -s http://localhost:9090/api/v1/tenants -H "X-API-Key: admin-key-001"

Docker 部署

构建镜像

docker build -t mcp-gateway -f docker/Dockerfile .

使用 docker-compose 启动

# 启动网关 + Ollama + ChromaDB
cd docker
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看网关日志
docker-compose logs -f mcp-tool-gateway

访问服务

• 网关：http://localhost:9090
• Ollama：http://localhost:11434
• ChromaDB：http://localhost:8000

验证部署

# 健康检查
curl.exe -s http://localhost:9090/api/v1/health

# 工具列表
curl.exe -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

docker-compose 服务说明

安全设计

网关内置三层安全防护：

安全能力通过 56 项专项测试量化验证：

运行安全测试：python -m pytest tests/test_security.py -v

结构化日志

所有日志统一输出 JSON 格式到 stderr，每个请求自动分配唯一 request_id 贯穿全链路：

{"t": "2026-06-27T10:30:00.123", "rid": "abc123", "mod": "mcp_gateway.server",
 "lvl": "INFO", "msg": "收到请求 tools/list", "dur": "0.5ms", "err": ""}

{"t": "2026-06-27T10:30:00.456", "rid": "abc123", "mod": "mcp_gateway.protocol",
 "lvl": "INFO", "msg": "中间件管道执行完成", "dur": "0.3ms", "err": ""}

{"t": "2026-06-27T10:30:01.234", "rid": "def456", "mod": "mcp_gateway.tools.filesystem",
 "lvl": "WARN", "msg": "路径穿越拦截: ../../../etc/passwd", "dur": "0.1ms",
 "err": "-32001"}

日志字段说明：

典型排查流程：

# 启动网关，日志重定向到文件
python main.py 2>gateway.log

# 按 request_id 追踪一次完整调用（PowerShell）
cat gateway.log | Select-String '"rid":"abc123"' | python -m json.tool

# 统计各模块耗时
cat gateway.log | python -c "
import sys, json
for line in sys.stdin:
    try:
        e = json.loads(line)
        print(f'{e[\"rid\"]} {e[\"mod\"]} {e[\"dur\"]} {e[\"msg\"]}')
    except: pass
"

测试指南

测试入口说明

为什么 test_scenarios.py 不通过 pytest 运行？ 端到端场景测试需要启动子进程（模拟 Trae STDIO 客户端和 Dify HTTP 客户端），在 CI 环境中子进程可能因端口占用或网络问题超时。因此标记为 __test__ = False，用 python 直接运行。

运行全部测试

# 1. 运行 pytest 测试（161 项）
python -m pytest tests/ -v --tb=short

# 2. 运行端到端场景测试（独立进程）
python tests/test_scenarios.py --all

# 3. 检查代码风格
ruff check . --select=E,F,W --ignore=E501

测试样例：缓存命中率

python main.py --status 默认显示缓存命中率为 0.0%（刚启动，无缓存）。以下演示缓存生效过程：

场景：重复读取同一文件

# 第一次请求（缓存未命中）：
# curl 调用 read_file → 缓存中没有 → 读取磁盘 → 写入缓存
curl.exe -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: admin-key-001" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"read_file","arguments":{"path":"main.py"}}}'

# 第二次请求（缓存命中）：
# curl 再次调用 read_file → 缓存中有 → 直接返回，不读磁盘
curl.exe -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: admin-key-001" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"read_file","arguments":{"path":"main.py"}}}'

# 查看状态（观察缓存命中率上升）
python main.py --status

使用 --demo 模式观察缓存效果：

python main.py --demo
# 输出中会显示缓存统计：
#   → Cache hit rate: xx.x%
#   → Tokens saved: xxx
#   → Token save rate: xx.x%

图：性能基准 — 缓存命中率 42.9% / 并行吞吐 2.8x / 错误码覆盖 100%（benchmark.py 实测）

质量保障

• 全部测试：pytest（161 passed, 1 skipped — Windows 符号链接专用）
• 安全专项：pytest tests/test_security.py -v（56 passed）
• 端到端验证：python tests/test_scenarios.py --all
• 代码风格：ruff check .（0 errors）
• 冒烟测试：python docs/smoke_test.py

文档体系

版本演进

License

MIT