@onebullex-group/mcp

MCP server for OneBullEx Open API V2.

把 @onebullex-group/cli 的 60 个端点暴露成 MCP tools， 让 Claude Code / Cursor 直接调用。读工具直通；写工具默认 dry-run， 必须传 confirm: true 才真的发请求。

Install

npm i -g @onebullex-group/mcp

Configure (Claude Code)

~/.claude/mcp_settings.json（路径以 Claude Code 当前版本为准）：

{
  "mcpServers": {
    "onebullex": {
      "command": "npx",
      "args": ["-y", "@onebullex-group/mcp", "--profile", "test"]
    }
  }
}

或直接用全局安装的 onebullex-mcp：

{
  "mcpServers": {
    "onebullex": {
      "command": "onebullex-mcp",
      "args": ["--profile", "test"]
    }
  }
}

Configure (Cursor)

仓库根放 .cursor/mcp.json：

{
  "mcpServers": {
    "onebullex": {
      "command": "onebullex-mcp",
      "args": ["--profile", "test"]
    }
  }
}

Tools

服务器暴露 60 个 tools，每个对应 V2 文档里的一个端点：

• 读工具（40 个）：公开行情 + 私有只读，annotations 标 readOnlyHint: true
• 写工具（20 个）：下单 / 撤单 / 改杠杆 / 平仓，annotations 标 destructiveHint: true， inputSchema 强制要求 confirm: boolean

工具名是从 CLI registry 自动派生的 snake_case： order_create / mark_price_get / position_change_type / ...

Credentials

按以下优先级加载：

1. --profile <name> flag
2. ONEBULLEX_PROFILE / ONEBULLEX_API_KEY / ONEBULLEX_SECRET / ONEBULLEX_BASE_URL 环境变量
3. ~/.onebullex/config.json

安全约束：本服务器拒绝通过 flag 传 api-key 或 secret （它们在 ps 里会被看到）。请改用 config 文件或环境变量。

Write-op safety

任何 destructiveHint: true 的工具都要求传 { confirm: true } （严格 boolean，不接受字符串 "true"）才会真发请求。否则返回：

{
  "dryRun": true,
  "request": {
    "method": "POST",
    "path": "/v2/order/create",
    "body": { "symbol": "btc_usdt", "...": "..." }
  },
  "message": "Pass confirm:true to execute. Review the body carefully before confirming."
}

AI 端的纪律由 @onebullex-group/skill （Phase 4）配套提供： SKILL.md 教模型先 dry-run、给用户看预览、等用户确认后再 confirm: true。

How tools are derived

启动时把 @onebullex-group/cli 的 REGISTRY 表 + 每个命令文件用 ts-morph 做 commander option 的静态分析合并出 tools 列表。CLI 加新端点时， MCP 工具会自动出现，无需手工同步。

Local dev

cd mcp
pnpm install
pnpm test            # 28 unit + integration cases
pnpm typecheck
pnpm build
node dist/index.js --help

stdio 烟测：

(echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'; \
 echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'; \
 echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}') \
| ONEBULLEX_BASE_URL=https://x.example node dist/index.js --profile test

License

MIT