luzzy-tool 2.4.0__tar.gz

luzzy_tool-2.4.0/.claude/skills/luzzy-tool-usage.md

@@ -0,0 +1,78 @@
+---
+name: luzzy-tool-usage
+description: Guide for using the LuzzyTool MCP server effectively. Use this skill when the user wants to operate files, run shell commands, search code, watch files, manage archives, send HTTP requests, interact with Git/SQLite, diagnose networks, or render Markdown through MCP tools.
+---
+
+# LuzzyTool Usage Skill
+
+LuzzyTool is a local-system MCP server that exposes ~70 tools across file
+operations, shell execution, structured editing, retrieval, code search,
+file watching, archives, HTTP, Git, SQLite, network diagnostics, and Markdown
+rendering.
+
+## When to use
+
+Trigger this skill whenever the user asks for:
+
+- Reading, writing, moving, copying, deleting, or searching local files
+- Running shell commands or batch operations on Windows / macOS / Linux
+- Editing documents by paragraph/heading or JSON/YAML fields
+- Searching local documents or code with keywords / regex
+- Watching directories for file changes
+- Creating or extracting zip/tar archives
+- Sending HTTP requests (GET/POST/PUT/DELETE with auth, JSON, forms, files)
+- Git operations (status, diff, log, add, commit, push, pull, branch, stash,
+  remote)
+- SQLite database queries and schema inspection
+- Network ping, DNS, port scan, connectivity checks
+- Markdown to HTML rendering, TOC generation, link extraction/validation
+
+## Core workflow
+
+1. Identify the task category from the list above.
+2. Prefer the dedicated tool over generic shell commands when one exists (e.g.
+   use `read_local_file` instead of `cat`, `git_status` instead of raw `git`).
+3. For destructive operations (delete, overwrite, restore), call
+   `backup_file` first unless the user explicitly waived it.
+4. Return structured results; if a tool fails, read its `error` field and
+   either retry with corrected arguments or fall back to a lower-level tool.
+
+## Tool selection cheatsheet
+
+| Task | Recommended tool |
+|------|------------------|
+| Explore directory | `list_local_directory` |
+| Read text file | `read_local_file` |
+| Write/overwrite file | `file_write` |
+| Move/rename file or dir | `move_file` / `rename_file` |
+| Copy file(s) | `copy_file` / `copy_files` |
+| Delete file(s) | `delete_file` / `delete_files` |
+| Search by name/content | `search_files` |
+| Run shell command | `execute_command` / `execute_batch` |
+| Structured shell output | `execute_command_structured` |
+| Edit document paragraph | `get_paragraphs` → `edit_paragraph` |
+| Edit by Markdown heading | `edit_by_heading` |
+| Edit JSON/YAML | `edit_json` / `edit_yaml` |
+| Local keyword search | `retrieve_from_local_files` |
+| Regex code search | `code_search` |
+| Watch files | `watch_start` / `watch_events` / `watch_stop` |
+| Archive | `archive_create` / `archive_extract` / `archive_list` |
+| HTTP | `http_request` |
+| Git | `git_status` / `git_diff` / `git_log` / `git_add` / ... |
+| SQLite | `db_list_tables` / `db_describe_table` / `db_execute_query` |
+| Network | `net_ping` / `net_dns_lookup` / `net_port_scan` |
+| Markdown | `md_render_to_html` / `md_generate_toc` / `md_check_links` |
+
+## Safety reminders
+
+- All paths must be absolute. Path traversal (`..`) is rejected.
+- File reads support up to 100 MB. Files over 1 MB are auto-limited to 500
+  lines per call (max 5000); files over 100 MB must be read in chunks via
+  `offset` / `limit`.
+- Shell commands must be non-interactive. On Windows, set `shell=true` to use
+  built-ins like `echo` / `dir`. Always set `timeout` for long tasks.
+- `http_request` blocks private/loopback addresses by default. Set
+  `allow_private_network=true` only when targeting `127.0.0.1` / `localhost`.
+- Database write/update tools are separated from read-only query tools.
+- Subprocess-based tools (shell, git, network, code search) use
+  `stdin=DEVNULL` to avoid hangs; never pipe interactive input.

luzzy_tool-2.4.0/.env.example

@@ -0,0 +1,50 @@
+# LuzzyTool MCP Server 环境配置
+
+# 项目根目录（默认为当前工作目录）
+PROJECT_ROOT=.
+
+# 服务器配置
+SERVER_HOST=127.0.0.1
+SERVER_PORT=8000
+
+# 日志配置
+LOG_LEVEL=INFO
+LOG_FORMAT=json
+
+# 安全配置
+ALLOWED_EXTENSIONS=.txt,.md,.py,.js,.ts,.json,.yaml,.yml,.xml,.csv,.log,.html,.css,.sh,.bat,.cfg,.ini,.toml,.rst,.tex,.sql,.java,.c,.cpp,.h,.hpp,.go,.rs,.rb,.php,.swift,.kt
+MAX_FILE_SIZE_MB=100
+MAX_ARCHIVE_SIZE_MB=500
+MAX_SEARCH_RESULTS=1000
+
+# Shell 执行配置
+SHELL_TIMEOUT=30
+SHELL_MAX_OUTPUT=1048576
+
+# 数据库配置
+MAX_SQL_LENGTH=10000
+MAX_RESULT_ROWS=1000
+
+# HTTP 客户端配置
+HTTP_TIMEOUT=30
+HTTP_MAX_RESPONSE_SIZE=10485760
+
+# 网络诊断配置
+PING_COUNT=4
+PING_TIMEOUT=10
+DNS_TIMEOUT=10
+TRACEROUTE_MAX_HOPS=30
+
+# 文件监听配置
+WATCH_RECURSIVE=true
+WATCH_IGNORE_PATTERNS=.git,__pycache__,node_modules,.venv,*.pyc,*.pyo
+
+# 代码搜索配置
+SEARCH_CONTEXT_LINES=3
+SEARCH_MAX_FILE_SIZE_MB=10
+
+# 检索引擎配置
+RETRIEVAL_CACHE_MAX_SIZE=100
+RETRIEVAL_CACHE_TTL=3600
+RETRIEVAL_CHUNK_SIZE=500
+RETRIEVAL_CHUNK_OVERLAP=50

luzzy_tool-2.4.0/CLAUDE.md

@@ -0,0 +1,14 @@
+# LuzzyTool
+
+MCP server providing 70+ tools for local system operations — file ops, shell,
+code search, file watching, archives, HTTP, Git, SQLite, network diagnostics,
+and Markdown rendering.
+
+## Skills
+
+- [luzzy-tool-usage](.claude/skills/luzzy-tool-usage.md) — LuzzyTool 工具选择与使用指南
+
+## Links
+
+- [LobeHub MCP](https://lobehub.com/mcp/LuzzyMeow-luzzy-tool)
+- [GitHub Repository](https://github.com/LuzzyMeow/LuzzyTool)

luzzy_tool-2.4.0/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/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md README.en.md LICENSE requirements.txt .env.example server.json CLAUDE.md
+recursive-include skills *.md
+recursive-include .claude *.md
+recursive-include scripts *.py

luzzy_tool-2.4.0/PKG-INFO

@@ -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)。