内容
# 工具列表
[](#license)
MCP 服务器，暴露 Nexus 交易所 API 作为 AI 代理（Claude Desktop / Claude Code）可以调用的工具，以读取市场数据和进行交易。
它与真实的公共交易所网关对话。市场数据和演示工具在无需配置的情况下工作；账户和交易工具使用从环境变量读取的 HMAC API 凭证。
## 当前功能
| 工具 | 状态 | 端点 |
| --- | --- | --- |
| `list_markets` | ✅ 运行（公共） | `GET /markets/summary` |
| `list_market_specs` | ✅ 运行（公共） | `GET /markets` |
| `get_ticker` | ✅ 运行（公共） | `GET /markets/{id}/ticker` |
| `get_tickers` | ✅ 运行（公共） | `GET /tickers` |
| `get_orderbook` | ✅ 运行（公共） | `GET /markets/{id}/orderbook` |
| `get_mark_price` | ✅ 运行（公共） | `GET /markets/{id}/mark-price` |
| `get_market_status` | ✅ 运行（公共） | `GET /markets/{id}/status` |
| `get_trades` | ✅ 运行（公共） | `GET /markets/{id}/trades` |
| `get_candles` | ✅ 运行（公共） | `GET /markets/{id}/candles` |
| `get_funding_history` | ✅ 运行（公共） | `GET /markets/{id}/funding` |
| `get_demo_account` | ✅ 运行（公共） | `GET /demo/account` |
| `get_demo_positions` | ✅ 运行（公共） | `GET /demo/positions` |
| `get_demo_orders` | ✅ 运行（公共） | `GET /demo/orders` |
| `get_balance` | ✅ 运行（需要密钥 + 直接网关） | `GET /account` |
| `get_positions` | ✅ 运行（需要密钥 + 直接网关） | `GET /positions` |
| `get_open_orders` | ✅ 运行（需要密钥 + 直接网关） | `GET /orders` |
| `get_order` | ✅ 运行（需要密钥 + 直接网关） | `GET /orders/{id}` |
| `get_fills` | ✅ 运行（需要密钥 + 直接网关） | `GET /fills` |
| `get_withdrawals` | ✅ 运行（需要密钥 + 直接网关） | `GET /withdrawals` |
| `get_rate_limit_status` | ✅ 运行（需要密钥 + 直接网关） | `GET /account/rate-limit` |
| `get_adl_history` | ✅ 运行（需要密钥 + 直接网关） | `GET /account/{addr}/adl-history` |
| `get_market_adl_events` | ✅ 运行（需要密钥 + 直接网关） | `GET /markets/{id}/adl-events` |
| `place_order` | ✅ 运行（需要密钥 + 直接网关） | `POST /orders` |
| `place_orders_batch` | ✅ 运行（需要密钥 + 直接网关） | `POST /orders/batch` |
| `cancel_order` | ✅ 运行（需要密钥 + 直接网关） | `DELETE /orders[/{id}]` |
| `deposit_collateral` | ✅ 运行（需要密钥 + 直接网关） | `POST /account/deposit` |
| `claim_credit` | ✅ 运行（需要密钥 + 直接网关） | `POST /account/credit` |
| `list_agents` | ✅ 运行（需要密钥 + 直接网关） | `GET /agents` |
| `register_agent` | ✅ 运行（需要调用者 EIP-712 签名） | `POST /agents/register` |
| `revoke_agent` | ✅ 运行（需要密钥 + 直接网关） | `DELETE /agents/{addr}` |
| `login` | ✅ 运行（需要调用者 EIP-191 签名） | `POST /auth/login` |
| `list_api_keys` | ✅ 运行（需要会话令牌） | `GET /keys` |
| `create_api_key` | ✅ 运行（需要会话令牌） | `POST /keys` |
| `delete_api_key` | ✅ 运行（需要会话令牌） | `DELETE /keys/{key_id}` |
| `get_ws_token` | ✅ 运行（需要密钥 + 直接网关） | `POST /ws/token` |
| `get_ws_token_legacy` | ✅ 运行（需要密钥 + 直接网关） | `POST /ws-tokens` |
| `get_health` | ✅ 运行（公共） | `GET /health` |
| `list_tiers` | 🔒 管理员（需开启，见下文） | `GET /admin/tiers` |
| `set_tier` | 🔒 管理员（需开启，见下文） | `PUT /admin/tiers` |
| `delete_tier` | 🔒 管理员（需开启，见下文） | `DELETE /admin/tiers/{addr}` |
| `get_deposit_target` | 🚧 待定 — 服务器端端点尚未构建 | 暂无 |
`get_deposit_target` 已接入代理流程，但返回清晰的 `not_yet_available` 消息，而不是伪造结果；当服务器端功能上线时，它就会亮起。
### API 表面覆盖
这些工具映射到 **40 个操作** 中的 **38 个**，位于 v0.4.0 OpenAPI 规范（`.api-version`）中。两个故意未映射的操作是 WebSocket **升级** 端点 `GET /ws` 和 `GET /stream` — 请求/响应 MCP 工具无法保持流式套接字打开，因此服务器改为颁发认证令牌（`get_ws_token` / `get_ws_token_legacy`），调用者使用它直接连接到它们。
### 授权层级
- **公共** — 无凭证。
- **HMAC（密钥 + 直接网关）** — 账户读取、交易、代理/资金操作。使用 `NEXUS_EXCHANGE_API_KEY` / `NEXUS_EXCHANGE_API_SECRET`。有关公共代理的身份验证说明，请参见下面的说明。
- **调用者签名** — `login`（EIP-191）和 `register_agent`（EIP-712）携带调用者外部生成的钱包签名；该服务器从不持有钱包密钥，无法为您签名。
- **会话令牌** — `*_api_key` 工具通过 `login` 发出的 Bearer 会话令牌进行身份验证，设置为 `NEXUS_EXCHANGE_SESSION_TOKEN`。
- **管理员（需开启）** — `list_tiers` / `set_tier` / `delete_tier` 使用操作员管理员密钥并修改其他账户的费率层级。它们 **未注册**，除非设置 `NEXUS_EXCHANGE_ENABLE_ADMIN_TOOLS=1`（并提供 `NEXUS_EXCHANGE_ADMIN_SECRET`）。请勿在不受信任的代理表面上启用这些。
破坏性工具（`revoke_agent`、`delete_api_key`、`delete_tier` 和 `cancel_order` 的批量取消）需要明确的 `confirm: true` / `cancel_all: true` 标志，以免意外造成损害。
## 快速开始
```bash
npm install
npm run build
npm start # 运行stdio MCP服务器
```
`npm start` 在stdio上等待MCP客户端；它旨在由Claude启动，而不是手动运行。要在没有客户端的情况下针对实时API进行端到端验证，请使用烟雾检查：
```bash
npm run smoke # 列出工具，对生产环境调用list_markets
```
预期输出以 `list_markets OK -> N markets` 结尾。
## 环境变量
复制 `.env.example` 并根据需要设置。仅交易/账户工具需要凭证 — 切勿提交真实密钥。
| 变量 | 必需 | 目的 |
| --- | --- | --- |
| `NEXUS_EXCHANGE_API_URL` | 否 | API基准URL。默认为 `https://exchange.nexus.xyz/api/exchange`。 |
| `NEXUS_EXCHANGE_API_KEY` | 账户/交易工具必填 | HMAC API密钥ID（`x-api-key`）。 |
| `NEXUS_EXCHANGE_API_SECRET` | 账户/交易工具必填 | HMAC密钥（十六进制）。 |
| `NEXUS_EXCHANGE_SESSION_TOKEN` | `*_api_key` 工具必填 | `login` 发出的Bearer会话令牌（`POST /auth/login`）。 |
| `NEXUS_EXCHANGE_ADMIN_SECRET` | 管理员工具必填 | 操作员管理员密钥（`ADMIN_SECRET`）。仅需开启以下标志。 |
| `NEXUS_EXCHANGE_ENABLE_ADMIN_TOOLS` | 否 | 设置为 `1` 以注册管理员层级工具。默认关闭。 |
## API 版本
<!-- api-version-sync:start -->
目前针对 Exchange API 规范 **`v0.4.0`**。
<!-- api-version-sync:end -->
固定的版本位于 [`.api-version`](./.api-version)；规范本身由
[`nexus-xyz/nexus-exchange-api`](https://github.com/nexus-xyz/nexus-exchange-api) 发布。
本仓库不提供规范副本 — `drift` CI 作业获取固定的发布版本以检查漂移，而计划的 `api-version-sync` 工作流在发布新规范时开启 PR。 上方的行由机器人管理；其周围的所有内容均为人工所有。
## 身份验证
签名请求使用索引器验证的相同规范 HMAC-SHA256 方案（`backend/services/indexer/src/auth.rs`）：
```text
<timestamp>\n<METHOD>\n<path>\n<query>\n<sha256hex(body)>
```
用十六进制解码的密钥签名并作为 `x-signature` 发送，附带 `x-api-key` 和 `x-timestamp`。
重要：默认公共基准URL（`/api/exchange`）是代理服务器，使用站点的前端密钥签名，因此它不尊重调用者的 HMAC 头部 —
通过它进行身份验证的工具解析为站点账户，而不是您的账户。要作为特定账户交易，请将 `NEXUS_EXCHANGE_API_URL` 指向直接索引网关，该网关验证客户端 HMAC（例如，交易所 `docker-compose` 的本地 `http://localhost:9090`）。直到那时，请使用公共 `get_demo_*` 工具在无密钥的情况下演示账户流程。
## Claude Desktop 配置
将以下内容添加到您的 Claude Desktop 配置文件
（`~/Library/Application Support/Claude/claude_desktop_config.json` 在 macOS 上），
调整到此软件包的 `dist/index.js` 的绝对路径：
```json
{
"mcpServers": {
"nexus-exchange": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/nexus-exchange-mcp/dist/index.js"],
"env": {
"NEXUS_EXCHANGE_API_URL": "https://exchange.nexus.xyz/api/exchange"
}
}
}
}
```
要启用交易，请在 `env` 块中添加 `NEXUS_EXCHANGE_API_KEY` / `NEXUS_EXCHANGE_API_SECRET`，
并将 `NEXUS_EXCHANGE_API_URL` 设置为直接网关。
## 演示脚本
1. 添加上述配置，重启Claude Desktop，并确认`nexus-exchange`出现在工具列表中。
2. 询问：“显示Nexus上的BTC市场” — Claude 调用 `list_markets` / `get_ticker` 并报告实时BTC-USDX-PERP价格。
3. 询问：“演示账户及其开放仓位中有什么？” — Claude 调用 `get_demo_account` 和 `get_demo_positions` 对实时交易所。
## 主机HTTP服务器（远程MCP）
上述stdio服务器在本地运行并持有您的API密钥。托管的 **Streamable HTTP** 服务器是远程入口 —
它允许交易者添加Nexus作为远程MCP服务器，而无需在本地运行任何持有密钥的软件。
```bash
npm run build
npm run start:http # 监听 :8080，MCP 端点在 /mcp，探测在 /healthz
```
在TLS终止入口后面，这是公共端点
`https://mcp.exchange.nexus.xyz/mcp`。客户端通过以下方式添加它：
```bash
claude mcp add --transport http nexus https://mcp.exchange.nexus.xyz/mcp
```
它公开的工具表面与stdio服务器 **相同** —
两个传输都通过 `src/server.ts` 中的 `createServerForClient` 注册相同的 `ToolDef[]`，因此工具永远不会漂移。传输是SDK的 `StreamableHTTPServerTransport` 在有状态模式（每个 `mcp-session-id` 一个MCP会话），它还为服务器→客户端的消息提供SSE备用流。托管流量使用不同的
`User-Agent` 标记（`nexus-exchange-mcp-http/...`），以便在仪表板中归因于“MCP”。
### 身份验证（MVP — 无OAuth）
> **OAuth 2.1 超出此MVP范围** （在强化工作中跟踪，ENG-3598，并有范围键控，ENG-3486）。在此之前，托管
> 服务器获取调用者的现有Exchange HMAC凭证作为请求头，一次在会话初始化时捕获并在会话中重用：
>
> ```text
> X-Nexus-Api-Key: <hmac key id>
> X-Nexus-Api-Secret: <hmac secret, hex>
> ```
>
> 这些被刻意 **不** 命名为 `x-api-key` / `x-signature` （上游网关自己的头部）以避免混淆。没有凭证头部，会话仍然提供公共市场数据工具，并fallback到任何服务器环境凭证。 **开放问题供审查：** 头部直通是最简单的可防御MVP，但长期答案是OAuth生成的范围键（交易非取款） — 调用者从不向我们提供原始密钥 — 见ENG-3598 / ENG-3486。
## 开发
```bash
npm run format # prettier --write
npm run lint # eslint
npm run typecheck # tsc --noEmit
npm test # 单元测试（HMAC方案，参数映射，模式）
npm run test:coverage # 单元测试 + 覆盖率（文本/lcov/json-summary）；CI发出 %
npm run smoke # 实时端到端检查针对网关
```
## License
在 [MIT](./LICENSE-MIT) 或 [Apache-2.0](./LICENSE-APACHE) 下双重许可，由您选择 — 与其他Nexus Exchange SDK相同。
