内容
# hytale-mcp
Hytale 模组开发的 MCP 服务器。 为 AI 编程助手提供文档搜索、Java API 参考、事件/实体/方块查找、插件和模组脚手架、以及 manifest 验证，基于模型上下文协议。
与 Claude Code、Claude Desktop、Antigravity、Cursor、Windsurf、Codex 以及任何支持 MCP 的客户端兼容。
[](https://github.com/eliasnvx/hytale-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@eliasnvx/hytale-mcp)
[](LICENSE)
[](package.json)
## 为什么
Hytale 在 2026 年 1 月进入早期访问阶段，模组功能内置于平台。从第一天起，文档就分散在官方网站、社区 GitBook 和多个 GitHub 组织中。该服务器将所有这些文档合并成一套工具，AI 助手可以回答 Hytale 模组问题并生成样板代码，而无需开发者切换选项卡。
## 安装
无需安装步骤。 将服务器添加到您的 MCP 客户端配置中，它通过 `npx` 按需运行。
### Claude Desktop
编辑您所在操作系统的配置文件：
| 操作系统 | 路径 |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
```json
{
"mcpServers": {
"hytale-mcp": {
"command": "npx",
"args": ["-y", "@eliasnvx/hytale-mcp"]
}
}
}
```
保存后完全重启 Claude Desktop（退出，而不仅仅是关闭窗口）。
### Claude Code
```bash
claude mcp add hytale-mcp -- npx -y @eliasnvx/hytale-mcp
```
### Antigravity、Cursor、Windsurf
将上述相同的 `mcpServers` 块添加到客户端的 MCP 配置文件中或通过其内置的连接器 UI。
### Codex CLI
```bash
codex mcp add hytale-mcp -- npx -y @eliasnvx/hytale-mcp
```
## 工具
| 工具 | 输入 | 描述 |
|---|---|---|
| `search_docs` | `query: string, limit?: number` | 对所有缓存的 Hytale 模组文档进行全文搜索 |
| `get_api_reference` | `className: string` | 来自服务器 API 的 Java 类和方法引用 |
| `list_events` | `type?: "sync"\|"async"\|"ecs", query?: string` | 浏览所有事件，可选按类型筛选 |
| `get_entities` | `category?: "hostile"\|"passive"\|"neutral"\|"boss", query?: string` | NPC 和实体注册表，可选按类别筛选 |
| `search_blocks` | `query: string, category?: string` | 方块和物品注册表搜索 |
| `scaffold_plugin` | `name: string, packageName: string, features: ("events"\|"commands"\|"config"\|"scheduler"\|"entities")[]` | 生成插件骨架（清单、主类、Gradle 构建） |
| `scaffold_pack` | `name: string, type: "block"\|"item"\|"entity"\|"world", description?: string` | 生成模组骨架 |
| `get_examples` | `topic: string` | 按主题获取代码示例，来源于社区仓库 |
| `validate_manifest` | `json: string, type?: "plugin"\|"pack"` | 验证 `plugin.json` 或模组清单是否符合必填字段 |
| `get_sounds` | `query?: string, category?: string` | 声音键注册表，可选按类别筛选 |
| `get_changelog` | `since?: string` | 最近的 Hytale 服务器 API 变更 |
| `analyze_error` | `log: string` | 分析栈跟踪信息以检查已知引擎错误 |
| `get_lore` | `query?: string, type?: string, faction?: string` | 搜索 Hytale 传闻（怪物、物品、统计数据） |
## 示例
连接后，向您的 AI 助手提问：
> 当玩家破坏方块时，会触发哪些事件？请为我展示一个记录该事件的插件。
助手调用 `search_docs` 和 `list_events` 以查找 `BlockBreakEvent`，然后调用 `scaffold_plugin` 以生成一个具有已连接事件监听器的插件骨架。
## 架构与文档
所有数据都在构建时预先获取并缓存到 `data/*.json`。工具处理程序从提交的缓存中读取数据，而不进行网络调用，因此响应速度快，服务器在运行时无需依赖上游网站。
```
[上游源] --构建时--> scripts/build-cache.ts --> data/*.json
|
src/tools/*.ts --> MCP 响应
```
有关详细的代码库分解、开发者设置、添加工具的分步教程以及 CI/CD 管道，请查看 **[开发者与架构指南](docs/architecture.md)**。
## 开发
```bash
git clone https://github.com/eliasnvx/hytale-mcp.git
cd hytale-mcp
npm install
npm run dev # 启动并启用热重载
npm run test # 运行测试套件
npm run typecheck # 类型检查（不生成输出）
npm run lint # 校验 src/
npm run inspect # 打开 MCP 检验器以检查已构建的服务器
npm run cache:build # 从上游源重新构建 data/
```
需要 Node.js 22 或更高版本。
### 添加工具
1. 使用 zod 输入模式和异步处理程序创建 `src/tools/<name>.ts`
2. 在 `src/tools/__tests__/<name>.test.ts` 中添加测试
3. 在 `src/index.ts` 中注册工具
4. 更新此 README 和 `AGENTS.md` 中的工具表格
参见 [CLAUDE.md](CLAUDE.md) 和 [AGENTS.md](AGENTS.md)，了解为本仓库做出贡献的 AI 助手遵循的完整规则集。
## 数据源
- [hytalemodding.dev](https://hytalemodding.dev) — 事件、实体、交互、声音
- [Britakee Studios GitBook](https://britakee-studios.gitbook.io/hytale-modding-documentation) — 插件和模组教程
- [github.com/HytaleModding](https://github.com/HytaleModding) — 插件模板、反编译源代码浏览器
- [hytale-docs.com](https://hytale-docs.com) — 社区 API 参考
本项目与 Hypixel Studios 无关。数据来源于社区文档，可能落后于最新的抢先体验版本。
## 贡献
欢迎提出问题和拉取请求。请在打开拉取请求前运行 `npm run typecheck && npm run test` — CI 在每次推送时强制执行这两项检查。
## 许可证
[MIT](LICENSE)
## 作者
[@eliasnvx](https://github.com/eliasnvx) — [vyxro.dev](https://vyxro.dev)
