LuzzyTool

基于 MCP (Model Context Protocol) 的本地智能工具集合，为 AI 助手提供文件管理、文档编辑、Shell 执行、语义检索与文本处理能力。通过 stdio 传输协议与 MCP 客户端无缝集成。

前置条件

安装

# 克隆项目
git clone https://github.com/your-org/luzzy-tool.git
cd luzzy-tool

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate   # Linux / macOS
venv\Scripts\activate      # Windows

# 安装依赖
pip install -r requirements.txt

# （可选）手动下载模型，否则首次调用工具时自动下载
python scripts/download_models.py

本地配置使用

将工具注册到你的 MCP 客户端（Claude Desktop、Continue、Cursor 等）中。

方式一：JSON 一键导入配置

适用于 Claude Desktop 等支持直接编辑 claude_desktop_config.json 的客户端。

路径说明：

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

将以下内容粘贴到配置文件的 mcpServers 字段中（如果该字段不存在则新建）：

{
  "mcpServers": {
    "luzzy-tool": {
      "command": "python",
      "args": [
        "-u",
        "run_server.py"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "DEVICE": "auto"
      },
      "description": "本地文件管理、Shell 执行、语义检索、文档编辑多功能工具集"
    }
  }
}

提示：

• 如果使用虚拟环境，将 "command" 改为虚拟环境中的 Python 解释器路径，如 "D:/Projects/luzzy-tool/venv/Scripts/python.exe"（Windows）或 "/home/user/luzzy-tool/venv/bin/python"（Linux/macOS）

• 将 "args" 中的 "run_server.py" 替换为实际脚本路径

方式二：手动逐项填写

适用于需要逐字段填写的 GUI 客户端：

验证安装

在 Claude Desktop 或支持 MCP 的客户端中，尝试发起以下调用即可验证：

1. 列出可用工具 — 让 AI 助手列出 luzzy-tool 提供的工具

2. 读取文件 — 尝试让 AI 读取一个已知路径的文本文件

3. 执行命令 — 尝试让 AI 执行 echo "Hello from LuzzyTool"

如果以上操作都能正常执行并返回结果，说明工具已正确连接。

可用工具一览

环境变量

在 .env 文件或配置的 env 字段中设置：

# 日志级别：DEBUG, INFO, WARNING, ERROR
LOG_LEVEL=INFO

# 运行设备：auto, cpu, cuda
DEVICE=auto

# 模型路径（可选，默认 ./models/）
EMBEDDING_MODEL_PATH=./models/bge-small-zh-v1.5
RERANKER_MODEL_PATH=./models/bge-reranker-base

# 检索配置
DEFAULT_TOP_K=5
CHUNK_SIZE=500
CHUNK_OVERLAP=100

问题排查

spawn ENOENT 或 command not found

命令 python 在客户端运行环境中不可用。

解决：将配置文件中的 "command" 改为 Python 解释器的完整绝对路径。使用以下命令查看：

python -c "import sys; print(sys.executable)"

权限不足 / PermissionError

MCP 工具尝试访问的路径无读写权限。

解决：确保 AI 助手操作的目标目录有适当权限，或将工作目录限制在用户目录下。

模型下载失败

首次使用检索功能时需下载嵌入模型（约 400MB）。

解决：

• 手动运行 python scripts/download_models.py

• 或设置 HuggingFace 镜像：export HF_ENDPOINT=https://hf-mirror.com

ModuleNotFoundError: No module named 'src'

未从项目根目录启动或 Python 路径配置不正确。

解决：确保在项目根目录执行，且 args 参数中脚本路径正确。

响应缓慢 / 超时

模型加载或向量检索在 CPU 上较慢。

解决：

• 设置 DEVICE=cuda 使用 GPU（需 CUDA 版 PyTorch）

• 减少 DEFAULT_TOP_K 值

• 首次调用后模型常驻内存，后续响应会加速

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request。

项目开发

DeepSeek-V4-Pro