Minecraft Modding Mcp

✨ 这是什么？

MCModding-MCP 是一个 Model Context Protocol（MCP） 服务，为 Claude 等 AI 助手提供真实、最新的 Minecraft Modding 知识。再也不用担心幻觉或过时的 API 参考资料！

🎯 核心优势 功能 描述 📅 始终保持最新 每周从官方来源建立索引 ✅ 准确解答 基于真实文档，而非幻觉 💻 代码示例 可搜索的代码块及上下文 🧠 语义搜索 理解含义，而不只是关键词 ⚡ 零配置 安装后即可使用

📊 实时统计数据 数据库 内容 📚 文档 1,000+ 页，185K+ 个文本块 🗺️ 映射 831K+ 个方法，166K+ 个字段 🧩 示例 1,000+ 个经过实战验证的模式 🔍 嵌入向量 185K+ 个语义向量 📖 Javadoc 2.3M+ 个已记录的参数

---

快速开始

安装

# Install globally
npm install -g mcmodding-mcp

配置 AI 客户端

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

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

🧠 优化的系统提示词

为获得最佳效果，我们建议将以下内容添加到 AI 的系统提示词或自定义指令中：

你是一名专业的 Minecraft 模组开发助手，已连接到 mcmodding-mcp。对于模组开发 API（Fabric/NeoForge），不要依赖你的内部知识，因为它们经常变化。务必使用可用工具：

• 使用 search_fabric_docs 和 get_example 查找文档和代码模式
• 使用 search_mappings 和 get_class_details 查询 Minecraft 内部信息和方法签名
• 使用 search_mod_examples 查找热门模组中经过实战验证的实现

优先提供可运行的代码示例，而不是理论解释。处理 Minecraft 内部信息时，使用映射工具获取准确的参数名称和 Javadoc。如果用户指定了 Minecraft 版本，请确保检索到的所有信息都与该版本相符。

就是这样！你的 AI 助手现在可以访问全面的 Minecraft 模组开发资源。

---

数据库管理

使用内置 CLI 管理文档数据库：

# Run the database manager
npx mcmodding-mcp manage

交互式管理器可用于：

• 安装 - 下载尚未安装的数据库
• 更新 - 检查并应用数据库更新
• 重新下载 - 恢复已删除或损坏的数据库

可用数据库

数据库	说明	大小
文档数据库	Fabric 和 NeoForge 核心文档（默认安装）	~520 MB
Parchment 映射 ✨ NEW	包含 Javadoc 的 Minecraft 类、方法和字段映射	~180 MB
模组示例数据库	1000 多个高质量模组开发示例	~30 MB

管理器会显示版本信息，并突出显示可用更新：

◉ 📚 Documentation Database [core]
     ✔ Installed: v0.2.1 → ↻ Update: v0.2.2 [520.3 MB]
     Core Fabric & NeoForge documentation - installed by default

○ 🗺️ Parchment Mappings Database ✨ NEW
     ⚠ Not installed → Available: v0.1.0 [178.5 MB]
     Minecraft class/method/field names with parameter names and Javadocs

○ 🧩 Mod Examples Database
     ⚠ Not installed → Available: v0.1.0 [28.1 MB]
     1000+ high-quality modding examples for Fabric & NeoForge

---

可用工具

MCP 服务在三类工具中提供强大功能：

📖 文档工具

search_fabric_docs

通过智能筛选搜索文档。

// Example: Find information about item registration
{
  query: "how to register custom items",
  category: "items",           // Optional filter
  loader: "fabric",            // fabric | neoforge
  minecraft_version: "1.21.10"  // Optional version filter
}

get_example

获取任意主题的可运行代码示例。

// Example: Get block registration code
{
  topic: "custom block with block entity",
  language: "java",
  loader: "fabric"
}

explain_fabric_concept

获取模组开发概念的详细说明及相关资源。

// Example: Understand mixins
{
  concept: 'mixins';
}

get_minecraft_version

获取当前 Minecraft 版本信息。

// Get latest version
{
  type: 'latest';
}

// Get all indexed versions
{
  type: 'all';
}

---

🗺️ Parchment 映射工具 ✨ NEW

需要 Parchment 映射数据库——通过 npx mcmodding-mcp manage 安装

search_mappings

搜索 Minecraft 类、方法和字段映射，以及参数名称和 Javadoc。

// Example: Find block-related classes and methods
{
  query: "BlockEntity",
  type: "class",              // class | method | field | all
  minecraft_version: "1.21.10",
  include_javadoc: true
}

get_class_details

获取 Minecraft 类的完整信息，包括所有方法和字段。

// Example: Explore the Block class
{
  class_name: "net.minecraft.world.level.block.Block",
  include_methods: true,
  include_fields: true
}

lookup_obfuscated

通过混淆标识符查找去混淆后的名称（适用于崩溃日志）。

// Example: Decode an obfuscated method name
{
  obfuscated_name: 'm_46859_';
}

get_method_signature

获取方法的完整签名，包括所有参数名称和类型。

// Example: Get method details
{
  class_name: "Block",
  method_name: "onPlace"
}

browse_package

查找 Minecraft 包中的类。

// Example: Browse block package
{
  package_name: 'net.minecraft.world.level.block';
}

---

🧩 模组示例工具

