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调用和方法。

⚠️ 重要提示

确保在运行脚本前已安装所有依赖项，否则可能会导致脚本运行失败。同时，注意数据爬取可能会受到网站的反爬机制限制，请遵守相关网站的使用条款。