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）"}
    ]
  }
}

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

                    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 推理                        │
                    └────────────────────────────────────┘

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

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

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

# 使用 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"}}'

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 build -t mcp-gateway -f docker/Dockerfile .

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

# 查看服务状态
docker-compose ps

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

# 健康检查
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":{}}'

{"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
"

# 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

# 第一次请求（缓存未命中）：
# 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

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