金大哥 - mcmodding-mcp MCP 详情

article

README

🚀 mcmodding - mcp

mcmodding - mcp 是一个为AI助手提供综合、最新的Minecraft Mod开发文档的服务器，支持Fabric和NeoForge两种加载器，让AI可以直接访问这些文档，准确解答Mod开发相关问题。

🚀 快速开始

📦 安装指南

# 全局安装
npm install -g mcmodding-mcp

配置你的AI客户端

将以下内容添加到你的MCP客户端配置中（例如Claude Desktop）：

{
  "mcpServers": {
    "mcmodding": {
      "command": "mcmodding-mcp"
    }
  }
}

完成！你的AI助手现在可以访问Minecraft Mod开发文档了。

✨ 主要特性

混合搜索引擎

结合多种搜索策略以获得最佳结果： | 策略 | 目的 | | ---- | ---- | | FTS5全文搜索 | 快速进行关键词匹配并排序 | | 语义嵌入 | 理解含义和上下文 | | 章节搜索 | 查找相关文档章节 | | 代码搜索 | 定位特定代码模式 |

自动更新

数据库在启动时会自动检查更新：

将本地版本与GitHub版本进行比较
通过哈希验证下载新版本
更新前创建备份
非阻塞式 - 服务器立即启动

文档来源

目前索引以下文档：

wiki.fabricmc.net - Fabric Wiki（226 + 页面）
docs.fabricmc.net - 官方Fabric文档（266 + 页面）

💻 使用示例

可用工具

MCP服务器提供了四个强大的工具：

基础用法

// 示例：查找有关物品注册的信息
{
  query: "how to register custom items",
  category: "items",           // 可选过滤器
  loader: "fabric",            // fabric | neoforge
  minecraft_version: "1.21.4"  // 可选版本过滤器
}

高级用法

// 示例：获取自定义方块与方块实体的代码示例
{
  topic: "custom block with block entity",
  language: "java",
  loader: "fabric"
}

`explain_fabric_concept`

获取Mod开发概念的详细解释及相关资源。

// 示例：了解Mixins
{
  concept: "mixins"
}

`get_minecraft_version`

获取当前Minecraft版本信息。

// 获取最新版本
{ type: "latest" }

// 获取所有索引版本
{ type: "all" }

🔧 技术细节

开发设置

# 克隆仓库
git clone https://github.com/OGMatrix/mcmodding-mcp.git
cd mcmodding-mcp

# 安装依赖
npm install

# 以开发模式运行
npm run dev

构建命令

# 开发
npm run dev              # 监听模式，热更新
npm run typecheck        # TypeScript类型检查
npm run lint             # ESLint
npm run test             # 运行测试
npm run format           # Prettier格式化

# 生产
npm run build            # 构建TypeScript
npm run build:prod       # 用全新的文档索引构建
npm run index-docs       # 用嵌入向量索引文档

项目结构

mcmodding-mcp/
├── src/
│   ├── index.ts              # MCP服务器入口点
│   ├── db - versioning.ts      # 自动更新系统
│   ├── indexer/
│   │   ├── crawler.ts        # 文档爬取器
│   │   ├── chunker.ts        # 文本分块
│   │   ├── embeddings.ts     # 语义嵌入
│   │   ├── store.ts          # SQLite数据库
│   │   └── sitemap.ts        # 站点地图解析
│   ├── services/
│   │   ├── search - service.ts # 搜索逻辑
│   │   └── concept - service.ts # 概念解释
│   └── tools/
│       ├── searchDocs.ts     # search_fabric_docs处理程序
│       ├── getExample.ts     # get_example处理程序
│       └── explainConcept.ts # explain_fabric_concept处理程序
├── scripts/
│   └── index - docs.ts         # 文档索引脚本
├── data/
│   ├── mcmodding - docs.db     # SQLite数据库
│   └── manifest.json         # 版本清单
└── dist/                     # 编译后的JavaScript

数据库架构

-- 文档：完整的文档页面
CREATE TABLE documents (
  id INTEGER PRIMARY KEY,
  url TEXT UNIQUE NOT NULL,
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  category TEXT NOT NULL,
  loader TEXT NOT NULL,          -- fabric | neoforge | shared
  minecraft_version TEXT,
  hash TEXT NOT NULL             -- 用于变更检测
);

-- 块：可搜索的内容单元
CREATE TABLE chunks (
  id TEXT PRIMARY KEY,
  document_id INTEGER NOT NULL,
  chunk_type TEXT NOT NULL,      -- title | section | code | full
  content TEXT NOT NULL,
  section_heading TEXT,
  code_language TEXT,
  word_count INTEGER,
  has_code BOOLEAN
);

-- 嵌入向量：语义搜索向量
CREATE TABLE embeddings (
  chunk_id TEXT PRIMARY KEY,
  embedding BLOB NOT NULL,       -- 384维Float32数组
  dimension INTEGER NOT NULL,
  model TEXT NOT NULL            -- Xenova/all - MiniLM - L6 - v2
);

-- FTS5索引，用于快速文本搜索
CREATE VIRTUAL TABLE documents_fts USING fts5(...);
CREATE VIRTUAL TABLE chunks_fts USING fts5(...);

📚 详细文档

发布工作流

本项目使用 [release - please](https://github.com/googleapis/release - please) 进行自动发布。

分支策略

| 分支 | 用途 | | ---- | ---- | | dev | 活跃开发 | | prod | 生产发布 |

工作原理

使用常规提交将提交推送到 dev 分支。
release - please 维护一个发布PR（dev → prod）。
合并后，自动发布：npm发布 + GitHub发布 + 数据库上传。
更改同步回 dev 分支。

详细信息请参阅 RELEASE_WORKFLOW.md。

配置

环境变量

| 变量 | 描述 | 默认值 | | ---- | ---- | ---- | | DB_PATH | 自定义数据库路径 | ./data/mcmodding - docs.db | | GITHUB_REPO_URL | 用于更新的自定义仓库 | 自动检测 | | MCP_DEBUG | 启用调试日志 | false |

禁用自动更新

将 DB_PATH 设置为自定义位置以手动管理更新：

DB_PATH=/path/to/my/database.db mcmodding-mcp

统计信息

典型的索引包含： | 指标 | 数量 | | ---- | ---- | | 文档页面 | 490 + | | 可搜索章节 | 2000 + | | 代码示例 | 500 + | | 语义嵌入向量 | 5000 + | | 数据库大小 | ~50 MB |

🤝 贡献

我们欢迎贡献！请参阅 CONTRIBUTING.md 了解贡献指南。

快速贡献指南

分叉仓库
从 dev 分支创建功能分支
使用常规提交进行更改
向 dev 分支提交PR

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE。

👏 致谢

Fabric文档 - 官方Fabric文档
Fabric Wiki - 社区Wiki
Model Context Protocol - MCP规范
Transformers.js - 本地机器学习嵌入向量
[better - sqlite3](https://github.com/WiseLibs/better - sqlite3) - 快速SQLite绑定

为Minecraft Mod开发社区精心打造

mcmodding-mcp