MCP Klipper Docs

🚀 MCP Klipper文檔服務器

一款由人工智能驅動的Klipper文檔工具，讓您輕鬆訪問Klipper 3D打印機固件文檔。

🚀 快速開始

前提條件

• Node.js >= 20.0.0
• npm 或 yarn
• Claude Desktop（用於MCP集成）

安裝

# 全局安裝
npm install -g mcp-klipper-docs

# 或者在項目中本地安裝
npm install mcp-klipper-docs

Claude Desktop設置

1. 打開Claude Desktop配置文件：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json

2. 添加MCP服務器：

選項1：全局安裝（推薦）

{
  "mcpServers": {
    "klipper-docs": {
      "command": "node",
      "args": ["C:\\Users\\bpuhnk\\AppData\\Roaming\\npm\\node_modules\\mcp-klipper-docs\\dist\\server.js"]
    }
  }
}

選項2：使用npx

{
  "mcpServers": {
    "klipper-docs": {
      "command": "npx",
      "args": ["-y", "mcp-klipper-docs@1.0.1"]
    }
  }
}

選項3：本地開發

{
  "mcpServers": {
    "klipper-docs": {
      "command": "node",
      "args": ["C:\\Users\\bpuhnk\\source\\repos\\MCP_Klipper\\dist\\server.js"]
    }
  }
}

3. 重啟Claude Desktop

大功告成！🎉 現在Claude可以立即訪問所有Klipper文檔。

📦 包信息

• npm包：mcp-klipper-docs
• 版本：1.0.1
• 倉庫：GitHub
• 許可證：MIT
• 作者：Ben Phillips

🔍 驗證

安裝完成後，驗證一切是否正常工作：

# 檢查包安裝情況
npm list -g mcp-klipper-docs

# 測試服務器啟動
node C:\Users\bpuhnk\AppData\Roaming\npm\node_modules\mcp-klipper-docs\dist\server.js

# 或者使用npx
npx -y mcp-klipper-docs@1.0.1

✨ 主要特性

問題與解決方案

Klipper的文檔雖然全面，但分散在數十個Markdown文件中。查找正確的配置選項或故障排除指南需要多次點擊和搜索。而本項目改變了這一切。

問題

• 🔍 文檔碎片化：50多個獨立的Markdown文件
• 🐛 配置複雜：難以找到特定選項的詳細信息
• ⏱️ 上下文切換：在文檔和配置文件之間來回切換
• 🤖 AI限制：Claude無法訪問本地Klipper文檔

解決方案

• 🔎 統一搜索：即時搜索所有文檔
• ⚙️ 智能配置查找：獲取確切的配置部分
• 📚 智能瀏覽：按邏輯類別導航
• 🤖 AI集成：Claude成為您的Klipper專家

功能展示

🔍 搜索文檔

"搜索BLTouch配置"
"查找壓力提前的相關信息"
"查找擠出機調優指南"

⚙️ 獲取配置詳情

"獲取[擠出機]的配置"
"顯示步進電機x的設置"
"床網參數有哪些？"

📚 按章節瀏覽

"瀏覽校準文檔"
"顯示硬件配置部分"
"故障排除部分有什麼內容？"

📊 獲取統計信息

"有多少可用文檔？"
"文檔中有哪些章節？"
"顯示索引統計信息"

💻 使用示例

基礎用法

以下是使用search_klipper_docs工具搜索文檔的示例：

{
  "query": "BLTouch configuration",
  "limit": 5,
  "section": "hardware"
}

高級用法

以下是使用get_config_option工具獲取特定配置選項的示例，同時包含代碼示例：

{
  "option": "extruder",
  "include_examples": true
}

📚 詳細文檔

架構

核心組件

graph TD
    A[Claude Desktop] --> B[MCP協議]
    B --> C[MCP服務器]
    C --> D[搜索引擎]
    C --> E[文檔解析器]
    C --> F[Git同步]
    D --> G[Lunr.js索引]
    E --> H[Markdown文件]
    F --> I[Klipper倉庫]

技術棧

數據流

1. 倉庫同步：自動拉取最新的Klipper文檔
2. 文檔解析：提取內容、元數據和結構
3. 索引構建：創建可搜索的lunr.js索引
4. MCP集成：通過MCP協議暴露工具和資源
5. AI交互：Claude搜索和檢索文檔

可用工具

🔎 search_klipper_docs

在所有Klipper文檔中進行相關度評分搜索。

參數：

• query（字符串）：搜索詞
• limit（數字，可選）：最大結果數（默認：10）
• section（字符串，可選）：按章節過濾

示例：

{
  "query": "BLTouch configuration",
  "limit": 5,
  "section": "hardware"
}

⚙️ get_config_option

從Config_Reference中檢索特定配置部分。

參數：

• option（字符串）：配置選項名稱
• include_examples（布爾值，可選）：是否包含代碼示例

示例：

{
  "option": "extruder",
  "include_examples": true
}

📚 browse_documentation

按章節瀏覽文檔或獲取概述信息。

參數：

• section（字符串，可選）：要瀏覽的章節
• include_stats（布爾值，可選）：是否包含統計信息

示例：

{
  "section": "calibration",
  "include_stats": true
}

📊 get_index_stats

