内容
# 黄色专业版MCP
English | [简体中文](README.zh-CN.md)
MCP服务器 + CLI，暴露 **黄色专业版** 交易所给AI代理 — Claude Code、
Codex CLI、OpenClaw、Cursor，或任何MCP客户端。市场数据、账户状态和
（当显式启用时）交易。
遵循与官方OKX / Bybit / Alpaca交易所MCP服务器相同的约定：本地标准输入输出进程，
凭证保留在您的机器上（环境变量或MCP客户端的本地配置 — 绝不发送到其他地方），
**默认只读**，模块过滤，内置速率限制，以及CLI和非MCP代理的代理技能文件。
## 一行安装（适用于代理和人类）
从GitHub安装并使用Claude Code注册：
```bash
curl -fsSL -H 'Accept: application/vnd.github.raw+json' \
'https://api.github.com/repos/layer-3/yellow-pro-mcp/contents/install.sh?ref=main' | bash && \
YELLOW_PRO_API_KEY=... YELLOW_PRO_API_SECRET=... YELLOW_PRO_APP_SESSION_ID=... \
yellow-pro setup claude-code
```
安装程序检查Node.js >= 18，在临时目录中构建，安装打包的tarball并全局删除临时文件。
如果系统npm前缀不可写，则在`~/.local`下安装。检查
`install.sh`在运行它之前，如果您的环境不允许`curl | bash`。
然后使用已安装的服务器注册任何MCP客户端，例如Claude Code：
```bash
claude mcp add yellow_pro -s user \
-e YELLOW_PRO_API_KEY=... -e YELLOW_PRO_API_SECRET=... -e YELLOW_PRO_APP_SESSION_ID=... \
-- yellow-pro-mcp
```
仓库是公开的，因此安装不需要GitHub凭证。
多客户端设置 — 每个客户端使用当前的
`YELLOW_PRO_*`环境注册MCP服务器：
```bash
yellow-pro setup claude-code # 通过`claude mcp add`（用户范围）
yellow-pro setup codex # 通过`codex mcp add`，回退到config.toml片段
yellow-pro setup openclaw # 编写~/.openclaw/openclaw.json mcpServers条目
yellow-pro setup hermes # 通过`hermes mcp add`，回退到config.yaml片段
yellow-pro setup json # 为任何其他客户端打印通用MCP JSON
```
`npm i -g`（或本地checkout：`npm i -g /path/to/yellow_pro_mcp`）为您提供两个
命令：`yellow-pro-mcp`（MCP服务器）和`yellow-pro`（CLI）。
### 手动配置（任何MCP客户端）
```toml
# Codex CLI (~/.codex/config.toml)
[mcp_servers.yellow_pro]
command = "yellow-pro-mcp"
env = { YELLOW_PRO_API_KEY = "...", YELLOW_PRO_API_SECRET = "...", YELLOW_PRO_APP_SESSION_ID = "..." }
```
```json
// OpenClaw (~/.openclaw/openclaw.json), Claude Desktop, Cursor, ...
{ "mcpServers": { "yellow_pro": { "command": "yellow-pro-mcp", "env": { "YELLOW_PRO_API_KEY": "..." } } } }
```
### 代理技能（非MCP代理）
`skills/yellow-pro/SKILL.md`教导代理如何使用`yellow-pro` CLI — 将其复制到
您的代理技能目录（例如`~/.claude/skills/yellow-pro/`）。
## 配置
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `YELLOW_PRO_BASE_URL` | 否 | 由`YELLOW_PRO_SANDBOX`选择 | 显式REST基准URL覆盖 |
| `YELLOW_PRO_SANDBOX` | 否 | `false` | 恰好`true`使用预发布环境（`https://api.staging.yellow.pro.neodax.app`）；否则生产环境（`https://trade.api.yellow.pro`） |
| `YELLOW_PRO_API_KEY` | 私有工具 | — | API密钥 |
| `YELLOW_PRO_API_SECRET` | 私有工具 | — | API密钥（HMAC-SHA256） |
| `YELLOW_PRO_APP_SESSION_ID` | 私有工具 | — | 应用会话ID（`uid`凭证） |
| `YELLOW_PRO_ENABLE_TRADING` | 否 | 关闭 | 恰好`true`启用交易工具/命令 |
| `YELLOW_PRO_MODULES` | 否 | 所有 | `market,account,trading`过滤工具的逗号列表 |
| `YELLOW_PRO_RATE_LIMIT_MS` | 否 | `100` | 请求之间的最小间隔（毫秒） |
除非`YELLOW_PRO_ENABLE_TRADING=true`，否则交易工具 **未注册**。
市场数据工具无需凭证即可工作。
显式的`YELLOW_PRO_BASE_URL`优先于预发布模式。
## 工具
- **市场**：`get_health`、`get_markets`、`get_ticker`、`get_orderbook`、`get_klines`、
`get_funding_rate`、`get_funding_rate_history`、`get_networks`、`get_transfer_assets`
- **账户**：`get_balance`、`get_open_orders`、`get_order_history`、`get_my_trades`、
`get_positions`、`get_position_history`、`get_position_history_detail`、
`get_spot_accounts`、`get_spot_account`、`get_perpetual_accounts`、`get_fee_schedule`、
`get_fee_tier`、`get_market_fee_rate`、`get_transaction_history`、`get_funding_payments`
- **交易**（按需）：`place_order`、`cancel_order`、`cancel_all_orders`、
`close_positions`、`set_leverage`、`transfer`
市场使用原生ID：现货`ETHUSDT`，永续`BTCUSDT-PERP`。
金额和价格是十进制字符串。所有结果都是原始交易所JSON。
`place_order`支持现货和永续的相同通用单订单类型：
- `limit`：需要`price`
- `market`：无`price`
- `post_only`：需要`price`，并保证订单仅为做市商
- `trigger_limit`（止损限价）：需要`trigger_price`和`price`
- `trigger_market`（止损市价）：需要`trigger_price`
永续触发订单还接受可选的`trigger_type`值
`stop_loss`或`take_profit`。订单查询返回分类的条件类型，
例如`stop_limit`、`stop_loss`、`take_limit`或`take_profit`。
`cancel_order`接受请求类型（`trigger_*`）或这些返回
类型并标准化现货取消。
大多数列表工具使用记录的按需游标协议。省略`cursor`表示
第一个请求；MCP发送`use_cursor=true`。传递返回的
`next_cursor`以获取下一页。`page_size`默认为50，最高
上限为100。填充级别的位置历史记录是原生游标：其第一个请求省略
`cursor`和`use_cursor`，其记录的`page_size`最大值为500。
`yellow-pro` CLI镜像相同的界面 — `yellow-pro --help`。
## 故障排除
**MCP客户端显示无工具 / 服务器无法连接**
- 通过CLI注册（`yellow-pro setup claude-code`或`claude mcp add`
直接）而不是手动编辑配置文件 — Claude Code从`~/.claude.json`读取MCP配置，
而不是`~/.claude/settings.json`。
- 客户端在不加载shell配置文件的情况下启动服务器，因此
`yellow-pro-mcp`必须在客户端的`PATH`上。检查`which yellow-pro-mcp`；
如果安装程序打印了PATH提示，请将该目录添加到您的配置文件中并
重启客户端。
- 在更改MCP配置后重启客户端 — 服务器在会话启动时连接。
- 验证服务器本身启动：
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | yellow-pro-mcp
```
**身份验证错误（`invalid_api_key`，`invalid_timestamp`）**
- 私有工具需要`YELLOW_PRO_API_KEY`、`YELLOW_PRO_API_SECRET`、
`YELLOW_PRO_APP_SESSION_ID`全部三个，并且它们必须与您访问的环境相匹配
（`YELLOW_PRO_SANDBOX=true`密钥在生产环境中无效，反之亦然）。
- `invalid_timestamp`表示机器时钟与交易所的时钟相差超过几秒钟 —
同步它（例如`sudo sntp -sS time.apple.com`在macOS上，`chrony`/`ntp`
在Linux上）。
**交易命令因“交易已禁用”而失败**
在MCP客户端的环境配置中设置`YELLOW_PRO_ENABLE_TRADING=true`。这是
故意的 — 不要通过直接调用REST API来绕过它。
## 风险警告
交易涉及损失风险。在使用之前：
- **保护您的凭证** — 授予API密钥所需的最低权限，并
绝不将它们提交到源代码控制中。
- **先在预发布环境中测试** — 在指向生产环境之前，使用`YELLOW_PRO_SANDBOX=true`运行在预发布环境中。
- **交易默认关闭** — 订单/放置工具仅在
`YELLOW_PRO_ENABLE_TRADING=true`时存在。审查代理提出的每个订单，然后
再让它通过。
- **您在控制中** — 所有操作由您或您的AI助手发起；
维护人员不负责代理行为导致的损失。
## 开发
```bash
npm install
npm test # 签名向量（与参考实现交叉检查）+ 工具注册
npm run build
```
端点和请求合约遵循当前的
[黄色专业版API文档](https://docs.yellow.pro/api-and-programmatic-access/overview)。
故意不实现：EIP-191/JWT身份验证和WebSocket流。
