Zhiwen Assistant MCP

# 快速入门指南 欢迎使用优化版文件夹文档生成MCP服务器！本指南将在5分钟内帮助您快速上手。 ## 🚀 5分钟快速开始 ### 第1步：安装依赖 (1分钟) ```bash # 进入项目目录 cd 优化版本/optimized_folder_docs_mcp # 安装依赖 pip install -r requirements.txt ``` ### 第2步：初始化配置 (2分钟) 运行交互式配置命令： ```bash python -m src.cli config ``` 系统会引导您完成以下设置： 1. **输出目录**: `docs` (直接按Enter使用默认值) 2. **模板目录**: `config/templates` (直接按Enter) 3. **启用缓存**: `yes` (建议启用) 4. **交互级别**: 选择 `normal` (默认选项) 5. **日志级别**: 选择 `INFO` (默认选项) 配置完成后，您的设置会保存到 `config/user_config.yaml` 文件中。 ### 第3步：启动服务器 (1分钟) ```bash python -m src.cli start ``` 您将看到类似以下的输出： ``` ℹ️ MCP服务器启动 ✅ 操作完成: 服务器初始化完成 🚀 FastMCP服务器正在运行... ``` ### 第4步：测试功能 (1分钟) 服务器启动后，您可以通过MCP客户端使用以下功能： 1. **生成README文档**: ``` generate_readme("./your-project-folder") ``` 2. **生成思维导图**: ``` generate_mindmap("./your-project-folder", "output/mindmap.md") ``` 3. **分析项目结构**: ``` analyze_project("./your-project-folder", 10) ``` ## 🎯 常用场景 ### 场景1：为新项目生成文档 假设您有一个Python项目 `my-app`，需要生成完整的项目文档： ```bash # 生成README和思维导图 python -m src.cli generate ./my-app --format both # 只生成README python -m src.cli generate ./my-app --format readme ``` ### 场景2：批量处理多个项目 ```python # 在MCP客户端中使用 projects = [ "./project1", "./project2", "./project3" ] for project in projects: generate_readme(project) ``` ### 场景3：自定义文档模板 1. 创建自定义模板 `config/templates/my_template.md.j2`: ```jinja2 # {{ project_name }} > 自动生成于: {{ timestamp }} ## 项目概览 - 路径: {{ project_path }} - 文件总数: {{ file_count }} - 目录总数: {{ dir_count }} ## 核心模块 {% for module in modules[:5] %} - **{{ module.name }}**: {{ module.description }} {% endfor %} ## 文件结构 ``` {{ file_tree }} ``` 2. 使用自定义模板： ```bash python -m src.cli generate ./my-project --template my_template ``` ## ⚙️ 高级配置 ### 性能优化设置 编辑 `config/user_config.yaml`: ```yaml # 提高处理大项目的性能 max_depth: 15 exclude_patterns: - "node_modules" - ".git" - "__pycache__" - "*.pyc" - ".vscode" # 增大缓存 cache_enabled: true memory_size: 200 disk_max_size: 1000 ``` ### 文件类型过滤 只处理特定类型的文件： ```yaml file_extensions: [".py", ".js", ".md", ".json", ".yaml"] ``` ### 自动化设置 ```yaml # 减少交互提示，适合自动化 auto_confirm: true interaction_level: "basic" ``` ## 🔧 常见问题解决 ### 问题1：权限错误 **症状**: 提示"权限被拒绝" **解决方案**: ```bash # 检查目录权限 ls -la ./your-project # 修改权限 chmod -R 755 ./your-project ``` ### 问题2：内存不足 **症状**: 处理大项目时内存溢出 **解决方案**: ```yaml # 减少缓存大小 memory_size: 50 # 限制分析深度 max_depth: 5 # 排除大目录 exclude_patterns: - "node_modules" - "dist" - "build" ``` ### 问题3：生成速度慢 **症状**: 文档生成很慢 **解决方案**: ```yaml # 启用缓存 cache_enabled: true # 减少处理文件 file_extensions: [".py", ".js", ".md"] # 降低详细级别 interaction_level: "basic" ``` ## 🎨 自定义技巧 ### 1. 创建项目专用配置 为不同类型项目创建不同配置： ```bash # Python项目配置 python -m src.cli config --config python_config.yaml # JavaScript项目配置 python -m src.cli config --config js_config.yaml ``` ### 2. 使用环境变量 ```bash # 设置输出目录 export OUTPUT_DIR="./documentation" # 设置日志级别 export LOG_LEVEL="DEBUG" # 启动服务器 python -m src.cli start ``` ### 3. 集成到CI/CD GitHub Actions示例： ```yaml name: Generate Docs on: [push] jobs: generate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Setup Python uses: actions/setup-python@v2 with: python-version: '3.9' - name: Install dependencies run: pip install -r requirements.txt - name: Generate docs run: python -m src.cli generate . --format both - name: Upload docs uses: actions/upload-artifact@v2 with: name: docs path: docs/ ``` ## 📊 监控和调试 ### 查看操作历史 ```python # 在MCP客户端中 from services import get_operation_summary summary = get_operation_summary() print(f"总操作数: {summary['total_operations']}") print(f"成功率: {summary['success_rate']:.1f}%") ``` ### 启用调试模式 ```bash python -m src.cli start --interaction-level debug ``` ### 性能分析 ```bash # 查看详细性能信息 python -m src.cli health-check --interaction-level verbose ``` ## 🎯 进阶学习 完成快速入门后，建议继续学习： 1. **[完整用户指南](user_guide.md)** - 了解所有功能详情 2. **[API参考](api_reference.md)** - 掌握API用法 3. **[模板开发指南](template_guide.md)** - 创建自定义模板 4. **[最佳实践](best_practices.md)** - 学习使用技巧 ## 🆘 获取帮助 如果遇到问题，可以： 1. **查看文档**: 阅读[完整用户指南](user_guide.md) 2. **检查配置**: 运行 `python -m src.cli config --validate` 3. **健康检查**: 运行 `python -m src.cli health-check` 4. **调试模式**: 使用 `--interaction-level debug` 参数 ## 🎉 恭喜！ 您已经成功掌握了优化版文件夹文档生成MCP服务器的基本用法！ 接下来可以： - 尝试为您的实际项目生成文档 - 探索自定义模板功能 - 集成到您的工作流程中 祝您使用愉快！🚀