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。