WindTools MCP Server

WindTools MCP Server

WindTools コードアシスタント用の MCP サーバーです。ChromaDB と sentence transformers を使用したドキュメントの埋め込みと検索機能を提供します。

機能

• セマンティックコード検索：sentence transformers を使用してコードスニペットを埋め込み、検索します
• コードリポジトリのインデックス作成：指定したディレクトリ内のコードファイルを自動的にインデックス化します
• 永続ストレージ：コードの埋め込みを ChromaDB に保存し、永続的に検索できるようにします
• ディレクトリの探索：コードベースの移動や探索に使用できる組み込みツールを備えています
• バックグラウンド初期化：リソースを非同期に読み込み、起動時間を最小限に抑えます
• 環境設定：環境変数で設定できます

ツール

1. list_dir

   • ディレクトリの内容を一覧表示します
   • 入力：
     • directory_path（文字列）：内容を一覧表示するディレクトリのパス。ディレクトリの絶対パスを指定してください
   • 戻り値：ファイルの種類やサイズなど、ディレクトリ情報を含む JSON 文字列

2. get_initialization_status

   • バックグラウンド初期化プロセスの状態を確認します
   • 戻り値：ChromaDB と埋め込みモデルの初期化状態を含む JSON 文字列

3. index_repository

   • 指定したディレクトリ内のコードファイルを ChromaDB にインデックス化します
   • 入力：
     • target_directories（文字列の配列）：インデックス化するディレクトリの絶対パスのリスト
     • force_reindex（ブール値、任意）：true の場合、すでにインデックスに存在するファイルも含め、すべてのファイルを再インデックス化します
   • 戻り値：インデックス作成の統計情報と結果を含む JSON 文字列

4. codebase_search

   • 検索クエリに関連するコードスニペットを見つけます
   • 入力：
     • query（文字列）：探している内容を説明する検索クエリ
     • limit（整数、任意）：返す結果の最大数（デフォルト：10）
     • min_relevance（浮動小数点数、任意）：関連性スコアの最小しきい値（0.0～1.0）
   • 戻り値：関連するコードスニペットを含む検索結果の JSON 文字列

技術アーキテクチャ

WindTools MCP Server は、次の主要コンポーネントで構成されています。

• ChromaDB：コードの埋め込みを保存・取得するベクトルデータベース
• Sentence Transformers：コードから埋め込みを作成する深層学習モデル
• FastMCP：MCP 準拠サーバーを構築するためのフレームワーク
• 非同期ライフスパン管理：効率的なリソースの初期化とクリーンアップ

初期化プロセス

サーバーは ChromaDB と埋め込みモデルをバックグラウンドで初期化するため、リソースの読み込みを続けながら、すぐにリクエストを受け付けられます。初期化が完了したかどうかは、get_initialization_status ツールで確認できます。

セットアップ

環境変数

次の環境変数でサーバーを設定できます。

• DATA_ROOT：ChromaDB データベースとモデルキャッシュを保存する絶対ディレクトリ（デフォルト：パッケージ内の「data」ディレクトリ）
• CHROMA_DB_FOLDER_NAME：ChromaDB がデータを保存するフォルダーの名前（デフォルト：「default」）
• SENTENCE_TRANSFORMER_PATH：sentence transformer モデルのパス（デフォルト：「jinaai/jina-embeddings-v2-base-code」）

インストール

pip を使用する

pip install windtools-mcp

ソースからインストールする

git clone https://github.com/ZahidGalea/windtools-mcp
cd windtools-mcp
pip install -e .

Claude Desktop での使用方法

claude_desktop_config.json に次の内容を追加してください。

直接実行

ChromaDB は新しいバージョンの Python で問題が発生するため、Python 3.11 を使用してください。

{
  "mcpServers": {
    "windtools": {
      "command": "uvx",
      "args": [
        "-p",
        "3.11",
        "-U",
        "windtools-mcp"
      ],
      "env": {
        "DATA_ROOT": "/Users/<user>/windtools_data",
        "CHROMA_DB_FOLDER_NAME": "chromadb",
        "SENTENCE_TRANSFORMER_PATH": "jinaai/jina-embeddings-v2-base-code"
      }
    }
  }
}

データ（ChromaDB データベースとモデルキャッシュを含む）は /Users/<user>/windtools_data ディレクトリに保存され、コンテナの実行をまたいで保持されます。

開発

要件

• Python 3.11
• pyproject.toml に記載された依存関係

開発環境のセットアップ

開発する場合：

# Install development dependencies
uv sync --dev

ローカルで使用する場合：

pip install -e .

ローカル開発用の設定：

{
  "mcpServers": {
    "windtools": {
      "command": "uv",
      "args": [
        "run",
        "windtools-mcp"
      ],
      "env": {
        "DATA_ROOT": "/Users/<user>/windtools_data",
        "CHROMA_DB_FOLDER_NAME": "chromadb",
        "SENTENCE_TRANSFORMER_PATH": "jinaai/jina-embeddings-v2-base-code"
      }
    }
  }
}

Inspector

npx @modelcontextprotocol/inspector uvx -p 3.11 windtools-mcp

npx @modelcontextprotocol/inspector uv run windtools-mcp

テストの実行

pytest tests/

このプロジェクトには、非同期機能のテスト用に pytest と pytest-asyncio を使用した単体テストと統合テストが含まれています。

プロジェクト構成

src/
  windtools_mcp/
    __init__.py
    __main__.py
    server.py
tests/
  test_client.py
  test_unit.py
.github/
  workflows/
    publish.yml
    test.yml
.gitignore
.python-version
pyproject.toml
README.md
VERSION

リリースプロセス

プロジェクトのバージョンは、VERSION ファイルで一元管理されています。リリースプロセスは自動化されています。

1. VERSION ファイルのバージョン番号を更新します
2. main ブランチにコミットしてプッシュします
3. GitHub Actions ワークフローが自動的に次の処理を実行します：
   • VERSION ファイルの変更を検出します
   • v{VERSION} 形式の Git タグを作成します
   • GitHub でリリースを作成します
   • パッケージを PyPI に公開します

タグを手動で作成したり、PyPI に公開したりする必要はありません。VERSION ファイルを更新すると、すべて自動的に処理されます。

ライセンス

この MCP サーバーは MIT License の下でライセンスされています。MIT License の利用規約に従うことを条件に、ソフトウェアを自由に使用、変更、配布できます。