🐝 Swarms MCP Documentation Server

🐝 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‑04‑25	埋め込み／読み込み処理をサーバーから分離。読み込み概要でチャンク数をすべてカウント
1.0	2025‑04‑25	動的 Markdown ローダー、カラーのログ、ヘルスチェックツール
0.7	2025‑04‑25	.py、.ipynb、.md 用の専用ファイルローダー
0.5	2025‑04‑10	OpenAI の大規模モデルによる埋め込み、拡張された MCP ツール
0.1	2025‑04‑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 ナレッジベースをローカルに構築できます。
• 大規模なリポジトリ（500MB 超）にも対応しています。インデックス作成はすべてローカルで行われます。

---

🚀 クイックスタート

# 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: サーバーの起動時に「No valid existing index found」と表示されます。
  • 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 サーバーの準備完了

起動後：

• 適切な読み込みサマリー
• 負荷の高い操作の前に安全に確認
• ファイルの自動監視と再インデックス
• Windsurf プラグイン対応
• すべてのツールを網羅

これで Cascade を利用できます！ 🏄‍♂️

---

📈 フロー図

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