使用说明

项目简介

WindTools MCP服务器是一个基于 Model Context Protocol (MCP) 构建的后端服务，专为代码助手应用设计。它利用 ChromaDB 向量数据库和 sentence-transformers 模型，为大型语言模型 (LLM) 提供代码库的上下文信息检索能力。通过语义代码搜索，WindTools MCP服务器能够帮助 LLM 更好地理解代码，从而提升代码生成、代码理解等任务的性能。

主要功能点

语义代码搜索: 基于 sentence-transformers 模型对代码片段进行嵌入，实现高效的语义检索。
代码库索引: 自动索引指定目录下的代码文件，支持多种编程语言。
持久化存储: 使用 ChromaDB 持久化存储代码嵌入，保证检索效率和数据安全。
目录浏览: 提供 'list_dir' 工具，方便 LLM 客户端浏览服务器端文件系统。
后台初始化: 服务器启动时在后台异步初始化资源，减少启动延迟。
可配置的环境变量: 通过环境变量灵活配置数据存储路径、模型路径等。

安装步骤

使用 pip 安装 (推荐):

pip install windtools-mcp

从源代码安装:

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

服务器配置

要将 WindTools MCP 服务器与 MCP 客户端（例如 Claude Desktop）集成，您需要在客户端的配置文件中添加服务器配置信息。以下是一个 'claude_desktop_config.json' 的配置示例，请注意，MCP客户端只需要配置启动命令和参数，无需修改代码：

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

参数注释:

'"windtools"': 服务器名称，客户端用此名称引用该服务器。
'"command": "uvx"': 启动服务器的命令，这里使用 'uvx' (假设已安装 uv 并使用虚拟环境)， '-p 3.11' 指定使用 Python 3.11 版本（ChromaDB 在更高版本 Python 下可能存在兼容性问题），'-U windtools-mcp' 运行 'windtools-mcp' 包。
'"args": [...]"': 传递给 'uvx' 命令的参数，这里没有额外的参数。
'"env": {...}': 设置服务器运行时的环境变量：
- '"DATA_ROOT": "/path/to/your/windtools_data"': 重要数据根目录，ChromaDB 数据库和模型缓存将存储在此目录下。请将 '/path/to/your/windtools_data' 替换为您希望存储数据的实际绝对路径。
- '"CHROMA_DB_FOLDER_NAME": "chromadb"': ChromaDB 数据库存储的文件夹名称，默认为 "chromadb"。
- '"SENTENCE_TRANSFORMER_PATH": "jinaai/jina-embeddings-v2-base-code"': sentence-transformers 模型的路径，默认为 "jinaai/jina-embeddings-v2-base-code"。

请根据您的实际环境修改 'DATA_ROOT' 的值，确保 LLM 客户端能够正确启动并连接到 WindTools MCP 服务器。

基本使用方法

启动 MCP 服务器: 根据客户端配置启动 WindTools MCP 服务器。服务器启动后，会在后台初始化 ChromaDB 和 embedding 模型。

使用 'index_repository' 工具索引代码库: 通过 MCP 客户端调用 'index_repository' 工具，指定要索引的代码库目录。例如，要索引 '/path/to/your/codebase' 目录，可以调用如下工具：

{
  "tool_call_id": "index-codebase-1",
  "tool_name": "index_repository",
  "tool_input": {
    "target_directories": ["/path/to/your/codebase"]
  }
}

请将 '/path/to/your/codebase' 替换为您实际的代码库目录的绝对路径。 首次索引可能需要一些时间，取决于代码库的大小。

使用 'codebase_search' 工具进行代码搜索: 索引完成后，可以使用 'codebase_search' 工具进行语义代码搜索。例如，搜索关于 "如何处理文件上传" 的代码，可以调用如下工具：

{
  "tool_call_id": "code-search-1",
  "tool_name": "codebase_search",
  "tool_input": {
    "query": "how to handle file upload"
  }
}

服务器将返回与查询相关的代码片段及其相关信息。

使用 'list_dir' 工具浏览目录: 可以使用 'list_dir' 工具查看服务器端的文件目录结构。例如，查看 '/path/to/your/codebase' 目录的内容，可以调用如下工具：

{
  "tool_call_id": "list-dir-1",
  "tool_name": "list_dir",
  "tool_input": {
    "directory_path": "/path/to/your/codebase"
  }
}

使用 'get_initialization_status' 工具检查初始化状态: 可以使用 'get_initialization_status' 工具检查服务器后台初始化是否完成。

{
  "tool_call_id": "check-init-1",
  "tool_name": "get_initialization_status",
  "tool_input": {}
}

通过上述步骤，您可以利用 WindTools MCP 服务器为 LLM 客户端提供强大的代码上下文支持，提升代码助手应用的智能化水平。

关键词