🐝 Swarms MCP ドキュメントサーバー

バージョン2.2

📖 説明

このプログラムは、 FastMCPを基盤とするエージェントフレームワーク・ドキュメンテーション MCP サーバーであり、 AI エージェントがドキュメントデータベースから効率的に情報を取得できるように設計されています。ハイブリッドなセマンティック（ベクター）検索とキーワード（BM25）検索、チャンクインデックス、そして堅牢な FastMCP ツール API を組み合わせることで、シームレスなエージェント統合を実現します。

主な機能:

セマンティック検索とキーワード検索の両方を使用した効率的なチャンクレベルの検索
エージェントはFastMCPツールを使用してドキュメントを照会、リスト、取得できます。
ローカルファースト、低レイテンシ設計（すべてのデータはローカルでインデックス化され、クエリされる）
ファイル変更時の自動再インデックス
モジュール式: corpora/に任意のリポジトリを追加し、すべての主要なファイルタイプをサポートします
拡張可能: 必要に応じて新しいツール、リトリーバー、またはコーパスを追加できます

メインモジュール:

embed_documents.py → ドキュメントを読み込み、チャンク化し、埋め込みます
swarms_server.py → MCPサーバーとFastMCPツールを起動します

Related MCP server: MCP Expert Server

🌟 主な機能

ハイブリッドリトリーバー🔍: セマンティック検索とキーワード検索を組み合わせます。
動的な 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 環境が必要です

環境を明示的に作成します。

python3.11 -m venv venv

次に次のコマンドでインストールします:

pip install -r requirements.txt

✅ MCP サーバー対応

起動後:

適切な読み込みサマリー
高価なアクションの前に安全を確認する
自動ファイル監視と再インデックス
ウィンドサーフィンプラグイン対応
完全なツールカバレッジ

カスケードしても大丈夫です！ 🏄‍♂️

📈 フロー図

Swarms MCP Documentation Server