ZebPay MCP Server

Zebpay MCP 服务

面向 Zebpay 现货和期货 API 的生产就绪型 TypeScript MCP (Model Context Protocol) 服务，仅使用 stdio 传输。 Model Context Protocol (MCP) 是一种标准方式，让 AI 助手能够安全地调用工具和数据源。 该服务专为 Cursor、Claude Desktop 和 MCP Inspector 等 MCP 客户端设计，通过本地进程执行进行连接。 服务提供市场数据和交易工作流，并具备严格的验证、安全的错误处理以及便于开发者使用的可观测性。

此服务提供的功能

• 公共市场数据工具（现货 + 期货）
• 私有交易/账户工具（需要 API 凭据）
• 面向 Agent 工作流的 MCP 资源和提示词
• 使用 Zod 进行请求验证
• 结构化错误处理和可选的文件日志记录

功能

• 仅使用 stdio 的 MCP 服务，可安全地与 MCP 客户端进行本地集成
• 覆盖现货和期货 API，支持公共和经过身份验证的操作
• 私有端点使用基于 HMAC 的身份验证请求流程
• 输入验证和标准化 MCP 错误响应
• 外发请求重试和超时控制
• 可选的结构化文件日志记录，便于调试和审计

支持的工具

现货（公共 + 私有）

• 市场数据：行情、订单簿、交易、K 线、交易所信息、货币
• 交易：下达市价/限价订单、取消订单、按交易对取消订单、取消所有订单
• 账户：余额、未结订单、订单历史、交易历史、交易所手续费
• 工具名称示例：
  • zebpay_public_getTicker
  • zebpay_public_getOrderBook
  • zebpay_spot_placeMarketOrder
  • zebpay_spot_placeLimitOrder
  • zebpay_spot_getBalance

期货（公共 + 私有）

• 市场数据：健康状态、市场、市场信息、订单簿、24 小时行情、聚合交易
• 交易/账户：钱包余额、下达订单、增加/减少保证金、未结订单、持仓
• 历史记录：订单历史、关联订单、交易历史、交易记录历史
• 工具名称示例：
  • zebpay_futures_public_getMarkets
  • zebpay_futures_public_getOrderBook
  • zebpay_futures_placeOrder
  • zebpay_futures_getWalletBalance
  • zebpay_futures_getPositions

技术栈

• Node.js (ESM)
• TypeScript
• @modelcontextprotocol/sdk
• undici
• zod

项目结构

src/
├── index.ts                  # Stdio MCP server entrypoint
├── mcp/                      # Tools, resources, prompts, MCP errors/logging
├── private/                  # Authenticated Zebpay clients
├── public/                   # Public market-data clients
├── security/                 # Credentials + signing helpers
├── http/                     # Shared outbound HTTP client to Zebpay APIs
├── validation/               # Schemas and validation helpers
├── utils/                    # Caching, metrics, formatting, file logging
└── types/                    # Shared response types

先决条件

• Node.js 20+
• npm 9+
• Zebpay API 凭据（用于私有工具）
• 请从官方 ZebPay API 门户创建 API 密钥/密钥：https://api.zebpay.com/

创建 ZebPay API 密钥

按照以下步骤为此 MCP 服务生成 API 凭据：

1. 打开 ZebPay API 门户：https://api.zebpay.com/
2. 登录你的 ZebPay 账户。
3. 前往 API 交易，然后点击 创建新的 API 密钥。
4. 输入密钥详情：
   • 密钥名称（例如：zebpay-mcp-local）
   • 所需权限（查询市场/账户时使用只读权限，仅在需要时授予交易权限）
   • 可选 IP 白名单（建议设置以增强安全性）
5. 完成 OTP 验证。
6. 复制并保存：
   • API Key
   • Secret Key（仅显示一次）

然后将它们添加到本地 .env 文件：

ZEBPAY_API_KEY=your_api_key
ZEBPAY_API_SECRET=your_api_secret

安全提示：

• 切勿将 API 密钥/密钥提交到 git。
• 尽量使用最小权限的 API 权限。
• 如果密钥泄露，请立即轮换。

设置

git clone <your-repo-url>
cd zebpay-mcp-server
npm install
cp env.example .env

更新 .env（所有值均从环境中读取；代码中没有后备默认值）：

ZEBPAY_API_KEY=your_api_key    # Use the API key from the step above
ZEBPAY_API_SECRET=your_api_secret    # Use the Secret key from the step above
ZEBPAY_SPOT_BASE_URL=https://sapi.zebpay.com/api/v2
ZEBPAY_FUTURES_BASE_URL=https://futuresbe.zebpay.com/api/v1
ZEBPAY_MARKET_BASE_URL=https://www.zebapi.com/api/v1/market
MCP_TRANSPORTS=stdio
LOG_LEVEL=info
HTTP_TIMEOUT_MS=15000
HTTP_RETRY_COUNT=2

构建和运行

npm run build
npm start

可选的文件日志记录：

npm run start:log

MCP 客户端配置（Stdio）

MCP 客户端配置示例：

{
  "mcpServers": {
    "zebpay": {
      "command": "node",
      "args": [
          "/absolute/path/to/zebpay-mcp-server/dist/index.js"
        ],
      "env": {
        "ZEBPAY_API_KEY": "YOUR_API_KEY_HERE",
        "ZEBPAY_API_SECRET": "YOUR_API_SECRET_HERE",
        "LOG_LEVEL": "info"
      }
    }
  }
}

另请参阅：mcp-config.json.example。

环境变量

Variable	Required	Description	Example value
ZEBPAY_API_KEY	是	Zebpay API 密钥（私有工具必需）	YOUR_API_KEY_HERE
ZEBPAY_API_SECRET	是	Zebpay API 密钥（私有工具必需）	YOUR_API_SECRET_HERE
MCP_TRANSPORTS	是	必须为 stdio	stdio
ZEBPAY_SPOT_BASE_URL	是	现货 API 基础 URL	https://www.zebapi.com/api/v2
ZEBPAY_FUTURES_BASE_URL	是	期货 API 基础 URL	https://futures-api.zebpay.com/api/v1
ZEBPAY_MARKET_BASE_URL	是	市场 API 基础 URL	https://www.zebapi.com/api/v1/market
LOG_LEVEL	是	debug、info、warn、error	info
LOG_FILE	否	日志文件路径	logs/mcp-server.log
HTTP_TIMEOUT_MS	是	出站请求超时时间（毫秒）	15000
HTTP_RETRY_COUNT	是	出站请求重试次数	2

开发者命令

npm run build
npm test
npm run test:watch
npm run logs
npm run logs:watch
npm run logs:errors
npm run logs:stats
npm run logs:clear

日志记录

• 日志工具和示例：scripts/README.md
• 完整的日志文档：docs/LOGGING.md
• 请勿将日志提交到 Git（logs/ 已被忽略）

问题反馈

发现错误或想要请求新功能？

• 在此仓库的 GitHub Issues 选项卡中创建问题。
• 也可以先替换 <your-org> 和 <your-repo>，再使用以下直接链接：
  • 错误报告：https://github.com/<your-org>/<your-repo>/issues/new?template=bug_report.md
  • 功能请求：https://github.com/<your-org>/<your-repo>/issues/new?template=feature_request.md
• 请提供以下信息，以便更快地进行问题分类：
  • 使用的 MCP 客户端（Cursor/Claude Desktop/其他）
  • Node.js 版本和操作系统
  • 最简复现步骤
  • 相关日志（请隐去密钥）

许可证

MIT