LuzzyTool

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

前置条件

依赖	要求
Python	3.10+
pip	最新版本（推荐 24.0+）
磁盘空间	~2 GB（模型文件首次下载）
操作系统	Windows / macOS / Linux

安装

# 克隆项目
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 客户端：

字段	值	说明
名称	luzzy-tool	工具在客户端中的显示名称，可自定义
命令	python	或虚拟环境中的 python 绝对路径
命令参数	-u run_server.py	-u 关闭 Python 输出缓冲；路径为项目根目录下的启动脚本
环境变量	LOG_LEVEL=INFO	可选，DEVICE=auto 指定设备（auto/cpu/cuda）
描述	本地文件管理、Shell 执行、语义检索、文档编辑多功能工具集	可选，帮助客户端了解工具用途

验证安装

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

1. 列出可用工具 — 让 AI 助手列出 luzzy-tool 提供的工具
2. 读取文件 — 尝试让 AI 读取一个已知路径的文本文件
3. 执行命令 — 尝试让 AI 执行 echo "Hello from LuzzyTool"

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

可用工具一览

类别	工具名	功能
文件管理	list_local_directory	列出目录内容
	read_local_file	读取文本文件
	file_write	写入文件
	move_file / copy_file	移动 / 复制文件
	delete_file / delete_files	删除文件
	rename_file	重命名文件
	create_directory	创建目录
	search_files	按模式搜索文件
	get_file_info	获取文件元信息
	backup_file / restore_file / list_backups	备份与恢复
Shell	execute_command	执行 Shell 命令
	execute_batch	批量执行命令
	get_system_info	获取系统信息
	set_env	设置环境变量
文档编辑	edit_paragraph	编辑段落
	get_paragraphs	获取段落内容
	edit_by_heading	按标题编辑
语义检索	retrieve_from_local_files	本地文件语义检索
	clear_retrieval_cache	清除检索缓存
	sparse_retrieve	稀疏注意力检索
	hybrid_retrieve	混合检索
	rerank_documents	文档重排序
	generate_embeddings	生成文本向量
	compute_similarity	计算文本相似度

环境变量

在 .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