内容
# 黑洞MCP服务器
用于Avalanche上的黑洞DEX的模型上下文协议服务器。 为交换、流动性、CL仓位、zap、投票、锁、仪表、贿赂、投资组合查询、池分析、gas估计和交易执行提供48种工具。
## 工具
| 类别 | 工具 |
|---|---|
| **兑换** | `swap_steps`, `quote` |
| **流动性（V2）** | `add_liquidity_steps`, `remove_liquidity_steps`, `withdraw_liquidity_steps` |
| **流动性（CL）** | `add_liquidity_cl_steps`, `create_cl_pool_steps` |
| **存款数学** | `get_deposit_amounts` |
| **Zap** | `zap_add_liquidity_steps`, `zap_mint_cl_steps`, `zap_increase_liquidity_steps`, `zap_remove_liquidity_steps`, `zap_split_plan` |
| **质押** | `stake_liquidity_steps`, `unstake_liquidity_steps` |
| **费用和排放** | `claim_fees_steps`, `claim_emissions_steps`, `claim_rebase_steps`, `claim_voting_rewards_steps`, `claim_voting_rewards_payload` |
| **锁（veNFT）** | `create_lock_steps`, `increase_lock_steps`, `merge_lock_steps`, `lock_advanced_steps` |
| **投票** | `vote_steps`, `get_lock_vote_state`, `vote_leaderboard` |
| **纪元** | `get_epoch_state` |
| **仪表和贿赂** | `create_gauge_steps`, `add_bribes_steps` |
| **投资组合和发现** | `resolve_address`, `get_token_balances`, `get_user_positions`, `get_user_locks`, `get_whitelisted_tokens`, `get_opportunities` |
| **池、收益和ALM** | `pool_yield`, `get_pool_status`, `get_pool_lp_providers`, `get_alm_vaults`, `get_tokenomics` |
| **CL数学和模拟** | `cl_tick_to_price`, `cl_price_to_tick`, `cl_position_detail`, `cl_apr_simulator` |
| **操作/安全** | `get_allowances`, `estimate_gas_and_tx_cost` |
| **执行** | `execute_transactions` |
## 安装
### 1. Stdio -- 用于MCP客户端（Claude Desktop, Cursor, Codex）
#### Cursor（`.cursor/mcp.json`）
```json
{
"mcpServers": {
"blackhole-mcp": {
"command": "npx",
"args": ["@blackhole-dex/blackhole-mcp-server"],
"env": {
"PRIVATE_KEY": "0x..."
}
}
}
}
```
或从源代码：
```json
{
"mcpServers": {
"blackhole-mcp": {
"command": "bash",
"args": ["-lc", "cd /path/to/mcp-server && NODE_ENV=prod npx tsx src/index.ts"],
"env": {
"PRIVATE_KEY": "0x..."
}
}
}
}
```
#### Claude Desktop
**选项A - 一条命令（推荐）：**
从npm：
```bash
claude mcp add --scope user blackhole-mcp -- npx @blackhole-dex/blackhole-mcp-server
```
从源代码：
```bash
claude mcp add --scope user blackhole-mcp -- bash -lc "cd /path/to/mcp-server && NODE_ENV=prod npx tsx src/index.ts"
```
`--scope user`写入您的全局Claude配置（`~/.claude.json`），因此服务器在每个项目中都可用。运行后重启Claude Desktop。
**选项B - 手动JSON** (`~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS上， `%APPDATA%\Claude\claude_desktop_config.json` 在Windows上)：
从npm：
```json
{
"mcpServers": {
"blackhole-mcp": {
"command": "npx",
"args": ["@blackhole-dex/blackhole-mcp-server"]
}
}
}
```
从源代码：
```json
{
"mcpServers": {
"blackhole-mcp": {
"command": "bash",
"args": ["-lc", "cd /path/to/mcp-server && NODE_ENV=prod npx tsx src/index.ts"]
}
}
}
```
编辑文件后重启Claude Desktop。
#### Codex
Codex从 `~/.codex/config.toml` （全局）或 `.codex/config.toml` （项目范围，仅限受信任的项目）读取MCP服务器配置。CLI和IDE扩展共享此文件。有关详细信息，请参阅 [Codex MCP文档](https://developers.openai.com/codex/mcp)。
**选项A - Codex应用/IDE（UI）**
1. 在Codex应用或IDE扩展中打开 **设置** （齿轮图标）。
2. 进入 **MCP设置** 并添加服务器（或选择 **打开config.toml** 并粘贴下面的TOML）。
3. 将命令设置为 `npx`，参数为 `@blackhole-dex/blackhole-mcp-server`，并在环境变量下添加 `PRIVATE_KEY`（如果您计划执行交易）。
**选项B - CLI：**
从npm：
```bash
codex mcp add blackhole-mcp --env PRIVATE_KEY=0x... -- npx @blackhole-dex/blackhole-mcp-server
```
从源代码：
```bash
codex mcp add blackhole-mcp --env PRIVATE_KEY=0x... -- bash -lc "cd /path/to/mcp-server && NODE_ENV=prod npx tsx src/index.ts"
```
在Codex TUI中，使用 `/mcp` 验证服务器是否活跃。
**选项C - 手动 `config.toml`** (`~/.codex/config.toml` 或 `.codex/config.toml` 在项目中)：
从npm：
```toml
[mcp_servers.blackhole-mcp]
command = "npx"
args = ["@blackhole-dex/blackhole-mcp-server"]
[mcp_servers.blackhole-mcp.env]
PRIVATE_KEY = "0x..."
```
从源代码：
```toml
[mcp_servers.blackhole-mcp]
command = "bash"
args = ["-lc", "cd /path/to/mcp-server && NODE_ENV=prod npx tsx src/index.ts"]
[mcp_servers.blackhole-mcp.env]
PRIVATE_KEY = "0x..."
```
### 2. 库 -- 导入到您自己的Node.js应用程序中
```bash
npm install @blackhole-dex/blackhole-mcp-server
```
```ts
import { createMcpServer } from "@blackhole-dex/blackhole-mcp-server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = createMcpServer();
const transport = new StdioServerTransport();
await server.connect(transport);
```
选项：
- 导出的API：`createMcpServer()`
- 还导出了：`toolDefinitions`，`toolHandlers`
## 环境
服务器使用生产Avalanche主网配置。
| 环境变量 | 网络 | RPC |
|---|---|---|
| `prod` | Avalanche 主网 | `https://api.avax.network/ext/bc/C/rpc` |
可选的运行时变量：
| 变量 | 目的 |
|---|---|
| `RPC_URL` | 覆盖用于读取和执行的Avalanche C-Chain RPC端点。 |
| `BASIC_GRAPH_URL` | 覆盖基本池子图谱URL。 |
| `CL_GRAPH_URL` | 覆盖集中流动性图谱URL。 |
| `GAMMA_VAULT_ADDRESSES` | 以逗号分隔的Gamma vault允许列表覆盖。 |
| `PRIVATE_KEY` | 由 `execute_transactions` 使用的私钥。服务器从此密钥派生 `userAddress`，用于需要它的任何工具。 |
| `USER_ADDRESS` | 无私钥配置时的只读备用地址。 |
当配置 `PRIVATE_KEY` 时，具有 `userAddress` 的工具可以省略它；服务器会填入派生自私钥的地址。 `execute_transactions` 需要私钥，并且仅在调用时带有 `confirm: true` 才会被广播。
