Pybricks MCP

🚀 Pybricks項目啟動指南

本項目為基於MCP的RAG助手提供了一個簡潔而可靠的藍圖，專為Python和Pybricks初學者（如FLL兒童和教練）設計。它通過整合Pybricks的官方文檔和示例，為用戶提供基於實際情況、版本感知的答案。

🚀 快速開始

本項目包含兩個核心文件，助您快速搭建起工作環境：

1. ingest_pybricks.py：該腳本會爬取官方的Pybricks文檔、教程以及關鍵的GitHub頁面，對內容進行合理分塊，並構建一個ChromaDB集合。
2. mcp_server.py：這是一個輕量級的MCP風格工具服務器，它基於Chroma集合，提供了docs.search、code.search、snippet.suggest和compare.versions等功能。

初始爬取範圍已限制在對初學者最有用、最穩定的頁面，如API參考、參數/常量、機器人技術/DriveBase、入門指南、教程和更新日誌等。您可以在後續添加更多內容。

✨ 主要特性

• 數據爬取：從官方文檔和教程中提取關鍵信息，構建ChromaDB集合。
• 工具服務：提供多種搜索和建議功能，方便用戶查找文檔、代碼示例和版本信息。
• 版本感知：支持根據版本過濾搜索結果，確保答案與用戶使用的版本一致。
• 初學者友好：使用官方API調用和示例，避免複雜的技巧，易於理解和使用。

📦 安裝指南

依賴安裝

運行腳本前，請確保已安裝以下依賴：

pip install requests beautifulsoup4 lxml markdownify tiktoken chromadb sentence-transformers fastapi uvicorn

數據攝入

首次運行或定期更新數據時，執行以下命令：

python ingest_pybricks.py

啟動服務

啟動工具服務器：

uvicorn mcp_server:app --reload --port 8765

💻 使用示例

基礎用法

以下是使用ingest_pybricks.py腳本的示例：

#!/usr/bin/env python3
"""
Build a beginner-friendly Pybricks RAG corpus into ChromaDB.

- Crawls/loads selected Pybricks docs/tutorials + key GitHub changelogs.
- Normalizes & chunks (HTML/Markdown-aware; preserves code blocks).
- Creates multi-view docs (full text + headings/signatures + identifiers).
- Indexes into ChromaDB collections: pybricks_docs and pybricks_snippets.

Requires: requests, beautifulsoup4, lxml, markdownify, tiktoken, chromadb, sentence-transformers
    pip install requests beautifulsoup4 lxml markdownify tiktoken chromadb sentence-transformers
"""

# 後續代碼保持不變...

高級用法

以下是使用mcp_server.py提供的工具的示例：

# 發送文檔搜索請求
import requests

data = {
    "query": "DriveBase的使用方法",
    "filters": {"version": "latest"}
}

response = requests.post("http://localhost:8765/tools/docs.search", json=data)
print(response.json())

📚 詳細文檔

攝入數據範圍

初始允許列表包含以下內容：

• API文檔（穩定版和最新版）：docs.pybricks.com，包括機器人技術/DriveBase和參數/常量。(Pybricks Documentation)
• 入門指南和IDE基礎：pybricks.com/learn/getting-started/*，code.pybricks.com主頁。(Pybricks, Pybricks Code)
• 初學者友好的教程和示例：如集線器到PC和集線器到集線器的通信、按鈕基礎、快速參考等。(Pybricks)
• 更新日誌（用於版本檢查）：pybricks-code和pybricks-micropython的更新日誌。(GitHub)
• pybricksdev文檔（可選輔助工具）：(Pybricks Documentation, GitHub)

工具服務器接口

• docs.search(query, filters)：混合密集搜索，可根據版本和來源進行過濾。
• code.search(symbol)：優先查找標識符匹配的結果。
• snippet.suggest(goal, hardware)：返回預定義的代碼模板。
• compare.versions(feature)：檢查更新日誌，查找特定功能的版本信息。

未來升級方向

• 添加對Python示例的AST感知分塊：對於本地保存的Python示例，進行更精細的分塊處理。
• 重排序：在密集搜索後，根據精確匹配的符號（如DriveBase.turn、Port.A等）提升結果排名。
• 版本提示：在答案中顯示版本信息，如“在v3.5中添加”。

🔧 技術細節

數據爬取與處理

ingest_pybricks.py腳本通過以下步驟完成數據的爬取和處理：

1. 配置種子URL和允許的域名：定義初始爬取的URL列表和允許的域名範圍。
2. 爬取頁面：使用requests庫發送HTTP請求，獲取頁面內容，並使用BeautifulSoup解析HTML。
3. 轉換為Markdown：將HTML內容轉換為Markdown格式，同時保留代碼塊和標題。
4. 分塊處理：根據標題（H1 - H3）將Markdown內容分割成多個部分，並進行窗口化處理，確保每個塊的長度在指定的令牌範圍內。
5. 提取標識符：從文本中提取可能的標識符，如符號、常量、錯誤名稱等。
6. 構建記錄：為每個分塊生成唯一的ID，並添加元數據，如URL、標題、版本等。
7. ChromaDB插入：將記錄插入到ChromaDB集合中，並創建一個輕量級的標識符集合，用於重排序。

工具服務器實現

mcp_server.py使用FastAPI框架實現了一個簡單的工具服務器，提供了以下接口：

1. /tools/docs.search：處理文檔搜索請求，支持根據版本和來源進行過濾。
2. /tools/code.search：處理代碼搜索請求，優先查找標識符匹配的結果。
3. /tools/snippet.suggest：根據目標和硬件信息，返回預定義的代碼模板。
4. /tools/compare.versions：檢查更新日誌，查找特定功能的版本信息。

索引與檢索策略

• 混合搜索：結合密集嵌入和BM25/正則表達式，提高符號匹配的準確性。
• 父子關係：嵌入小的分塊，並保留“父”部分或文件，以便在需要時擴展。
• 多向量表示：每個分塊使用多個向量表示，包括全文、標題/簽名視圖和僅標識符視圖。
• 版本過濾：為每個分塊標記版本信息，支持根據版本過濾搜索結果。
• 重排序：根據精確符號匹配、版本接近度和文檔類型對前K個結果進行重排序。

📄 許可證

文檔中未提及相關許可證信息。

💡 使用建議

• 定期運行ingest_pybricks.py腳本，以更新ChromaDB集合中的數據。
• 在使用工具服務器時，根據需要調整搜索參數，如k值和過濾條件，以獲得更準確的結果。
• 對於初學者，建議參考官方文檔和示例，以確保使用正確的API調用和方法。

⚠️ 重要提示

確保在運行腳本前已安裝所有依賴項，否則可能會導致腳本運行失敗。同時，注意數據爬取可能會受到網站的反爬機制限制，請遵守相關網站的使用條款。