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

🐝 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 環境が必要です

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

python3.11 -m venv venv

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

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) |
+-----------------+                                   +----------------+

Swarms MCP Documentation Server

Integrations