Windtools MCP

🚀 WindTools MCP 服務器

WindTools 代碼助手的 MCP 服務器，藉助 ChromaDB 和句子轉換器，提供文檔嵌入和檢索功能，有效助力代碼搜索與管理。

🚀 快速開始

服務器啟動時，會自動從指定目錄讀取代碼文件，並將其嵌入到 ChromaDB 中。你需要確保所有環境變量正確配置，特別是 WINDTOOLS_HOME 和 CHROMA_DB_URL。啟動後，服務器會監聽特定端口，等待客戶端連接和請求。

安裝依賴

pip install chroma-db sentence-transformers

啟動服務器

python -m windtools_mcp.server start

配置示例

export WINDTOOLS_HOME=/path/to/windtools
export CHROMA_DB_URL=http://localhost:8000

✨ 主要特性

• 語義代碼搜索：利用句子轉換器對代碼片段進行嵌入並實現檢索。
• 代碼庫索引：自動從指定目錄中索引代碼文件。
• 持久存儲：將代碼嵌入保存在 ChromaDB 中，以支持持久檢索。
• 目錄探索：內置工具用於導航和探索代碼庫。
• 背景初始化：異步加載資源，以最小化啟動時間。
• 環境配置：可通過環境變量進行配置。

📦 安裝指南

環境變量配置

• WINDTOOLS_HOME：指定 WindTools 的安裝目錄，默認為當前工作目錄。
• CHROMA_DB_URL：ChromaDB 服務的 URL 地址，默認為本地運行的實例。
• SENTENCE_CONVERTER_PATH：句子轉換器的可執行文件路徑，必須可執行。

安裝步驟

1. 安裝依賴：

   pip install chroma-db sentence-transformers
   

2. 啟動服務器：

   python -m windtools_mcp.server start
   

3. 配置示例：

   export WINDTOOLS_HOME=/path/to/windtools
   export CHROMA_DB_URL=http://localhost:8000
   

💻 使用示例

基礎用法

客戶端連接

curl -X POST http://localhost:5000/api/list_dir

索引代碼庫

python scripts/index_codebase.py --directory /path/to/your/code

📚 詳細文檔

工具集

list_dir

• 功能：列出某個目錄的內容。
• 輸入：
  • directory_path (字符串)：要列出內容的絕對路徑，應為目錄路徑。
• 輸出：返回指定目錄中的所有文件和子目錄。

get_file_content

• 功能：獲取指定文件的內容。
• 輸入：
  • file_path (字符串)：目標文件的絕對路徑。
• 輸出：返回文件內容，或錯誤信息（如果文件不存在）。

search_code

• 功能：根據關鍵詞搜索代碼庫。
• 輸入：
  • keywords (列表)：要搜索的關鍵詞列表。
• 輸出：返回匹配代碼片段的位置和內容。

🔧 技術細節

技術架構

• ChromaDB：用於存儲和檢索代碼嵌入，支持高效的文本搜索。
• 句子轉換器：負責將代碼片段轉換為向量表示，以便進行相似性計算。
• 異步處理：通過異步任務管理資源加載和查詢請求，提升系統響應速度。

初始化流程

1. 服務器啟動時，自動從指定目錄讀取代碼文件，並將其嵌入到 ChromaDB 中。
2. 確保所有環境變量正確配置，特別是 WINDTOOLS_HOME 和 CHROMA_DB_URL。
3. 啟動後，服務器監聽特定端口，等待客戶端連接和請求。

📄 許可證

本 MCP 服務器遵循 MIT 許可證。這意味著您可以自由使用、修改和分發軟件，但需遵守 MIT 許可證的條款和條件。

開發相關

開發要求

• 代碼結構：遵循標準的 Python 項目結構，確保模塊間依賴明確。
• 測試覆蓋率：使用 pytest 和 pytest-asyncio 進行全面測試，保證各功能正常運行。

測試指令

pytest tests/

項目結構

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 工作流自動執行：
     • 創建名為 v{VERSION} 的 Git 標籤。
     • 發佈到 GitHub 和 PyPI。