内容
# @usenami/mcp-server
提供给AI代理（Claude Desktop，Cursor，支持MCP的客户端）直接访问**Usenami** —— 一个为arb-aware代理构建的多场馆永续期货资金费率和现实世界资产价差API。
- Bazaar列表：<https://agentic.market/services/api-usenami-io>
- API基础：<https://api.usenami.io>
- 通过**x402** USDC在Base主网（Coinbase CDP促进者）支付
## 工具
### 免费（无需钱包）
| 工具 | 描述 |
|---|---|
| `usenami_venues_list` | Usenami跟踪的永续期货场馆目录（CEX + DEX，包括Hyperliquid HIP-3子场馆）。 |
| `usenami_venues_health` | 每个场馆的最后更新时间戳和新鲜度状态。使用它在付费调用前验证货币。 |
### 付费（0.001 USDC每个，需要`X402_PRIVATE_KEY`）
| 工具 | 描述 |
|---|---|
| `usenami_funding_current` | 30多个交易所的每个场馆资金费率。可选`symbol`过滤器（`BTC-PERP`，`ETH-PERP`，...）。 |
| `usenami_perp_funding_spread` | 基准票据的跨场馆资金费率差快照。返回长边/短边场馆和基差（以bps为单位）。 |
| `usenami_perp_oracle_families` | 预言机价格源家族分类。识别共享价格源的场馆（相同家族对之间没有真正的套利优势）。 |
| `usenami_rwa_perp_coverage` | Hyperliquid HIP-3 DEX上的RWA永续覆盖。6个子场馆 × 约139个票据，涵盖股票/金属/外汇/商品/指数/预IPO合成资产。可选`asset_class`过滤器。 |
## 设置 — Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows）：
```json
{
"mcpServers": {
"usenami": {
"command": "npx",
"args": ["-y", "@usenami/mcp-server"],
"env": {
"X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY"
}
}
}
}
```
重启Claude Desktop。6个工具出现在工具抽屉中。
`X402_PRIVATE_KEY` 是**可选的** —— 2个免费工具无需它。付费工具如果环境缺失，会返回明确的错误。
## 设置 — Cursor
在Cursor设置 → MCP中，添加上述相同的JSON块。Cursor通过stdio调用服务器。
## 钱包准备
`X402_PRIVATE_KEY` 必须是持有**Base主网USDC**的EVM私钥：
- USDC合约：`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- 网络：Base主网（链ID 8453）
- 建议最低：0.05 USDC（~50次付费调用的余量）
- **无需ETH** —— Coinbase CDP促进者通过EIP-3009元交易覆盖gas。
定价为每付费调用0.001 USDC。结算在链上进行，不可撤销，无需订阅。
## 本地开发
```bash
npm install
npm run build
node dist/index.js # 通过stdio进行JSON-RPC通信 — 使用MCP Inspector驱动它
```
对于开发（无构建步骤）：
```bash
npm run dev
```
手动测试付费工具：
```bash
X402_PRIVATE_KEY=0x... npm run dev
# 然后在另一个终端使用 @modelcontextprotocol/inspector
```
## 返回内容 — 响应形状
所有付费响应均为JSON。示例：
`usenami_funding_current` → `{ symbol: "BTC-PERP" | null, rates: [{ source_id, venue, symbol, rate, updated_at }, ...] }`
`usenami_perp_funding_spread` → `{ ticker, venues_count, spread: { ticker, long_venue, long_rate, short_venue, short_rate, spread_bps, updated_at } | null }`
`usenami_perp_oracle_families` → `{ families: [{ family, method, venues }, ...], total_venues }`
`usenami_rwa_perp_coverage` → `{ items: [{ ticker, venue, asset_class, funding_rate, updated_at }, ...], tickers_count, venues_count }`
## 架构
- **传输**：stdio（Claude Desktop，Cursor，MCP Inspector）。计划中的v0.2版本支持流式HTTP远程调用。
- **支付**：`x402-fetch`封装`fetch` —— 拦截402响应，使用本地钱包签名EIP-3009授权，带有`X-Payment`头部重试。钱包私钥从不离开本地进程。
- **托管**：零 —— 没有MCP侧的钱包。客户自带私钥。
## 与CoinGecko / CMC的区别
Usenami是**永续期货优先** —— 资金费率和场馆价差是主要产品，而不是附加思考。两个独特的产品：
1. **预言机家族披露** —— 明确的基差风险意识。跨家族场馆的策略（`cex_aggregated`，`pyth_stork`等）没有真正的优势；Usenami直接公开这一点。
2. **HIP-3上的RWA** —— 139个RWA票据（股票，金属，外汇，商品，预IPO）位于Hyperliquid HIP-3子场馆。CoinGecko/CMC没有可比的表面。
## 许可证
MIT