需要模组示例数据库——通过 npx mcmodding-mcp manage 安装

search_mod_examples

搜索 Create、Botania 和 Applied Energistics 2 等热门模组中经过实战验证的代码。

// Example: Find block entity implementations
{
  query: "block entity tick",
  mod: "Create",              // Optional: filter by mod
  category: "tile-entities",
  complexity: "intermediate"
}

get_mod_example

获取特定示例的详细信息，包括完整代码和说明。

// Example: Get full details for an example
{
  id: 42,
  include_related: true
}

list_canonical_mods

查看所有已索引的模组及其可用示例。

list_mod_categories

浏览可用的示例类别（方块、实体、渲染等）。

---

功能

混合搜索引擎

结合多种搜索策略，以获得最佳结果：

策略	用途
FTS5 全文搜索	快速关键词匹配并进行排序
语义嵌入	理解含义和上下文
章节搜索	查找相关文档章节
代码搜索	定位特定代码模式

自动更新

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

• 将本地版本与 GitHub 发行版进行比较
• 下载新版本并验证哈希值
• 更新前创建备份
• 非阻塞式——服务会立即启动

文档来源

当前索引的文档：

• wiki.fabricmc.net - Fabric Wiki（226+ 个页面）
• docs.fabricmc.net - Fabric 官方文档（266+ 个页面）
• docs.neoforged.net - NeoForge 文档（512+ 个页面）

---

面向开发者

开发环境设置

# Clone repository
git clone https://github.com/OGMatrix/mcmodding-mcp.git
cd mcmodding-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

构建命令

# Development
npm run dev              # Watch mode with hot reload
npm run typecheck        # TypeScript type checking
npm run lint             # ESLint
npm run test             # Run tests
npm run format           # Prettier formatting

# Production
npm run build            # Build TypeScript
npm run build:prod       # Build with fresh documentation index
npm run index-docs       # Index documentation with embeddings

# Database Management
npx mcmodding-mcp manage # Interactive database installer/updater

项目结构

mcmodding-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── db-versioning.ts      # Auto-update system
│   ├── indexer/
│   │   ├── crawler.ts        # Documentation crawler
│   │   ├── chunker.ts        # Text chunking
│   │   ├── embeddings.ts     # Semantic embeddings
│   │   ├── store.ts          # SQLite database
│   │   └── sitemap.ts        # Sitemap parsing
│   ├── services/
│   │   ├── search-service.ts # Search logic
│   │   └── concept-service.ts # Concept explanations
│   └── tools/
│       ├── searchDocs.ts     # search_fabric_docs handler
│       ├── getExample.ts     # get_example handler
│       └── explainConcept.ts # explain_fabric_concept handler
├── scripts/
│   └── index-docs.ts         # Documentation indexing script
├── data/
│   ├── mcmodding-docs.db     # SQLite database
│   └── db-manifest.json      # Version manifest
└── dist/                     # Compiled JavaScript

数据库架构

-- Documents: Full documentation pages
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             -- For change detection
);

-- Chunks: Searchable content units
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
);

-- Embeddings: Semantic search vectors
CREATE TABLE embeddings (
  chunk_id TEXT PRIMARY KEY,
  embedding BLOB NOT NULL,       -- 384-dim Float32Array
  dimension INTEGER NOT NULL,
  model TEXT NOT NULL            -- Xenova/all-MiniLM-L6-v2
);

-- FTS5 indexes for fast text search
CREATE VIRTUAL TABLE documents_fts USING fts5(...);
CREATE VIRTUAL TABLE chunks_fts USING fts5(...);

---

发布工作流

本项目使用 release-please 自动发布。

分支策略

分支	用途
dev	正在进行的开发
prod	生产版本发布

工作原理

1. 使用 约定式提交 将提交推送到 dev
2. Release-please 维护一个 Release PR（dev → prod）
3. 合并后自动发布：npm 发布 + GitHub 发布 + 数据库上传
4. 将更改同步回 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

---

💡 分享你的想法！

我们正在积极开发 mcmodding-mcp，期待听到你的想法！

有什么想法吗？

• 功能请求 - 哪些工具能让你的模组开发更轻松？
• 新的文档来源 - 知道我们应该索引的优质模组开发资源吗？
• 工作流改进 - 怎样才能让工具更好地满足你的使用需求？

👉 提交功能请求

发现了 Bug？

• 搜索结果不正确？
• 文档缺失或过时？
• 工具未按预期工作？

👉 报告 Bug

分享你的体验

使用 mcmodding-mcp 开展了有趣的项目？我们很想了解！欢迎在 讨论区 分享你的故事。

---

贡献

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

快速贡献指南

1. Fork 此仓库
2. 从 dev 创建功能分支
3. 使用约定式提交进行更改
4. 向 dev 提交 PR

---

许可证

MIT 许可证——详情请参阅 LICENSE。

更新日志

请参阅 CHANGELOG.md，了解详细的更改和发布历史。

---

致谢

• Fabric 文档 - Fabric 官方文档
• Fabric Wiki - 社区 Wiki
• NeoForge 文档 - NeoForge 官方文档
• ParchmentMC - 参数名称和 Javadoc 映射
• Model Context Protocol - MCP 规范
• Transformers.js - 本地 ML 嵌入
• better-sqlite3 - 快速 SQLite 绑定

---