LuzzyTool

English version also available · 也提供英文版

基于 MCP (Model Context Protocol) 的本地系统工具集，为 AI 助手提供 70+ 工具，涵盖文件操作、Shell 执行、代码搜索、文件监听、压缩解压、HTTP 请求、Git 操作、SQLite 数据库、网络诊断和 Markdown 渲染。

环境要求

• Python 3.10+
• Windows、macOS 或 Linux

快速开始

方式一：pip 安装（推荐）

pip install luzzy-tool

方式二：uvx 直接运行（无需安装）

uvx luzzy-tool

方式三：源码安装

git clone https://github.com/LuzzyMeow/LuzzyTool.git
cd LuzzyTool
pip install -e .

接入 MCP 客户端

方式一：uvx（最简单，推荐）

{
  "mcpServers": {
    "luzzy-tool": {
      "command": "uvx",
      "args": ["luzzy-tool"]
    }
  }
}

方式二：pip 安装后直接运行

{
  "mcpServers": {
    "luzzy-tool": {
      "command": "luzzy-tool"
    }
  }
}

方式三：源码运行

将以下配置添加到你的 MCP 客户端。必须使用绝对路径，将示例路径替换为你的实际项目路径。

{
  "mcpServers": {
    "luzzy-tool": {
      "command": "/home/user/LuzzyTool/venv/bin/python",
      "args": ["-m", "src.server"],
      "env": {
        "LUZZY_TOOL_HOME": "/home/user/LuzzyTool"
      }
    }
  }
}

Windows 用户（例如克隆到 D:\\Projects\\）：

{
  "mcpServers": {
    "luzzy-tool": {
      "command": "D:\\Projects\\LuzzyTool\\venv\\Scripts\\python.exe",
      "args": ["-m", "src.server"],
      "env": {
        "LUZZY_TOOL_HOME": "D:\\Projects\\LuzzyTool"
      }
    }
  }
}

将路径替换为你的实际项目位置。command 必须指向 venv 中的 python（Windows 为 python.exe）， LUZZY_TOOL_HOME 指向项目根目录。

Claude Desktop

参考 MCP 安装指南，使用上述配置。

VS Code / Cursor / Windsurf

将上述配置添加到 MCP 设置中。

配置

在项目根目录创建 .env 文件（参考 .env.example）：

LOG_LEVEL=INFO        # DEBUG | INFO | WARNING | ERROR
CHUNK_SIZE=500        # 检索文本分块大小
CHUNK_OVERLAP=100     # 分块重叠量
DEFAULT_TOP_K=5       # 默认返回结果数

也可通过 MCP 客户端 env 字段注入环境变量。

工具概览

LuzzyTool 提供 70 个 MCP 工具，涵盖 14 个类别。工具名使用英文标识以保证跨客户端兼容性。

类别	工具
文件操作	list_local_directory, read_local_file, file_write, create_directory, move_file, copy_file, delete_file, search_files, get_file_info, rename_file, delete_files, copy_files, backup_file, restore_file, list_backups
Shell 执行	execute_command, execute_batch, execute_command_structured, get_system_info, set_env, get_env, get_command_history, clear_command_history, spawn_process, list_processes, kill_process
文档编辑	get_paragraphs, edit_paragraph, edit_by_heading
结构化编辑	edit_json, edit_yaml, validate_json, validate_yaml
检索	retrieve_from_local_files, clear_retrieval_cache
代码搜索	code_search
文件监听	watch_start, watch_stop, watch_list, watch_events
压缩解压	archive_create, archive_extract, archive_list, archive_test
HTTP	http_request
Git	git_status, git_diff, git_log, git_add, git_commit, git_push, git_pull, git_branch, git_stash, git_remote
数据库	db_list_tables, db_describe_table, db_execute_query, db_execute_update, db_get_table_data
网络诊断	net_ping, net_dns_lookup, net_port_scan, net_check_connectivity, net_reverse_dns
Markdown	md_render_to_html, md_generate_toc, md_extract_links, md_check_links
元工具	list_tools

📁 文件操作（15 个工具）

工具	说明
list_local_directory	列出目录内容，支持递归
read_local_file	读取文本文件（自动检测编码，最大 100MB）
file_write	写入/覆盖文件
create_directory	创建目录（含父目录）
move_file	移动文件或目录
copy_file	复制文件
delete_file	删除文件
search_files	按文件名模式或内容正则搜索
get_file_info	获取文件大小、修改时间、权限、编码
rename_file	重命名文件或目录
delete_files	批量删除（数组接口）
copy_files	批量复制，可保持目录结构
backup_file	创建文件备份
restore_file	从备份恢复文件
list_backups	列出所有备份

💻 Shell 执行（11 个工具）

