# LuzzyTool

<div align="center">

[![PyPI](https://img.shields.io/pypi/v/luzzy-tool.svg)](https://pypi.org/project/luzzy-tool/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/luzzy-tool.svg)](https://pypi.org/project/luzzy-tool/)
[![MCP Badge](https://lobehub.com/badge/mcp/your-org-luzzy-tool)](https://lobehub.com/mcp/your-org-luzzy-tool)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-1.0+-purple.svg)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-70-orange.svg)](#工具概览)

</div>

> [English version](README.en.md) also available · 也提供[英文版](README.en.md)

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

## 环境要求

- Python 3.10+
- Windows、macOS 或 Linux

## 快速开始

### 方式一：pip 安装（推荐）

```bash
pip install luzzy-tool
```

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

```bash
uvx luzzy-tool
```

### 方式三：源码安装

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

## 接入 MCP 客户端

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

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

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

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

### 方式三：源码运行

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

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

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

```json
{
  "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 安装指南](https://modelcontextprotocol.io/quickstart/user)，使用上述配置。

### VS Code / Cursor / Windsurf

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

## 配置

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

```ini
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` |

<details>
<summary>📁 文件操作（15 个工具）</summary>

| 工具 | 说明 |
|------|------|
| `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` | 列出所有备份 |

</details>

<details>
<summary>💻 Shell 执行（11 个工具）</summary>

| 工具 | 说明 |
|------|------|
| `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` | 终止后台进程 |

</details>

<details>
<summary>🔀 Git 操作（10 个工具）</summary>

| 工具 | 说明 |
|------|------|
| `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） |

</details>

<details>
<summary>🗄️ 数据库 — SQLite（5 个工具）</summary>

| 工具 | 说明 |
|------|------|
| `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 |

</details>

<details>
<summary>🌐 网络诊断（5 个工具）</summary>

| 工具 | 说明 |
|------|------|
| `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 → 域名） |

</details>

<details>
<summary>📝 Markdown（4 个工具）</summary>

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

</details>

<details>
<summary>📦 其他类别</summary>

**压缩解压（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`

</details>

## 提示词 (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](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](LICENSE)。