Zhiwen Assistant MCP

# 优化版文件夹文档生成MCP服务器 - 用户指南 ## 概述 这是一个功能强大的MCP服务器，专为文件夹结构分析和文档生成而设计。它提供了丰富的功能，包括： - 🔍 **智能项目分析**：深度分析项目结构和文件关系 - 📝 **自动文档生成**：生成README文件和思维导图 - 🚀 **批量处理**：支持多项目批量操作 - ⚡ **性能优化**：双重缓存机制，显著提升处理速度 - 🎨 **灵活模板**：基于Jinja2的自定义模板系统 - 🛡️ **安全可靠**：完整的输入验证和安全控制 - 📊 **进度跟踪**：实时显示操作进度和状态 ## 快速开始 ### 1. 安装依赖 ```bash pip install -r requirements.txt ``` ### 2. 初始化配置 首次使用时，运行交互式配置： ```bash python -m src.cli config ``` 这将引导您完成基本配置设置，包括： - 输出目录设置 - 模板选择 - 缓存配置 - 日志级别等 ### 3. 启动服务器 ```bash # 使用默认配置启动 python -m src.cli start # 指定配置文件 python -m src.cli start --config /path/to/config.yaml # 设置交互级别 python -m src.cli start --interaction-level verbose ``` ### 4. 健康检查 验证服务器是否正常运行： ```bash python -m src.cli health-check ``` ## 命令行界面 ### 基本命令 #### 启动服务器 ```bash python -m src.cli start [options] ``` 选项： - `--config PATH`: 指定配置文件路径 - `--interaction-level LEVEL`: 设置交互级别 (silent/basic/normal/verbose/debug) #### 配置管理 ```bash # 交互式配置 python -m src.cli config # 显示当前配置 python -m src.cli config --show # 重置为默认配置 python -m src.cli config --reset # 验证配置 python -m src.cli config --validate ``` #### 健康检查 ```bash python -m src.cli health-check ``` ### 高级命令 #### 生成文档 ```bash python -m src.cli generate <目录> [选项] ``` 选项： - `--output PATH`: 指定输出目录 - `--template NAME`: 使用指定模板 - `--format FORMAT`: 生成格式 (readme/mindmap/both) 示例： ```bash # 生成完整文档 python -m src.cli generate ./my-project --format both # 只生成README python -m src.cli generate ./my-project --format readme # 指定输出目录 python -m src.cli generate ./my-project --output ./docs ``` #### 分析项目 ```bash python -m src.cli analyze <目录> [选项] ``` 选项： - `--depth NUM`: 分析深度 (默认: 10) - `--export PATH`: 导出分析结果 示例： ```bash # 分析项目结构 python -m src.cli analyze ./my-project # 深度分析并导出 python -m src.cli analyze ./my-project --depth 20 --export ./analysis.json ``` ## 配置选项 ### 基本配置 | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | `output_dir` | 目录 | "docs" | 生成的文档保存目录 | | `template_dir` | 目录 | "config/templates" | 模板文件目录 | | `cache_enabled` | 布尔 | true | 是否启用缓存 | | `cache_dir` | 目录 | ".cache" | 缓存文件保存目录 | | `log_level` | 选择 | "INFO" | 日志级别 | | `interaction_level` | 选择 | "normal" | 用户交互程度 | ### 高级配置 | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | `auto_confirm` | 布尔 | false | 自动确认所有提示 | | `include_hidden` | 布尔 | false | 处理隐藏文件和目录 | | `max_depth` | 整数 | 10 | 最大递归深度 | | `file_extensions` | 列表 | [] | 文件扩展名过滤 | | `exclude_patterns` | 列表 | ["node_modules", ".git"] | 排除模式 | ### 配置文件示例 ```yaml # 用户配置文件示例 output_dir: "docs" template_dir: "config/templates" cache_enabled: true cache_dir: ".cache" log_level: "INFO" interaction_level: "normal" auto_confirm: false include_hidden: false max_depth: 10 file_extensions: [".py", ".js", ".md", ".json"] exclude_patterns: - "node_modules" - ".git" - "__pycache__" - "*.pyc" ``` ## 交互级别 不同级别提供不同详细程度的用户反馈： - **silent**: 静默模式，不输出任何信息 - **basic**: 只显示关键结果和错误信息 - **normal**: 显示进度和基本信息（默认） - **verbose**: 显示详细操作信息 - **debug**: 显示所有详细信息，包括调试信息 ## 模板系统 ### 内置模板 服务器提供了以下内置模板： 1. **README简单模板** (`readme_simple.md.j2`) - 基本项目结构 - 文件列表 - 简单说明 2. **README详细模板** (`readme_detailed.md.j2`) - 详细项目分析 - 模块说明 - 依赖关系 3. **思维导图模板** (`mindmap.mm.j2`) - 层级结构可视化 - Mermaid格式输出 ### 自定义模板 您可以创建自己的Jinja2模板： 1. 在模板目录中创建`.j2`文件 2. 使用以下变量： - `{{ project_name }}`: 项目名称 - `{{ project_path }}`: 项目路径 - `{{ analysis }}`: 分析结果 - `{{ file_tree }}`: 文件树结构 - `{{ modules }}`: 模块信息 模板示例： ```jinja2 # {{ project_name }} ## 项目概述 路径: {{ project_path }} 生成时间: {{ timestamp }} ## 文件结构 {% for file in file_tree %} {{ file.indentation }}{{ file.name }}{% if file.is_dir %}/{% endif %} {% endfor %} ## 模块信息 {% for module in modules %} ### {{ module.name }} {% if module.description %} {{ module.description }} {% endif %} {% endfor %} ``` ## 性能优化 ### 缓存机制 服务器使用双重缓存系统： 1. **内存缓存**: 快速访问最近使用的数据 2. **磁盘缓存**: 持久化缓存，重启后仍然有效 缓存配置： ```yaml cache: memory_size: 100 # 内存缓存大小(MB) disk_enabled: true # 启用磁盘缓存 disk_dir: ".cache" # 磁盘缓存目录 disk_max_size: 500 # 磁盘缓存大小(MB) ttl: 3600 # 缓存过期时间(秒) ``` ### 性能建议 1. **合理设置深度**: `max_depth`设置过大会影响性能 2. **使用排除模式**: 排除不需要的目录(如node_modules) 3. **启用缓存**: 对重复操作有显著性能提升 4. **限制文件类型**: 只处理需要的文件类型 ## 故障排除 ### 常见问题 #### 1. 配置文件错误 ```bash # 验证配置文件 python -m src.cli config --validate # 重置配置 python -m src.cli config --reset ``` #### 2. 权限问题 确保对以下目录有读写权限： - 输出目录 (`output_dir`) - 缓存目录 (`cache_dir`) - 模板目录 (`template_dir`) #### 3. 性能问题 - 检查是否排除了大目录(如node_modules) - 减少分析深度 - 清理缓存：删除`.cache`目录 #### 4. 模板错误 - 检查Jinja2语法 - 验证变量名是否正确 - 查看错误日志 ### 调试模式 启用调试模式获取详细信息： ```bash python -m src.cli start --interaction-level debug ``` 这会显示： - 详细的操作步骤 - 错误堆栈信息 - 性能统计 - 缓存状态 ## 最佳实践 ### 1. 项目组织 - 保持项目结构清晰 - 使用有意义的文件和目录名 - 添加必要的文档和注释 ### 2. 配置管理 - 为不同项目使用不同配置 - 定期备份配置文件 - 使用版本控制管理配置 ### 3. 性能优化 - 根据项目大小调整配置参数 - 定期清理缓存 - 监控性能指标 ### 4. 安全考虑 - 不要处理敏感文件 - 使用排除模式避免处理临时文件 - 定期检查生成的文档内容 ## 高级用法 ### 1. 批量处理 ```python # 批量处理多个项目 projects = [ {"path": "./project1", "output": "./docs1"}, {"path": "./project2", "output": "./docs2"} ] for project in projects: # 处理每个项目 pass ``` ### 2. 自定义分析器 扩展分析功能： ```python # 自定义文件分析器 def custom_analyzer(file_path): # 自定义分析逻辑 return analysis_result ``` ### 3. 插件系统 服务器支持插件扩展，可以： - 添加新的分析器 - 创建自定义模板 - 集成外部工具 ## API参考 ### MCP工具 服务器提供以下MCP工具： 1. `generate_readme`: 生成README文件 2. `generate_mindmap`: 生成思维导图 3. `analyze_project`: 分析项目结构 4. `batch_generate`: 批量生成文档 5. `list_templates`: 列出可用模板 详细API文档请参考[API参考](api_reference.md)。 ## 更新日志 ### v2.0.0 (当前版本) - ✨ 新增用户交互系统 - ⚡ 性能优化和缓存机制 - 🎨 灵活的模板系统 - 🛡️ 增强的安全控制 - 📊 实时进度跟踪 - 🧪 完整的测试覆盖 ### v1.0.0 - 🎉 初始版本 - 📝 基本文档生成功能 - 🔍 项目结构分析 - 💾 基础缓存支持 ## 社区和支持 - 📖 [完整文档](https://docs.example.com) - 🐛 [问题反馈](https://github.com/example/folder-docs-mcp/issues) - 💬 [讨论区](https://github.com/example/folder-docs-mcp/discussions) - 📧 [邮件支持](mailto:support@example.com) ## 许可证 本项目采用MIT许可证，详情请查看[LICENSE](../LICENSE)文件。