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（最新）