Mcmodding MCP

🚀 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開發文檔了。

✨ 主要特性

混合搜索引擎

結合多種搜索策略以獲得最佳結果：

自動更新

數據庫在啟動時會自動檢查更新：

• 將本地版本與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) 進行自動發佈。

分支策略

工作原理

1. 使用 常規提交 將提交推送到 dev 分支。
2. release - please 維護一個發佈PR（dev → prod）。
3. 合併後，自動發佈：npm發佈 + GitHub發佈 + 數據庫上傳。
4. 更改同步回 dev 分支。

詳細信息請參閱 RELEASE_WORKFLOW.md。

配置

環境變量

禁用自動更新

將 DB_PATH 設置為自定義位置以手動管理更新：

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

統計信息

典型的索引包含：

🤝 貢獻

我們歡迎貢獻！請參閱 CONTRIBUTING.md 瞭解貢獻指南。

快速貢獻指南

1. 分叉倉庫
2. 從 dev 分支創建功能分支
3. 使用常規提交進行更改
4. 向 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開發社區精心打造