獲取文檔索引統計信息和元數據。

無需參數。

MCP資源

所有文檔文件都作為MCP資源提供：

• URI方案：klipper://docs/{document-id}
• 格式：帶有元數據的Markdown
• 訪問方式：直接文件讀取或瀏覽

示例資源：

• klipper://docs/Config_Reference
• klipper://docs/BLTouch
• klipper://docs/Installation
• klipper://docs/Troubleshooting

高級配置

環境變量

Docker部署

# 構建鏡像
docker build -t mcp-klipper-docs .

# 運行容器
docker run -d \
  --name mcp-klipper-docs \
  -v $(pwd)/data:/app/data \
  mcp-klipper-docs

Docker Compose

version: '3.8'
services:
  mcp-klipper-docs:
    build: .
    container_name: mcp-klipper-docs
    volumes:
      - ./data:/app/data
    environment:
      - LOG_LEVEL=info
      - UPDATE_INTERVAL=3600
    restart: unless-stopped

性能指標

索引統計

• 文檔：56個Klipper文檔文件
• 單詞：超過135,000個索引單詞
• 章節：11個分類章節
• 構建時間：完整索引約400ms
• 搜索速度：典型查詢小於10ms

內存使用

• 基礎內存：約50MB
• 索引內存：約25MB
• 峰值內存：更新期間約100MB

網絡使用

• 初始克隆：約50MB（一次性）
• 更新：約1 - 5MB（僅更改部分）
• API調用：僅本地調用（無外部依賴）

🔧 技術細節

本地開發設置

# 克隆倉庫
git clone https://github.com/yourusername/mcp-klipper-docs.git
cd mcp-klipper-docs

# 安裝依賴
npm install

# 以開發模式運行
npm run dev

# 運行測試
npm test

# 生產構建
npm run build

項目結構

mcp-klipper-docs/
├── src/
│   ├── server.ts          # 主MCP服務器
│   ├── config.ts          # 配置管理
│   ├── logger.ts          # 日誌工具
│   ├── git-sync.ts        # Git倉庫操作
│   ├── parser.ts          # Markdown文檔解析
│   ├── search.ts          # 搜索引擎實現
│   ├── types.ts           # TypeScript類型定義
│   └── errors.ts          # 錯誤處理
├── tests/                 # 測試套件
├── docs/                  # 附加文檔
├── img/                   # 圖像和資產
├── data/                  # 本地Klipper倉庫
└── dist/                  # 構建後的JavaScript文件

測試

# 運行所有測試
npm test

# 以監聽模式運行測試
npm run test:watch

# 運行測試並生成覆蓋率報告
npm run test -- --coverage

# 代碼檢查
npm run lint

# 修復代碼檢查問題
npm run lint:fix

🤝 貢獻代碼

我們歡迎Klipper社區的貢獻！以下是您可以提供幫助的方式：

🐛 報告問題

1. 首先檢查現有問題
2. 使用提供的問題模板
3. 包含：
   • 復現步驟
   • 預期行為與實際行為
   • 環境詳細信息
   • 相關日誌

💡 功能請求

1. 對於主要功能，首先開啟討論
2. 提供清晰的用例
3. 考慮實現複雜度
4. 考慮邊緣情況

🔧 代碼貢獻

1. 分叉倉庫
2. 創建功能分支：git checkout -b feature/amazing-feature
3. 進行更改：
   • 遵循現有代碼風格
   • 為新功能添加測試
   • 更新文檔
4. 運行測試套件：npm test
5. 提交拉取請求

📝 文檔貢獻

• 修正錯別字並提高清晰度
• 添加示例和用例
• 更新README和指南
• 翻譯文檔（如果您會其他語言）

📈 路線圖

1.1版本（計劃中）

• [ ] 增強搜索：模糊匹配和拼寫糾正
• [ ] 交叉引用：鏈接相關配置選項
• [ ] 版本支持：支持多個Klipper版本
• [ ] 性能優化：優化索引和緩存

長期願景

• [ ] 多語言支持：國際化支持
• [ ] 社區文檔：用戶貢獻的文檔
• [ ] AI功能：智能推薦和協助
• [ ] 集成：其他AI助手平臺

🙏 致謝

核心技術

• 模型上下文協議 - 實現AI助手集成
• Klipper - 優秀的3D打印機固件
• Lunr.js - 強大的搜索功能
• TypeScript - 類型安全的開發

社區

• Klipper社區 - 維護全面的文檔
• MCP社區 - 協議開發和支持
• 開源貢獻者 - 提供我們使用的工具和庫

📄 許可證

本項目採用MIT許可證 - 詳情請參閱LICENSE文件。

📞 支持與社區

獲取幫助

• 📖 文檔：查看本README和/docs文件夾
• 🐛 問題：在GitHub上報告錯誤
• 💬 討論：加入GitHub討論
• 📦 npm問題：報告包問題

社區

• Discord：加入Klipper和MCP社區
• Reddit：r/klipper和r/3Dprinting
• Twitter/X：關注@bpuhnk @klipper3d和MCP更新

MCP註冊表

• 註冊表條目：可用於MCP服務器發現
• 安裝：npm install -g mcp-klipper-docs
• 版本：1.0.1（最新）