工具	说明
execute_command	执行单条命令，支持超时、工作目录、系统 Shell 模式
execute_batch	批量执行命令，可配置遇错停止
execute_command_structured	执行命令并自动解析输出
get_system_info	获取系统信息（OS、CPU、内存、磁盘）
set_env	设置会话级环境变量
get_env	获取环境变量
get_command_history	查询命令执行历史
clear_command_history	清空命令历史
spawn_process	启动后台进程
list_processes	列出所有后台进程
kill_process	终止后台进程

🔀 Git 操作（10 个工具）

工具	说明
git_status	仓库状态（分支、暂存、未跟踪）
git_diff	查看差异（暂存区/工作区/文件级统计）
git_log	提交日志（结构化输出）
git_add	暂存文件
git_commit	提交更改
git_push	推送远程（受保护分支防护）
git_pull	拉取更新（支持 rebase）
git_branch	分支管理（list/create/delete/rename）
git_stash	Stash 管理（list/save/pop/apply/drop/clear）
git_remote	远程仓库管理（list/add/remove/get-url）

🗄️ 数据库 — SQLite（5 个工具）

工具	说明
db_list_tables	列出所有表及行数
db_describe_table	查看表结构（列、索引、主键、DDL）
db_execute_query	只读查询（SELECT/PRAGMA/EXPLAIN），参数化
db_execute_update	写入操作（INSERT/UPDATE/DELETE/CREATE/ALTER/DROP）
db_get_table_data	分页获取表数据，支持 WHERE/ORDER BY

🌐 网络诊断（5 个工具）

工具	说明
net_ping	Ping 检测（跨平台，延迟/丢包统计）
net_dns_lookup	DNS 查询（A/AAAA/CNAME/MX/NS/TXT/SOA/SRV）
net_port_scan	TCP 端口扫描（最多 100 端口，服务名识别）
net_check_connectivity	TCP 连通性检测（可达性 + 延迟）
net_reverse_dns	反向 DNS 查询（IP → 域名）

📝 Markdown（4 个工具）

工具	说明
md_render_to_html	Markdown → HTML（支持表格、代码块、脚注等扩展）
md_generate_toc	生成目录（标题列表 + HTML）
md_extract_links	提取链接和图片
md_check_links	检查链接有效性（本地 + 可选 HTTP）

📦 其他类别

压缩解压（4）： archive_create, archive_extract, archive_list, archive_test

文件监听（4）： watch_start, watch_stop, watch_list, watch_events

文档编辑（3）： get_paragraphs, edit_paragraph, edit_by_heading

结构化编辑（4）： edit_json, edit_yaml, validate_json, validate_yaml

检索（2）： retrieve_from_local_files, clear_retrieval_cache

代码搜索（1）： code_search

HTTP（1）： http_request

提示词 (Prompts)

4 个内置提示词模板：

提示词	参数	说明
代码审查	file_path（必填）, language（可选）	代码审查——bug、安全、风格、性能
项目概览	project_dir（必填）	项目结构概览和技术栈分析
Git 提交信息	repo_path（必填）	根据暂存区变更生成 Conventional Commits 提交信息
文件分析	file_path（必填）, focus（可选）	深度分析文件内容，给出建议

资源 (Resources)

3 个资源端点：

URI	名称	类型
project://readme	项目 README	text/markdown
project://tools	工具列表 (JSON)	application/json
project://config	项目配置 (pyproject.toml)	text/plain

安全特性

• 路径穿越防护：拒绝 ../ 越权访问
• 文件读取限制：最大 100MB；超过 1MB 自动限制 500 行/次
• 参数校验：单参数 10MB，总计 50MB
• 压缩解压防护：Zip-slip 路径穿越检测
• Git 保护分支：master/main force push 拦截
• HTTP 安全：默认禁止内网/回环地址；响应体限制 10MB
• 数据库隔离：读写工具分离；查询使用 ?mode=ro；参数化 SQL
• Shell 安全：子进程使用 stdin=DEVNULL 防挂起

详见 SECURITY.md。

项目结构

LuzzyTool/
├── src/
│   ├── server.py                    # MCP 入口，工具注册与调度
│   ├── config.py                    # 全局配置
│   ├── modules/                     # ~15 个工具模块
│   ├── utils/path_security.py       # 路径安全校验
│   └── database/chroma_manager.py   # Chroma 向量数据库
├── scripts/                         # 测试与调试脚本
├── tests/
├── pyproject.toml
├── server.json                      # MCP Registry 元数据
├── lhm.plugin.json                  # LobeHub 市场清单
├── CLAUDE.md
├── README.md                        # 中文说明（本文件）
├── README.en.md                     # English version
├── SECURITY.md
├── CONTRIBUTING.md
├── CHANGELOG.md
└── LICENSE

许可证

MIT — 详见 LICENSE。