内容
# 超液体MCP服务器
为超液体（Hyperliquid）准备就绪的**模型上下文协议（MCP）服务器**，基于官方的超液体Python SDK构建。
> 没有UI。没有多余的粘合代码。只需一个可靠的MCP后端，您可以在本地或在Docker中运行。
---
## 为什么有这个项目
超液体自动化通常在操作层面上失败（设置摩擦，环境漂移，脆弱的启动流程）。这个仓库专注于**可预测的部署和安全的默认值**，以便您可以有信心地运行代理。
---
## 功能概述
- 与超液体（仅官方Python SDK）的**SDK原生集成**
- **严格的输入验证**，用于工具安全性和确定性行为
- **标准化的响应模式** (`ok`, `message`, `data`, 结构化`error`)
- **Docker优先运行时**，具有干净的启动/停止/重置工作流
- 通过`start.bat`实现**一键式Windows启动**
- **端口回退策略**，适用于未来暴露的服务（API/UI/指标）
- **默认为测试网**，以降低操作风险
---
## 技术栈
- **Python 3.12+**
- **MCP服务器运行时** (`mcp`)
- **超液体官方SDK** (`hyperliquid-python-sdk`)
- **Docker + Docker Compose**
---
## 快速入门（Windows - 一键式）
1. 安装并启动 **Docker Desktop**。
2. 在此仓库根目录中，双击：
```bat
start.bat
```
`start.bat`的作用：
- 验证Docker可用性和守护进程状态
- 从`.env.example`创建`.env`（如果丢失）
- 检查保留的端口（`APP_PORT`，`METRICS_PORT`）
- 自动切换占用端口到空闲备用端口
- 运行 `docker compose up --build -d`
- 验证服务正在运行并打印状态
### 停止服务
```bat
stop.bat
```
### 完全重置（干净状态）
```bat
reset.bat
```
---
## 安装（手动/跨平台）
```bash
cp .env.example .env
# 使用您的凭证编辑.env
docker compose up --build -d
```
停止：
```bash
docker compose stop
```
重置：
```bash
docker compose down -v --remove-orphans
```
---
## 用例
此服务器适用于MCP兼容的客户端（例如本地代理运行时）。
### 示例：本地Python执行
```bash
python -m hyperliquid_mcp.server
```
### 示例MCP配置片段
```json
{
"mcpServers": {
"hyperliquid": {
"command": "python",
"args": ["-m", "hyperliquid_mcp.server"],
"env": {
"HYPERLIQUID_PRIVATE_KEY": "0x...",
"HYPERLIQUID_ACCOUNT_ADDRESS": "0x...",
"HYPERLIQUID_TESTNET": "true"
}
}
}
}
```
---
## 配置（`.env`）
### 必需
- `HYPERLIQUID_PRIVATE_KEY`
### 可选
- `HYPERLIQUID_ACCOUNT_ADDRESS`
- `HYPERLIQUID_VAULT_ADDRESS`
- `HYPERLIQUID_TESTNET`（默认为`true`）
- `LOG_LEVEL`
### 保留端口变量（未来服务）
- `APP_PORT`（默认为`18080`）
- `METRICS_PORT`（默认为`19090`）
当前MCP服务器通过stdio进行通信，因此目前不需要主机端口映射。这些变量包含在内，以支持未来不重新设计本地工作流的HTTP/指标服务。
---
## Docker使用和端口回退策略
### 当前状态
- 主要服务在Docker中通过stdio运行。
- 没有做出UI假设。
### 未来准备的端口策略
- 在`.env`中定义所有主机端口（`APP_PORT`，`METRICS_PORT`等）。
- 在`docker-compose.yml`中始终引用环境变量（`${APP_PORT}`）进行映射。
- `start.bat`检查保留的端口是否已被占用。
- 如果被占用，它将递增到下一个空闲端口（最多10次尝试）。
- 如果找不到空闲端口，它将退出并显示一个可操作的错误。
### 使用未来的API/UI服务扩展
使用类似的组合映射：
```yaml
ports:
- "127.0.0.1:${APP_PORT:-18080}:8080"
- "127.0.0.1:${METRICS_PORT:-19090}:9090"
```
这使得在不同的本地环境中启动保持稳定，并防止端口冲突。
---
## 故障排除
### Docker未运行
- 启动Docker Desktop并等待它报告健康状态。
- 重新运行`start.bat`。
### 组合构建后启动失败
- 检查服务状态：
```bash
docker compose ps
```
- 检查日志：
```bash
docker compose logs --tail=100
```
### 凭证/配置错误
- 确保`.env`存在并包含有效的`HYPERLIQUID_PRIVATE_KEY`。
- 保持`HYPERLIQUID_TESTNET=true`，除非您明确需要主网。
### 需要干净的环境
- 运行：
```bat
reset.bat
```
- 这将删除容器、卷和孤立的容器。
---
## 安全性和操作说明
- 永远不要提交`.env`或私钥。
- 使用专用的自动化钱包。
- 在开发过程中优先使用测试网。
- 仅在验证工具行为后切换到主网。
---
## 路线图（可选）
- [ ] 非stdio客户端的可选HTTP桥接配置文件
- [ ] 运行状况检查/指标端点配置文件
- [ ] Docker组合烟雾测试的CI作业
- [ ] 公共分发版本化的发布工作流
---
## 许可证
MIT（参见`LICENSE`）。
