WindTools MCP Server

WindTools MCP 服务

WindTools 代码助手的 MCP 服务，使用 ChromaDB 和句子转换器提供文档嵌入与检索功能。

功能

• 语义代码搜索：使用句子转换器嵌入代码片段并进行检索
• 代码仓库索引：自动为指定目录中的代码文件建立索引
• 持久化存储：在 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 服务基于以下关键组件构建：

• ChromaDB：用于存储和检索代码嵌入的向量数据库
• 句子转换器：用于从代码创建嵌入的深度学习模型
• FastMCP：用于构建符合 MCP 规范的服务的框架
• 异步生命周期管理：高效地初始化和清理资源

初始化流程

服务会在后台初始化 ChromaDB 和嵌入模型，使其能够立即开始接受请求，同时继续在后台加载资源。可以使用 get_initialization_status 工具检查初始化是否完成。

设置

环境变量

可使用以下环境变量配置服务：

• DATA_ROOT：用于存储 ChromaDB 数据库和模型缓存的目录绝对路径（默认值：软件包内名为 'data' 的目录）
• CHROMA_DB_FOLDER_NAME：ChromaDB 存储数据的文件夹名称（默认值："default"）
• SENTENCE_TRANSFORMER_PATH：句子转换器模型的路径（默认值："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 的条款和条件。