MCP Gateway

🚀 MCP网关系统

MCP网关系统用于协调多个能力提供者，借助Model Context Protocol (MCP) 实现不同语言特定提供者的协同工作，为市场数据分析提供了强大支持。

🚀 快速开始

使用Claude Code 🤖

MCP网关与Claude Code无缝集成，配置完成后，你可以用自然语言提问：

你："生成一份比特币的综合市场报告"
Claude：[使用binance.generate_market_report工具]
响应：
# 市场数据报告 - BTCUSDT
生成时间：2025-10-24 12:00:00 UTC 🟢

## 价格概览
- 当前价格：$106,841.00 📈
- 24小时变化：+0.43% (+$459.00)
- 24小时最高/最低：$107,200.00 / $105,800.00
- 交易量：1,234.56 BTC ($131.8M)

## 订单簿指标
- 买卖价差：0.01% (1.0 bps)
- 微观价格：$106,840.50
- 买卖失衡：58% 买盘占优 📊

## 流动性分析
- 买单墙：$106,500 💪 强劲 (125.5 BTC)
- 成交量分布图POC：$106,750
[... 还有5个部分 ...]

你："仅显示ETHUSDT的价格和流动性部分"
Claude：[使用带自定义选项的generate_market_report]
响应：[仅包含请求部分的Markdown报告]

你："分析比特币的交易机会"
Claude：[使用带有实时市场数据的trading-analysis提示]
响应：[结合报告数据和AI洞察的详细分析]

Claude Code的设置步骤：

# 配置MCP服务器（已在.claude/settings.json中完成）
claude mcp add --transport stdio mcp-gateway -- \
  bash -c "cd mcp-gateway && uv run python -m mcp_gateway.main"

# 启动会话
claude  # MCP网关将自动启动

使用ChatGPT 🤖 🆕

MCP网关现在可通过SSE传输与ChatGPT集成，统一的市场数据报告提供了全面的市场情报！ ChatGPT的设置步骤：

1. 在ChatGPT中启用开发者模式（需要Plus/Pro版本）
2. 进入设置 → MCP服务器 → 添加服务器
3. 配置SSE端点：
   • 服务器URL：https://mcp-gateway.thevibe.trading/sse/
   • 传输方式：SSE（服务器发送事件）

使用示例：

你："生成一份BTCUSDT的完整市场报告"
ChatGPT：[使用binance_generate_market_report工具]
响应：[包含8个部分的完整Markdown报告：价格、订单簿、流动性、异常情况、健康状况等 - 缓存60秒]

你："仅显示ETHUSDT的价格和流动性分析"
ChatGPT：[使用带选项的binance_generate_market_report]
请求：{"symbol": "ETHUSDT", "options": {"include_sections": ["price_overview", "liquidity_analysis"]}}
响应：[仅包含请求部分的自定义报告]

你："BTCUSDT的订单簿健康状况如何？"
ChatGPT：[使用binance_orderbook_health工具 - 旧版单个工具]
响应：[快速的健康指标快照]

详细的设置指南请参考 CHATGPT_INTEGRATION.md。

手动设置

前提条件

• 安装Python 3.11+ 并带有uv
• 安装Go 1.21+（用于hello-go提供者）
• 安装Rust 1.75+（用于binance-rs提供者）
• 安装Protocol Buffers编译器（protoc）

构建所有提供者

# 生成protobuf存根
make proto-gen

# 构建Go提供者
cd providers/hello-go && go build -o bin/hello-go cmd/server/main.go

# 构建Rust提供者
make build-binance

运行系统

终端1 - 启动提供者：

# hello-go
make run-hello-go

# binance-rs（在另一个终端中）
make run-binance

终端2 - 启动网关：

make run-gateway

配置

在 mcp-gateway/providers.yaml 中配置提供者：

providers:
  - name: hello-go
    type: grpc
    address: localhost:50051
    enabled: true

  - name: binance-rs
    type: grpc
    address: localhost:50053
    enabled: true
    metadata:
      description: "Binance加密货币交易提供者"
      features: ["orderbook"]

对于binance-rs，还需要设置环境变量：

export BINANCE_API_KEY="your_api_key"
export BINANCE_API_SECRET="your_api_secret"
export BINANCE_BASE_URL="https://testnet.binance.vision"

✨ 主要特性

