内容
# Everstake MCP 服务器
MCP 服务器，暴露 Everstake 的质押数据和公司信息给 AI 代理。使用 Go 语言构建，基于 [modelcontextprotocol/go-sdk](https://github.com/modelcontextprotocol/go-sdk)。
**传输方式:** 可流式传输的 HTTP（MCP 2025-03-26 规范，单个 `/` 端点）或标准输入输出。 通过 `MCP_TRANSPORT` 选择。
---
## 可用工具
| 工具 | 类型 | 描述 |
|---|---|---|
| `get_company_profile` | 静态 | 公司概况、指标、认证 |
| `get_products` | 静态 | 产品详情：机构质押、VaaS、收益、SWQOS、ShredStream |
| `get_solutions` | 静态 | 面向不同受众的解决方案：托管方、交易所、资产管理者、银行、金融科技 |
| `get_developer_docs` | 静态 | SDK 链接、集成指南、API 参考 |
| `get_contact_information` | 静态 | 联系渠道和路由指南 |
| `get_security_profile` | 静态 | 认证：SOC 2 Type II、ISO 27001、NIST CSF、ITGC、GDPR、CCPA |
| `get_integrations` | 静态 | 托管集成：Fireblocks、BitGo、Anchorage、Coinbase 等 |
| `get_uptime_metrics` | 实时 | 来自仪表盘 API 的在线指标（30 分钟缓存） |
| `get_chains` | 实时 | 支持的链，包括 APY、费用、状态（30 分钟缓存） |
| `staking_calculator` | 实时 | 按网络和金额估算的质押奖励 |
| `request_integration` | 写入 | 向 Everstake 销售团队提交集成/质押查询 |
---
## 运行服务器
### 先决条件
- Go 1.26.1+
- 环境变量 `DASHBOARD_URL` 已设置（必填）
### 本地运行
```bash
export DASHBOARD_URL=https://dashboard-api.everstake.one
go run ./cmd/mcp_server
```
服务器默认在 `8080` 端口启动。可以通过 `PORT=<port>` 重写端口。
### 标准输入输出模式
```bash
export DASHBOARD_URL=https://dashboard-api.everstake.one
export MCP_TRANSPORT=stdio
go run ./cmd/mcp_server
```
在标准输入输出模式下，HTTP 服务器、`/` 健康检查端点和速率限制均被禁用。日志输出到标准错误流；标准输出流承载 MCP JSON-RPC 协议。
### Docker
HTTP 模式：
```bash
docker build -t everstake-mcp .
docker run -e DASHBOARD_URL=https://dashboard-api.everstake.one -p 8080:8080 everstake-mcp
```
标准输入输出模式（交互式，无端口映射）：
```bash
docker run --rm -i \
-e DASHBOARD_URL=https://dashboard-api.everstake.one \
-e MCP_TRANSPORT=stdio \
everstake-mcp
```
使用 `-i` 保持标准输入连接以进行 JSON-RPC 协议；**不要** 传递 `-t`（TTY 会破坏基于行的 JSON 帧）。对于启动服务器作为子进程的 MCP 客户端，将 `command` 指向 `docker`，并使用与上述匹配的 `args`，或包装在一个辅助脚本中（参见 [.vscode/stdio_docker.sh](.vscode/stdio_docker.sh) 中使用 `--env-file` 的示例）。
### 环境变量
| 变量 | 默认值 | 必填 |
|---|---|---|
| `DASHBOARD_URL` | - | 是 |
| `MCP_TRANSPORT` | `http` | 否（`http` 或 `stdio`） |
| `PORT` | `8080` | 否（仅限 HTTP 模式） |
| `GIN_MODE` | - | 否（Dockerfile 中设置为 `release`） |
### 健康检查
```
GET /health
```
---
## 使用 MCP Inspector 进行调试
[MCP Inspector](https://github.com/modelcontextprotocol/inspector) 是用于探测 MCP 服务器的官方工具 - 列出工具、调用它们、查看原始 JSON-RPC。
> **标准输入输出注意事项：** 标准输入输出服务器由父进程拥有；您无法连接到已经运行的标准输入输出容器。Inspector 必须**启动**子进程本身。对于交互式会话，您可以重新连接，请使用 HTTP 模式（以下为选项）。
### HTTP 模式（推荐用于常规调试）
启动容器：
```bash
docker run --rm -p 8080:8080 \
-e DASHBOARD_URL=https://dashboard-api.everstake.one \
-e DASHBOARD_API_KEY=<key> \
everstake-mcp
```
打开 Inspector：
```bash
npx @modelcontextprotocol/inspector
```
在 UI 中：
- **传输类型：** `Streamable HTTP`
- **网址：** `http://localhost:8080/`
容器在 Inspector 会话之间保持运行。
### 标准输入输出模式（验证标准输入输出传输）
让 Inspector 启动容器，以便它拥有标准输入/标准输出：
```bash
npx @modelcontextprotocol/inspector \
docker run --rm -i \
--env-file .env \
everstake-mcp
```
或手动填写 UI：
- **传输类型：** `STDIO`
- **命令：** `docker`
- **参数：** `run --rm -i --env-file .env everstake-mcp`
每个 Inspector 会话都会新建一个容器；退出 Inspector 会杀死容器。
---
## linting
该项目使用 [golangci-lint](https://golangci-lint.run/)，并在 [.golangci.yml](.golangci.yml) 中使用严格的配置。
**安装 golangci-lint：**
```bash
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```
**运行：**
```bash
make lint
```
强制执行的主要规则：`staticcheck`（所有检查）、`gosec`、`gocritic`（诊断/样式/性能标签）、`revive`（40 多个规则，包括提前返回、错误字符串、变量命名）、`errchkjson`、`bodyclose`、`contextcheck`等。`nolintlint` 需要特定的 lint 指令 - 不允许使用裸 `//nolint`。
---
## 编辑工具响应
### 静态工具
编辑 [tools.yaml](tools.yaml)。每个映射键是工具名称；`static_response` 字段原样返回给 AI 代理。
```yaml
tools:
get_company_profile:
description: |
...
static_response: |
COMPANY: Everstake
...
```
添加新静态工具：
1. 在 `tools.yaml` 中添加一个 `tools:` 下的条目，包含 `static_response`。
2. 在 [`internal/config/mcp_config.go`](internal/config/mcp_config.go) 中添加一个对应的字段到 `ToolsConfig`，并带有匹配的 `yaml` 结构体标签 - 名称通过反射自动注入。
3. 在 [`internal/server/mcp/server.go`](internal/server/mcp/server.go) 中使用 `staticTextTool()` 注册它。
### 内容规则
适用于所有工具响应的跨切割规则在 [.vscode/tools_src/RULES.md](.vscode/tools_src/RULES.md) 中。这些规则涵盖：
- 认证差异化语言
- 非托管定位
- 保险库产品免责声明
- APY 免责声明措辞
- `request_integration` 的线索来源标签
### 动态工具
`get_uptime_metrics` 和 `get_chains` 从仪表盘 API 提取实时数据，带有 30 分钟内存缓存。它们的处理程序在 [`internal/server/mcp/dashboard.go`](internal/server/mcp/dashboard.go) 中。底层 API 客户端位于 [`pkg/everstake/dashboard/`](pkg/everstake/dashboard/) 中。
