内容
# Hipo MCP 服务器
[MCP](https://modelcontextprotocol.io)（模型上下文协议）服务器，用于 [Hipo](https://hipo.finance)，TON 区块链上的开源流动质押协议。它允许任何支持 MCP 的 AI 客户端（Claude、Claude Code、Cursor 等）读取 Hipo 的文档并查询实时的链上数据 — hGRAM/GRAM 汇率、国库状态、验证轮次时间、钱包质押状态等。
该服务器严格**只读**：它不持有任何密钥，不发送任何消息，只调用合约读取器和公共 HTTP 端点。
## 连接
### 已托管（推荐）
将远程服务器添加到您的 MCP 客户端：
> https://mcp.hipo.finance/mcp
例如，在 Claude Code 中：
```sh
claude mcp add --transport http hipo https://mcp.hipo.finance/mcp
```
### 本地（stdio）
需要 Node.js 20+：
```sh
claude mcp add hipo -- npx -y @hipo-finance/mcp
```
或在 `mcpServers` 配置中：
```json
{
"mcpServers": {
"hipo": {
"command": "npx",
"args": ["-y", "@hipo-finance/mcp"]
}
}
}
```
## 工具
| 工具 | 描述 |
| --- | --- |
| `get_exchange_rate` | 当前 hGRAM↔GRAM 汇率，以及最近的年化收益率 |
| `get_treasury_state` | 总锁仓价值、hGRAM 供应量、待处理存款/取消质押、轮次参与情况、治理参数 |
| `get_round_timing` | 当前/下一个验证轮次边界、选举窗口、质押冻结时长 |
| `get_fees` | 当前存款、取消质押和贷款请求的 gas 费用 |
| `get_wallet_status` | 用户的 hGRAM 余额、其 GRAM 价值和待处理质押/取消质押 |
| `get_reward_history` | 用户的历史质押奖励（需要配置奖励 API） |
| `get_participation` | Hipo 在验证轮次中的参与情况（状态、贷款、总额） |
| `get_loan_info` | 借款人的每轮贷款合约 |
| `get_max_punishment` | 给定验证者质押的最大惩罚 |
## 资源
| URI | 内容 |
| --- | --- |
| `hipo://docs/overview` | 合约仓库 README（协议摘要、地址） |
| `hipo://docs/architecture` | 合约、轮次状态机、协议不变量 |
| `hipo://docs/integration` | 消息模式和集成指南 |
| `hipo://docs/schema` | 完整的 TL-B 模式 |
| `hipo://docs/knowledge` | 精选的知识库（llms.txt） |
文档从其规范的公共位置获取并缓存短暂时间，因此始终保持最新。
## 配置
所有配置均为可选；默认配置针对通过公共 toncenter 的主网。
| 环境变量 | 默认值 | 用途 |
| --- | --- | --- |
| `TONCENTER_ENDPOINT` | `https://toncenter.com/api/v2/jsonRPC` | TON HTTP API 端点 |
| `TONCENTER_API_KEY` | （无） | toncenter API 密钥；如果没有密钥，则应用公共速率限制（调用将重试并退后） |
| `TONCENTER_API_KEY_FILE` | （无） | 持有 API 密钥的文件路径（例如 docker secret）；优先级高于 `TONCENTER_API_KEY` |
| `HIPO_STATE_CACHE_SECONDS` | `5` | 工具调用之间缓存的国库状态/时间/费用 TTL |
| `HIPO_NETWORK` | `mainnet` | `mainnet` 或 `testnet` |
| `HIPO_REWARDS_API_BASE` | `https://api.hipogang.io` | Hipo 奖励 API 的基准 URL（`/wallet-rewards`）；设置为空以禁用 `get_reward_history` |
| `HIPO_DOCS_CACHE_SECONDS` | `300` | 文档资源缓存 TTL |
| `PORT` / `HOST` | `3000` / `0.0.0.0` | 仅 HTTP 传输 |
## 开发
```sh
npm install
npm run build
npm test # 单元测试（模拟链访问）
node dist/stdio.js # stdio 传输
node dist/http.js # 流式 HTTP 传输到 :3000/mcp
```
### Docker
```sh
docker build -t hipo-mcp .
docker run -p 3000:3000 -e TONCENTER_API_KEY=... hipo-mcp
```
```sh
docker build -t ghcr.io/hipogang/mcp:latest . && docker push ghcr.io/hipogang/mcp:latest
```
## 真相来源
合约地址和协议文档来自 [合约仓库](https://github.com/HipoFinance/contract)；其 README 是已部署地址的真相来源。实时数据从合约读取器读取 — 该服务器从不重新实现协议数学。
## 许可证
MIT
