Hydocs文档MCP服务器
一种模型上下文协议（MCP）服务器，提供对Hydocs API文档的编程访问。使用TypeScript和Streamable HTTP传输构建。
特性
- 具有严格类型的TypeScript
- 流式HTTP MCP传输
- 快速类搜索和完整文档检索
- 健康检查端点
- 从MinIO自动下载文档 （通过预先签名的URL）
- 可选的监控集成
文档管理
服务器支持两种加载文档的方法：
1.自动下载（建议用于生产）
设置 DOCS_URL 将环境变量转换为预签名的MinIO URL。服务器将：
- 首次启动时下载并解压缩文档ZIP
- 在中跟踪URL
.last-download-url检测变化 - 如果URL没有更改，则跳过下载（快速重启）
- URL更改时自动重新下载
2.本地目录（开发）
点 DOCS_DIR 到包含文档构建输出的本地目录。
建筑
MCP Client
|
| Streamable HTTP
v
Hydocs MCP Server (port 3000)项目结构
mcp/
├── src/
│ ├── index.ts
│ ├── types/
│ ├── utils/
│ └── tools/
├── nyxis-monitoring/
│ ├── docker-compose.monitoring.yml
│ └── monitoring/
│ ├── prometheus.yml
│ ├── loki-config.yml
│ └── grafana/
│ ├── datasources.yml
│ ├── dashboards.yml
│ └── dashboards/
│ └── hydocs-mcp-overview.json
├── Dockerfile
├── package.json
└── README.md需求
- Node.js 18+
- 以下之一：
- 带有文档ZIP的预签名MinIO URL（建议用于生产） - 本地Hydocs文档构建输出（用于开发）
配置
创建一个 .env 文件基于 .env.example 或 .env.production.example.
本地开发的最低配置：
PORT=3000
DOCS_DIR=../build
LOG_LEVEL=info可选自动下载配置：
# Download documentation from pre-signed URL
DOCS_URL=https://minio.example.com/docs/latest.zip?X-Amz-...
DOCS_DOWNLOAD_TIMEOUT=300000可选监控配置（Nyxis堆栈）：
ENABLE_LOKI_PUSH=true
LOKI_URL=http://loki:3100
ENABLE_METRICS_PUSH=true
PUSHGATEWAY_URL=http://pushgateway:9091
METRICS_PUSH_INTERVAL=10000本地开发
npm install
npm run build
npm start服务器终结点：
- MCP：
POST http://localhost:3000/mcp - 健康：
GET http://localhost:3000/health
Docker部署
塑造形象
docker build -t hydocs-mcp:local .选项1：自动下载（推荐）
从预先签名的URL自动下载文档：
docker run --rm -p 3000:3000 \
-e DOCS_URL="https://minio.example.com/docs/latest.zip?X-Amz-..." \
-e DOCS_DIR=/app/docs \
hydocs-mcp:local服务器将：
- 首次启动时下载并解压缩ZIP
- 如果URL没有更改，则跳过下载
- URL更改时重新下载
选项2：卷装载（传统）
从主机文件系统装载文档：
docker run --rm -p 3000:3000 \
-e DOCS_DIR=/app/docs \
-v /path/to/build:/app/docs:ro \
hydocs-mcp:local注： 使用自动下载时，不要以只读方式挂载docs目录(:ro).
监控支持
如果您需要度量和日志，此项目可以与Nyxis监控堆栈集成。监控堆栈在以下位置进行维护 nyxis-monitoring/ 并且可以由任何Nyxis服务使用。
要在这里使用它，请将MCP容器连接到堆栈，并设置配置部分中显示的环境变量。
MCP工具
search_hydocs_classes
按名称搜索API类。
输入：
{
"query": "Player"
}输出（示例）：
- com.hypixel.hydocs.player.Player (class)
- com.hypixel.hydocs.player.PlayerManager (class)
- com.hypixel.hydocs.player.PlayerData (class)read_hydocs_class_docs
阅读课程的完整文档。
输入：
{
"full_class_name": "com.hypixel.hydocs.player.Player"
}输出（示例）：
# Player
Full markdown documentation for the Player class...MCP客户端示例
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/http.js";
const transport = new StreamableHTTPClientTransport({
endpoint: "http://localhost:3000/mcp",
});
const client = new Client(
{ name: "my-client", version: "1.0.0" },
{ capabilities: {} }
);
await client.connect(transport);
const result = await client.callTool({
name: "search_hydocs_classes",
arguments: { query: "Entity" },
});
console.log(result);监控（可选）
如果需要度量和日志，请将MCP服务连接到Nyxis监控堆栈，并启用监控环境变量。该堆栈可在Nyxis服务之间重用。
故障排除
- 服务器找不到文档：验证
DOCS_DIR而那个class_lookup.json存在 - 自动下载失败：检查一下
DOCS_URL有效且可访问 - 下载超时：增加
DOCS_DOWNLOAD_TIMEOUT用于慢速连接 - 服务器启动时退出：如果下载失败且不存在本地文档，服务器将退出并出错
- 文档未更新：检查URL是否已更改（服务器使用URL比较进行缓存）
- 缺少指标：确保MCP容器能够到达Pushgateway
- 日志丢失：设置
LOG_LEVEL=info或debug
贡献
- 分叉存储库。
- 创建要素分支。
- 在适当的地方添加测试或示例。
- 打开一个带有清晰描述的拉取请求。
许可证
看 LICENSE.