mc-rp-assistant

mc-rp-assistant-mcp

用于 Minecraft 资源包分析、验证和管理的 MCP 服务。读取 pack.mcmeta、验证结构、列出资源、比较资源包并查询 Modrinth。

工具

工具	说明
read_packmeta	从资源包目录或 .zip 文件中读取 pack.mcmeta
validate_rp_structure	验证资源包结构并标记问题（缺少文件、格式不匹配、图标过大等）
list_rp_assets	列出资源包中的所有资源路径（纹理/模型/声音/语言）。支持目录和 .zip 文件
compare_rpacks	比较两个资源包并报告新增、移除和更改的资源文件
search_rp_on_modrinth	按名称或标签在 Modrinth 中搜索资源包。最多返回 limit 条结果
get_rp_info	通过资源包的 slug 或项目 ID 获取 Modrinth 上的详细信息
validate_textures	验证纹理大小限制（>2MB）、命名规范（小写、无空格）和资源包图标大小
analyze_lang_files	分析语言文件（.lang），检测不同语言之间缺失的翻译
compare_rpacks_diff	比较两个资源包，提供逐文件详情，包括新增/移除/更改资源的文件大小

导出的函数

• readPackMetaExport(packPath) — 读取 pack.mcmeta
• validateRpStructureExport(packPath, mcVersion?) — 验证资源包结构
• listRpAssetsExport(packPath, limit?) — 列出资源文件
• compareRpacksExport(oldPackPath, newPackPath) — 比较两个资源包
• searchRpOnModrinthExport(query, limit?) — 搜索 Modrinth
• getRpInfoExport(slugOrId) — 从 Modrinth 获取资源包信息
• validateTexturesExport(packPath) — 验证纹理
• analyzeLangFilesExport(packPath) — 分析语言文件
• compareRpacksDiffExport(oldPackPath, newPackPath) — 详细比较资源包

MCP 客户端配置

添加到 MCP 客户端配置中（例如 Trae settings.json 或 MCP CLI 配置）：

{
  "mcpServers": {
    "mc-rp-assistant": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

路径说明： ${workspaceFolder} 在 Trae/VS Code 中会解析为项目根目录。如果使用其他编辑器，请替换为绝对路径，例如 ["C:/Users/xxx/Desktop/mc-rp-assistant-mcp/dist/index.js"]。

配置

本工具零配置即可用（内置默认值，任何环境开箱即用）。以下项目可通过环境变量或项目根目录 .env 文件覆盖（复制 .env.example 为 .env）：

变量	默认值	说明
RP_ASSISTANT_MODRINTH_API_BASE	https://api.modrinth.com/v2	Modrinth API 根地址，支持自建网关/代理
RP_ASSISTANT_USER_AGENT	mc-rp-assistant-mcp/1.0	请求 User-Agent（Modrinth 要求标明来源）
RP_ASSISTANT_TEXTURE_MAX_MB	2	单张纹理大小上限（MB），超过则标记为大纹理
RP_ASSISTANT_PACK_ICON_MAX_KB	50	资源包图标 pack.png 大小上限（KB）
RP_ASSISTANT_DEFAULT_SEARCH_LIMIT	10	Modrinth 资源包搜索默认返回条数
RP_ASSISTANT_MAX_SEARCH_RESULTS	50	Modrinth 搜索返回条数硬上限

优先级：环境变量 > .env 文件 > rp-config.json > 内置默认值。更改后重启 MCP 服务即可生效。

扩展默认配置：编辑 src/rp-config.json（构建后为 dist/rp-config.json）可调整搜索上限、pack.png 大小阈值与 MC 版本 → pack_format 映射，无需修改代码。

要求

• Node.js 18+
• @modelcontextprotocol/sdk、zod、adm-zip
• .zip / .mcpkg 资源包支持需要 adm-zip — 已作为依赖项包含

开发

npm run build   # Compile TypeScript
npm run test:unit  # Run unit tests
npm test        # Run all tests

测试

npm run build
npm test

除 searchRpOnModrinth 和 getRpInfo 外，所有单元测试均可离线运行；在没有网络时，这两个函数会正常返回空结果。

平台兼容性

工具	Windows	macOS	Linux
read_packmeta	✅	✅	✅
validate_rp_structure	✅	✅	✅
list_rp_assets	✅	✅	✅
compare_rpacks	✅	✅	✅
search_rp_on_modrinth	✅	✅	✅
get_rp_info	✅	✅	✅
validate_textures	✅	✅	✅
analyze_lang_files	✅	✅	✅
compare_rpacks_diff	✅	✅	✅

所有工具均使用跨平台的 Node.js fs 和 path API。.zip 支持需要 adm-zip。依赖网络的工具（search_rp_on_modrinth、get_rp_info）在联网时可在所有平台上使用；离线时会正常返回空结果。

要求

• Node.js 18+
• @modelcontextprotocol/sdk、zod、adm-zip

许可证

MIT