Hycocs MCP

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

贡献

1. 分叉存储库。
2. 创建要素分支。
3. 在适当的地方添加测试或示例。
4. 打开一个带有清晰描述的拉取请求。

许可证

看 LICENSE.