JinDaGe - windtools-mcp MCP Details

article

README

🚀 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：句子转换器的可执行文件路径，必须可执行。

安装步骤

安装依赖：

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

💻 使用示例

基础用法

客户端连接

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：用于存储和检索代码嵌入，支持高效的文本搜索。
句子转换器：负责将代码片段转换为向量表示，以便进行相似性计算。
异步处理：通过异步任务管理资源加载和查询请求，提升系统响应速度。

初始化流程

服务器启动时，自动从指定目录读取代码文件，并将其嵌入到 ChromaDB 中。
确保所有环境变量正确配置，特别是 WINDTOOLS_HOME 和 CHROMA_DB_URL。
启动后，服务器监听特定端口，等待客户端连接和请求。

📄 许可证

本 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。

windtools-mcp