Pybricks MCP

🚀 Pybricksの初学者向けMCPベースRAGアシスタント

このプロジェクトは、初心者のPython + Pybricks開発者（FLLの子供たちやコーチ）向けのMCPベースのRAGアシスタントのためのブループリントです。Pybricksの公式ドキュメントやサイトから具体的な詳細を取り入れ、アシスタントが根拠のある、バージョンを意識した回答を提供できるようにします。

🚀 クイックスタート

まずは、このスターターキットを動かしてみましょう。以下に2つのファイルがあります。

1. ingest_pybricks.py — Pybricksの公式ドキュメントやチュートリアル、重要なGitHubページをクロールし、適切に分割してChromaDBのコレクションを構築します。
2. mcp_server.py — Chromaコレクションをバックエンドに持つ、docs.search、code.search、snippet.suggest、compare.versions を公開する最小限のMCPスタイルのツールサーバーです。

✨ 主な機能

• 初心者にとって最も有用で安定した情報源をクロールし、ChromaDBにインデックスを作成します。
• ツールサーバーを介して、ドキュメント検索、コード検索、スニペット提案、バージョン比較などの機能を提供します。
• 初学者に配慮したガードレールやヒューリスティックを備えています。

📦 インストール

依存関係のインストール

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 の基本的な使用法
python ingest_pybricks.py

# mcp_server.py の基本的な使用法
uvicorn mcp_server:app --reload --port 8765

高度な使用法

# 特定のバージョンやカテゴリでドキュメントを検索する例
import requests

url = "http://localhost:8765/tools/docs.search"
data = {
    "query": "DriveBase",
    "filters": {
        "version": "latest",
        "category": "robotics"
    }
}

response = requests.post(url, json=data)
print(response.json())

📚 ドキュメント

インジェストする情報源

• 公式APIドキュメント（安定版 + 最新版）：docs.pybricks.com のロボット工学やパラメーター、定数などのドキュメント。
• 入門ガイドとIDEの基本：pybricks.com/learn/getting-started/* や code.pybricks.com のランディングページ。
• 初心者向けのチュートリアルやサンプル：ハブとPCの通信、ボタンの基本操作などのチュートリアル。
• 変更履歴：pybricks-code と pybricks-micropython のCHANGELOG。
• pybricksdevのドキュメント：オプションのコーチ用ツールのドキュメント。

ツールサーバーのAPI

• docs.search(query, filters)：クエリとフィルターを指定してドキュメントを検索します。
• code.search(symbol)：指定したシンボルを含むコードを検索します。
• snippet.suggest(goal, hardware)：指定した目標とハードウェアに適したコードスニペットを提案します。
• compare.versions(feature)：指定した機能のバージョン変更を確認します。

🔧 技術詳細

データのクロールとインデックス作成

ingest_pybricks.py は、指定されたURLをクロールし、HTMLをMarkdownに変換してから、適切なサイズに分割します。分割されたデータはChromaDBにインデックス化されます。

ツールサーバーの実装

mcp_server.py は、FastAPIを使用して実装されたツールサーバーです。ChromaDBからデータを取得し、クエリに応じた結果を返します。

データの前処理とチャンク化

• Markdown/HTMLドキュメント：見出し（H2/H3）で分割し、コードブロックやテーブルを保持します。
• Pythonサンプル/スニペット：関数やクラスごとに分割し、シグネチャ、ドキュメント文字列、インポートを含めます。

インデックスと検索

• ハイブリッド検索：密な埋め込みとBM25/正規表現を組み合わせてシンボルヒットを検索します。
• 親子関係：小さなチャンクを埋め込み、必要に応じて親セクション/ファイルを展開します。
• マルチベクトル：全文、見出し/シグネチャビュー、識別子のみのベクトルを作成します。
• バージョンフィルター：各チャンクにバージョン、チャネル、ソースなどのタグを付けます。
• リランク：正確なシンボル一致、バージョンの近さ、ドキュメントセクションのタイプで上位K件をリランクします。

📄 ライセンス

このドキュメントにはライセンス情報が記載されていません。