• 架构升级：实现分布式MCP架构，通过Python网关借助gRPC协调多个语言特定的提供者。
• 功能转变：从混合读写交易客户端转变为只读市场数据分析工具，移除了所有订单管理功能。
• 统一报告：引入统一的市场数据报告API，保留并增强了所有市场数据分析功能。
• 多平台集成：支持与Claude Code和ChatGPT集成，提供自然语言交互体验。

📦 安装指南

前提条件

• Python 3.11+ 并带有uv
• Go 1.21+（用于hello-go提供者）
• Rust 1.75+（用于binance-rs提供者）
• Protocol Buffers编译器（protoc）

构建步骤

# 生成protobuf存根
make proto-gen

# 构建Go提供者
cd providers/hello-go && go build -o bin/hello-go cmd/server/main.go

# 构建Rust提供者
make build-binance

运行步骤

终端1 - 启动提供者：

# hello-go
make run-hello-go

# binance-rs（在另一个终端中）
make run-binance

终端2 - 启动网关：

make run-gateway

配置步骤

在 mcp-gateway/providers.yaml 中配置提供者：

providers:
  - name: hello-go
    type: grpc
    address: localhost:50051
    enabled: true

  - name: binance-rs
    type: grpc
    address: localhost:50053
    enabled: true
    metadata:
      description: "Binance加密货币交易提供者"
      features: ["orderbook"]

对于binance-rs，还需要设置环境变量：

export BINANCE_API_KEY="your_api_key"
export BINANCE_API_SECRET="your_api_secret"
export BINANCE_BASE_URL="https://testnet.binance.vision"

💻 使用示例

基础用法

生成完整报告（所有部分）

await client.generate_market_report(symbol="BTCUSDT")

生成自定义报告（特定部分）

await client.generate_market_report(
    symbol="ETHUSDT",
    options={
        "include_sections": ["price_overview", "liquidity_analysis"],
        "volume_window_hours": 48,
        "orderbook_levels": 50
    }
)

📚 详细文档

币安提供者

• 币安提供者指南 - 完整的提供者文档
• ChatGPT集成指南 - ChatGPT的SSE设置
• 集成测试 - 测试结果

网关与部署

• 手动测试指南 - 测试SSE端点
• 部署脚本 - 生产环境部署自动化
• 部署总结 - 最新的生产环境部署

规范文档

• 特性018：统一市场数据报告 🆕
  • 规范
  • 实施计划
  • 任务分解
  • 快速入门指南
• 特性002：币安提供者集成
  • 规范
  • 实施计划
  • 任务分解

变更日志

• CHANGELOG.md - 版本历史和迁移指南

🔧 技术细节

架构

AI客户端
    ├→ Claude Code (STDIO传输)
    │       ↓
    │   MCP网关 (Python)
    │       ├→ hello-go (Go提供者) - 演示工具
    │       ├→ hello-rs (Rust提供者) - 演示工具
    │       └→ binance-rs (Rust提供者) - 加密货币交易
    │
    └→ ChatGPT (SSE传输) 🆕
            ↓
        SSE网关 (Python)
            └→ binance-rs (Rust提供者) - 统一市场数据报告

生产部署

ChatGPT MCP服务器 (SSE传输)：

• URL：https://mcp-gateway.thevibe.trading/sse/
• 状态：✅ 生产环境运行
• 版本：0.2.0（只读市场数据分析）
• 特性：具有高级分析功能的统一市场情报报告
• 传输方式：服务器发送事件（SSE） - ChatGPT集成必需
• 文档：请参考 ChatGPT集成指南

提供者

hello-go

• 语言：Go
• 端口：50051
• 工具：echo.v1, sum.v1（演示工具）
• 状态：✅ 已实现

hello-rs

• 语言：Rust
• 端口：50052
• 工具：（待实现）
• 状态：🚧 计划中

binance-rs ⭐ 生产就绪

• 语言：Rust
• 端口：50053
• 状态：✅ 完全实现（只读市场数据分析）
• 版本：0.2.0

能力：

• 1个主要工具：🆕 统一市场数据报告

  • generate_market_report - 综合市场情报，结合8个以上数据部分
    • 价格概览（24小时统计数据和趋势指标）
    • 订单簿指标（买卖价差、微观价格、买卖失衡）
    • 流动性分析（买单墙、成交量分布图、流动性真空）
    • 市场异常情况（带严重程度标记的检测）
    • 微观结构健康状况（健康评分和组件状态）
    • 数据健康状态（WebSocket连接性、数据新鲜度）
    • 性能：60秒缓存，冷生成时间<500ms，缓存检索时间<3ms

