luzzy-tool 2.4.0__py3-none-any.whl

luzzy_tool-2.4.0.dist-info/METADATA

@@ -0,0 +1,345 @@
+Metadata-Version: 2.4
+Name: luzzy-tool
+Version: 2.4.0
+Summary: 基于MCP协议的本地系统工具集，为AI助手提供文件操作、Shell执行、代码搜索、文件监听、压缩解压、HTTP请求、Git操作、数据库操作、网络诊断、Markdown渲染和结构化数据处理
+Author-email: LuzzyMeow <2170206661@qq.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/LuzzyMeow/LuzzyTool
+Project-URL: Repository, https://github.com/LuzzyMeow/LuzzyTool
+Project-URL: Issues, https://github.com/LuzzyMeow/LuzzyTool/issues
+Project-URL: MCP Server, https://lobehub.com/mcp/LuzzyMeow-luzzy-tool
+Keywords: mcp,mcp-server,tools,file-management,shell,git,database,network,markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: structlog>=23.0.0
+Requires-Dist: tqdm>=4.65.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: typing-extensions>=4.5.0
+Requires-Dist: watchdog>=3.0.0
+Requires-Dist: markdown>=3.4.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: export
+Requires-Dist: python-docx>=0.8.11; extra == "export"
+Requires-Dist: ebooklib>=0.18; extra == "export"
+Requires-Dist: markdown>=3.4.0; extra == "export"
+Dynamic: license-file
+
+# LuzzyTool
+
+<div align="center">
+
+[![MCP Badge](https://lobehub.com/badge/mcp/LuzzyMeow-luzzy-tool)](https://lobehub.com/mcp/LuzzyMeow-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)](#工具概览)
+[![Skills](https://img.shields.io/badge/skills-1-blue.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
+
+## 快速开始
+
+```bash
+git clone https://github.com/LuzzyMeow/LuzzyTool.git
+cd LuzzyTool
+pip install -e .
+```
+
+## 接入 MCP 客户端
+
+将以下配置添加到你的 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 |
+
+## 技能 (Skills)
+
+LuzzyTool 遵循 [Anthropic Skills 规范](https://docs.anthropic.com/en/docs/claude/skills)。
+技能文件位于 [`.claude/skills/`](.claude/skills/)：
+
+| 技能 | 文件 | 说明 |
+|------|------|------|
+| `luzzy-tool-usage` | [`.claude/skills/luzzy-tool-usage.md`](.claude/skills/luzzy-tool-usage.md) | LuzzyTool 工具选择与使用指南 |
+
+## 安全特性
+
+- **路径穿越防护**：拒绝 `../` 越权访问
+- **文件读取限制**：最大 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 向量数据库
+├── .claude/skills/                  # Claude 技能定义
+├── skills/                          # Anthropic Skills 格式
+├── scripts/                         # 测试与调试脚本
+├── tests/
+├── pyproject.toml
+├── server.json                      # MCP Registry 元数据
+├── CLAUDE.md
+├── README.md                        # 中文说明（本文件）
+├── README.en.md                     # English version
+├── SECURITY.md
+├── CONTRIBUTING.md
+├── CHANGELOG.md
+└── LICENSE
+```
+
+## 许可证
+
+MIT — 详见 [LICENSE](LICENSE)。

luzzy_tool-2.4.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+luzzy_tool-2.4.0.dist-info/licenses/LICENSE,sha256=tPemUCTFl1v30pfYkJJncW6zmiUkctZ28MbCg6Xhz_4,1076
+scripts/test_all_tools_boundaries.py,sha256=aLiNUeYIGg7u202wRRyEpcSPnKLNvcM0fJM2rdn1fNo,23557
+scripts/test_file_watcher.py,sha256=SE0xj8Auw4FvTKpVOjSsz0IzgWDTtQTtW-yFyp1pmfY,1124
+scripts/test_mcp_capabilities.py,sha256=53XmvdKDN8Xnr-zRd2lkpbMMvmLENVoYHaSA95D_u2M,1592
+scripts/test_mcp_startup_time.py,sha256=fpMq33A93A4-8MsvSkyp5R8HoRpn2vCGm2cYH_htdC0,1427
+scripts/test_read_upgrade.py,sha256=bHIL_d-nxTjYdGA7FmbcbUUaMemMmmlq_IRgkV0oN9k,3631
+src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/config.py,sha256=WNda5wlrQh2aabaiQcpf2n-aC0WJHV7Keh4QXX4PNBg,2770
+src/server.py,sha256=5977u7hcZgMy5o1HRfM6D_95MbF4hXyDHKv71RSPjkE,117250
+src/database/__init__.py,sha256=aXQJNVVgR0JJkYeniblXGnDoCNQ0scqQDW5ddT7xnjA,469
+src/database/chroma_manager.py,sha256=tLjsx8OMsFk3mVGf4mZOXSChEyTvvt1gmsNMyh0b_hw,13808
+src/modules/__init__.py,sha256=xrX-LosDAnbKyOpRIhTe-dGMrs7xawpRT7fDs7UhQLs,557
+src/modules/archive_manager.py,sha256=vYSE2k68-aUnViFhIIB0UvdMaMsByHdu1KquXWubnMc,16566
+src/modules/code_searcher.py,sha256=psr3nbcUkkKsPZ9_smwWrmdQuOaR_QRtI5IWm0JbhMc,12337
+src/modules/database_manager.py,sha256=pI0uyMe2XajUTeaXy08xyvUopqtO3wuiVPXLPN5lLyg,14963
+src/modules/document_editor.py,sha256=B2fgKgyATCI5WgcZyx3hJAzjWI8IVvQjjuKYba07lZI,18460
+src/modules/enhanced_file_manager.py,sha256=2FSvjE6ma8WdUQekU6du89fcsQHahnBjo9uDKKpGZt8,18952
+src/modules/enhanced_shell_executor.py,sha256=-xA6-BC9Byfk7wfXHbWGZhC7mQKFaXLnZ6sG-JrFLDI,18517
+src/modules/file_manager.py,sha256=m4Wd0y4T8MVFX6CkFHpth-kK5suragMH-u21xG59G6o,23091
+src/modules/file_watcher.py,sha256=NnY9V_-ypb8rWmMLSz6g3a-I7q2FMKTBwxFvQsUXzW0,10809
+src/modules/git_manager.py,sha256=eYYWCfmU7nAkhHyYttsogqPfg8ei_jkz4o5Qp43l_yo,17744
+src/modules/http_client.py,sha256=1geSTFLMV8eJ6SezvTGizT7Sl7W2b_bX-jqIu4aV5Xs,13899
+src/modules/local_retrieval_engine.py,sha256=4nxIKrU9ORPBYoWYkEaxp9n90tYYPTMCCqBpqics7Pk,12983
+src/modules/markdown_renderer.py,sha256=8miUaw7_7fdNTClWlUeyBTqYcNx37PAeJGohgYe5THs,15917
+src/modules/network_diagnostics.py,sha256=4zCB5GDXyveeNAyMeMZ9-BccVzhuwERIqISF9S0x0U8,15389
+src/modules/session_manager.py,sha256=lHhV3XI1mYtqldYIqqGa1lKWrJiFEzVV2vYQViq03FQ,16196
+src/modules/shell_executor.py,sha256=_CDmF4jJqjkhID3lnUhGTI_TPWfKDZfw5uXPQHQeIiY,18968
+src/modules/structured_editor.py,sha256=nBj823KkWAzsWCaK9QndGVFMUkH7uKEFeQfFLG-VA3M,13732
+src/modules/unified_file_writer.py,sha256=WM8-Mp0SeFFlFk96KffBIDTfy2RjRJd-_Yw9YsUU6iw,18393
+src/utils/__init__.py,sha256=qPxbB2ZPguNjhxI1k9aU7zve5Ih71XNwj4PkyBczgtI,1120
+src/utils/path_security.py,sha256=Obl_Rf358ApSpmPZOibqyhy_kIUY4AObq2tSVRqAOPU,11254
+src/utils/text_chunker.py,sha256=4xKFJUowMlofvfLE9wi9P85JQBcJwIcSLLCBURqO8Fk,12428
+luzzy_tool-2.4.0.dist-info/METADATA,sha256=nBkfaaPjELp6lvooMUylYafi1Xu7NpTuqSS2rAdyOpA,13578
+luzzy_tool-2.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+luzzy_tool-2.4.0.dist-info/entry_points.txt,sha256=L24UW5_4kRTVbVX3hgZUl-2kW1WN7HWNrltpzD2wRlc,83
+luzzy_tool-2.4.0.dist-info/top_level.txt,sha256=2u1B708VEAisYx1t_BY-Ya_-RVnGzeibiEH429s02AM,12
+luzzy_tool-2.4.0.dist-info/RECORD,,

luzzy_tool-2.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

luzzy_tool-2.4.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+luzzy-tool = src.server:main
+luzzy-tool-server = src.server:main

luzzy_tool-2.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 LuzzyTool Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

luzzy_tool-2.4.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+scripts
+src