🐝 Swarms MCP ドキュメントサーバー
📖 説明
このプログラムは、 FastMCPを基盤とするエージェントフレームワーク・ドキュメンテーション MCP サーバーであり、 AI エージェントがドキュメントデータベースから効率的に情報を取得できるように設計されています。ハイブリッドなセマンティック（ベクター）検索とキーワード（BM25）検索、チャンクインデックス、そして堅牢な FastMCP ツール API を組み合わせることで、シームレスなエージェント統合を実現します。
主な機能:
- セマンティック検索とキーワード検索の両方を使用した効率的なチャンクレベルの検索
- エージェントはFastMCPツールを使用してドキュメントを照会、リスト、取得できます。
- ローカルファースト、低レイテンシ設計（すべてのデータはローカルでインデックス化され、クエリされる）
- ファイル変更時の自動再インデックス
- モジュール式:
corpora/に任意のリポジトリを追加し、すべての主要なファイルタイプをサポートします - 拡張可能: 必要に応じて新しいツール、リトリーバー、またはコーパスを追加できます
メインモジュール:
embed_documents.py → ドキュメントを読み込み、チャンク化し、埋め込みますswarms_server.py → MCPサーバーとFastMCPツールを起動します
🌟 主な機能
- ハイブリッド リトリーバー🔍: セマンティック検索とキーワード検索を組み合わせます。
- 動的な Markdown 処理📄: ファイル サイズに基づいたスマート ローダー。
- 特殊なローダー⚙️:
.py 、 .ipynb 、 .md 、 .txt 、 .yaml 、 .yml 。 - チャンクとファイルの概要📈: チャンク数とファイル数を表示します。
- ライブウォッチドッグ🔥:
corpora/内のあらゆる変更に即座に応答します。 - コストに関するユーザー確認✅: 高価な埋め込みの前に確認します。
- ヘルスチェックエンドポイント🚑: サーバーが使用可能であることを確認します。
- ローカルファースト🗂️: すべてのリポジトリは外部依存関係なしでローカルにインデックス付けされます。
- 安全な削除ヘルパー🔥: 壊れた/不一致のインデックスを自動削除します。
🏗️ バージョン履歴
| バージョン | 日付 | ハイライト |
|---|
| 2.2 | 2025年4月25日 | サーバーからの埋め込み/読み込みを分割し、読み込みサマリーでチャンク全体をカウントします。 |
| 1.0 | 2025年4月25日 | ダイナミックマークダウンローダー、カラーログ、ヘルスチェックツール |
| 0.7 | 2025年4月25日 | .py 、 .ipynb 、 .md用の特殊なファイルローダー |
| 0.5 | 2025年4月10日 | OpenAIの大規模モデル埋め込み、拡張MCPツール |
| 0.1 | 2025年4月10日 | 汎用ローダー付きの初期バージョン |
📚 コーパスの管理（ローカルリポジトリ）
Swarms やその他のフレームワークは非常に大きいため、完全なコーパスは GitHub にプッシュされません。
代わりに、 corpora/の下に手動でクローンを作成します。
# Inside your project folder:
cd corpora/
# Clone useful frameworks:
git clone https://github.com/SwarmsAI/Swarms
git clone https://github.com/SwarmsAI/Swarms-Examples
git clone https://github.com/microsoft/autogen
git clone https://github.com/langchain-ai/langgraph
git clone https://github.com/openai/openai-agent-sdk
✅注記:
- パブリック、プライベート、カスタムなど、任意のリポジトリを追加します。
- 独自のカスタム AI ナレッジ ベースをローカルに構築します。
- 大きなリポジトリ(>500 MB) でも問題ありません。すべてのインデックスはローカルで行われます。
🚀 クイックスタート
# 1. Activate virtual environment
venv\Scripts\Activate.ps1
# 2. Install all dependencies
pip install -r requirements.txt
# 3. Configure OpenAI API Key
echo OPENAI_API_KEY=sk-... > .env
# 4. (Load and embed documents
python embed_documents.py
# 5. Start MCP server
python swarms_server.py
# If no index is found, the server will prompt you to embed documents automatically.
⚙️ 構成
- コーパス:
corpora/ - 環境変数:
.envにはOPENAI_API_KEYが含まれている必要があります
- インデックスファイルのサポート:
chroma-collections.parquetとchroma.sqlite3の両方がサポートされています。両方存在する場合は.parquetが優先されます。
- 自動埋め込み:
- インデックスが見つからない場合、サーバーはドキュメントを自動的に埋め込み、インデックスを作成す��ように要求します。
- オプション:
- 必要に応じて、Chroma 圧縮を無効にします。
setx CHROMA_COMPACTION_SERVICE__COMPACTOR__DISABLED_COLLECTIONS "swarms_docs"
- コマンドラインフラグ:
--reindex → サーバー実行中に更新再インデックスをトリガーします。
🔄 ファイル監視と自動再インデックス
MCP サーバーは、 corpora/ファイルの変更を監視します。
- 変更、作成、または削除が行われると、ライブ再インデックスがトリガーされます。
- サーバーを再起動する必要はありません。
🛠️ 利用可能なFastMCPツール
| 道具 | 説明 |
|---|
swarm_docs.search | 関連するドキュメントチャンクを検索 |
swarm_docs.list_files | インデックスされたすべてのファイルを一覧表示する |
swarm_docs.get_chunk | パスとインデックスで特定のチャンクを取得する |
swarm_docs.reindex | 強制的に再インデックス（完全または増分） |
swarm_docs.healthcheck | MCPサーバーのステータスを確認する |
❓ トラブルシューティング
- Q: サーバーの起動時に「有効な既存のインデックスが見つかりません」というメッセージが表示されます。
- A: サーバーからドキュメントの埋め込みとインデックス作成を促すメッセージが表示されます。プロンプトに従って続行するか、
python embed_documents.py手動で実行してください。
- Q: どのインデックス ファイルが使用されますか?
- A: サーバーは、利用可能な場合は
chroma-collections.parquetを使用し、そうでない場合はchroma.sqlite3使用します。
- Q: 強制的に再インデックスを実行したいです。
- A:
python swarms_server.py --reindex実行するか、 swarm_docs.reindexツールを使用します。
📋 使用例
# Search the documentation
result = swarm_docs.search("How do I load a notebook?")
print(result)
# List all available files
files = swarm_docs.list_files()
print(files)
# Get a specific document chunk
chunk = swarm_docs.get_chunk(path="examples/agent.py", chunk_idx=2)
print(chunk["content"])
🧰 拡張と再構築
- 新しいドキュメントを追加→
corpora/にドロップして、次の操作を実行します。python swarms_server.py --reindex
- スキーマの変更→ (例: メタデータ構造の違い):
python swarms_server.py --reindex --full
- 新しいリポジトリを追加→
corpora/下にフォルダーをドロップし、インデックスを再作成します。 - 主に読み取り専用のリポジトリに推奨:
setx CHROMA_COMPACTION_SERVICE__COMPACTOR__DISABLED_COLLECTIONS "swarms_docs"
🔗 IDE統合
Windsurf Cascade に直接接続します。
"swarms": {
"command": "C:/…/Swarms/venv/Scripts/python.exe",
"args": ["swarms_server.py"]
}
その後、Cascade 自動化からswarm_docs.*ツールにアクセスできるようになります。
📦 要件
💡 Python 3.11 環境が必要です
環境を明示的に作成します。
次に次のコマンドでインストールします:
pip install -r requirements.txt
✅ MCP サーバー対応
起動後:
- 適切な読み込みサマリー
- 高価なアクションの前に安全を確認する
- 自動ファイル監視と再インデックス
- ウィンドサーフィンプラグイン対応
- 完全なツールカバレッジ
カスケードしても大丈夫です！ 🏄♂️
📈 フロー図
+------------------+
| 🖥️ MCP Server |
+------------------+
|
+---------------------------------------------------+
| |
+-------------+ +-----------------+
| 📁 Corpora | | 🔎 FastMCP Tools |
| Folder | | (search, list, |
| (markdown, | | get_chunk, etc.) |
| code, etc) | +-----------------+
+-------------+ |
| |
+-----------------+ +----------------+
| 📚 Loaders | | 🧠 Ensemble |
| (Python, MD, TXT)| | Retriever (BM25|
| Split into Chunks| | + Chroma) |
+-----------------+ +----------------+
| |
+-----------------+ +----------------+
| ✂️ Text Splitter | | 🧩 Similarity |
| (RecursiveCharacter) | | Search (chunks) |
+-----------------+ +----------------+
| |
+-----------------+ +----------------+
| 💾 Embed chunks | —OpenAI Embedding (small)—> | 🛢️ Chroma Vector |
| via OpenAI API | | DB (Local Store) |
+-----------------+ +----------------+
| |
+-----------------+ +----------------+
| 📡 Reindex Watcher| | 👀 File Watchdog |
| (Auto detect | | (Auto reindex |
| new/modified files| | on file events) |
+-----------------+ +----------------+