• 11个独立分析工具（旧版，已被统一报告取代）：

  • get_ticker - 24小时价格统计数据
  • orderbook_l1 / orderbook_l2 - 订单簿快照
  • get_recent_trades - 交易历史
  • get_order_flow - 买卖压力跟踪
  • get_volume_profile - 成交量分布（POC/VAH/VAL）
  • detect_market_anomalies - 异常模式检测
  • get_microstructure_health - 市场健康评分
  • get_liquidity_vacuums - 低成交量价格区间检测
  • orderbook_health - 实时订单簿健康指标

• 1个资源：Markdown格式的数据快照

  • binance://market/{SYMBOL} - 实时市场摘要

• 1个提示：适用于AI的分析模板

  • trading-analysis - 带有实时上下文的市场分析

特性：

• ✅ 实时WebSocket订单簿流（延迟低于200ms）
• ✅ 来自币安API的实时市场数据
• ✅ 懒初始化和连接池
• ✅ 渐进式披露（按需从L1到L2深度）
• ✅ 支持20个并发符号订阅
• ✅ 测试网和生产模式

API参考

统一市场数据报告

工具：generate_market_report 生成综合市场情报报告，结合8个以上数据部分，具有智能缓存和自定义选项。

参数：

{
  "symbol": str,              # 必需：交易对（例如，"BTCUSDT", "ETHUSDT"）
  "venue": str,               # 可选：交易场所（默认："binance"）
  "options": {                # 可选：报告自定义
    "include_sections": list[str],  # 要包含的部分（默认：所有）
    "volume_window_hours": int,     # 成交量分析窗口（默认：24）
    "orderbook_levels": int         # 订单簿深度（默认：20）
  }
}

可用部分：

• "price_overview" - 24小时价格统计数据和趋势指标
• "orderbook_metrics" - 买卖价差、微观价格、买卖失衡
• "liquidity_analysis" - 流动性墙、成交量分布图、流动性真空
• "market_microstructure" - 订单流分析（占位符）
• "market_anomalies" - 带严重程度标记的异常检测
• "microstructure_health" - 健康评分和组件状态
• "data_health" - WebSocket连接性和数据新鲜度

响应：

{
  "markdown_content": str,     # 完整的格式化报告
  "symbol": str,               # 交易对
  "generated_at": int,         # Unix时间戳（毫秒）
  "data_age_ms": int,          # 数据新鲜度指标
  "failed_sections": list[str],# 生成失败的部分
  "generation_time_ms": int    # 报告生成时间
}

性能：

• 冷生成：<500ms
• 缓存检索：<3ms
• 缓存TTL：60秒
• 对缺失数据源进行优雅降级

从v0.1.0迁移： 如果你之前使用单个工具：

# 之前（v0.1.0 - 不再可用）
ticker = await client.get_ticker(symbol="BTCUSDT")
account = await client.get_account()
trades = await client.get_my_trades(symbol="BTCUSDT")

# 之后（v0.2.0 - 统一报告）
report = await client.generate_market_report(symbol="BTCUSDT")
# 访问report.markdown_content以获取格式化输出

完整的迁移指南请参考 CHANGELOG.md。

项目结构

mcp-trader/
├── mcp-gateway/          # Python MCP网关
│   ├── mcp_gateway/
│   │   ├── main.py      # FastMCP服务器（STDIO传输）
│   │   ├── sse_server.py # SSE服务器，用于ChatGPT 🆕
│   │   ├── adapters/    # gRPC客户端
│   │   ├── tools/       # 搜索和获取工具 🆕
│   │   └── validation.py
│   └── providers.yaml   # 提供者配置
├── providers/
│   ├── hello-go/        # Go演示提供者
│   ├── hello-rs/        # Rust演示提供者
│   └── binance-rs/      # 币安市场数据提供者（只读）
│       └── src/
│           ├── report/       # 统一报告生成器 🆕
│           └── orderbook/
│               └── analytics/  # 高级分析模块
├── infra/               # 生产部署 🆕
│   ├── deploy-chatgpt.sh        # ChatGPT SSE部署脚本
│   ├── binance-provider.service # Systemd服务
│   ├── mcp-gateway-sse.service  # SSE网关服务
│   └── nginx-mcp-gateway.conf   # NGINX反向代理
├── pkg/
│   ├── proto/           # 共享的protobuf合约
│   └── schemas/         # JSON模式
└── Makefile

📄 许可证

请查看LICENSE文件。