Zhiwen Assistant MCP

# 📚 文件夹文档生成MCP - 用户手册 ## 🎯 功能概述 这是一个专门为中文项目设计的MCP服务器，能够： - 🇨🇳 为项目文件夹自动生成中文README文档 - 📊 创建项目结构思维导图 - 🔄 支持批量更新和增量处理 - ⚙️ 可自定义排除目录和模板 ## 🚀 快速开始 ### 第一步：运行安装程序 ```bash python install.py ``` ### 第二步：配置MCP客户端 将生成的 `mcp_config.json` 配置添加到你的MCP客户端中。 ### 第三步：开始使用 重启MCP客户端，即可使用所有功能！ ## 🛠️ 功能详解 ### 1. 生成README文件 (`generate_readme_files`) **功能**：为项目中的每个主要文件夹生成中文README.md文件 **参数说明**： - `root_dir` (必需)：项目根目录路径 - `exclude_dirs` (可选)：排除的目录列表，默认排除 `.git`, `.trae` 等 - `force_update` (可选)：是否强制更新现有README.md文件，默认为 `false` **使用示例**： ```json { "root_dir": "/path/to/your/project", "exclude_dirs": ["node_modules", "build", "dist"], "force_update": true } ``` ### 2. 生成思维导图 (`generate_mindmap`) **功能**：生成项目文件夹结构的思维导图 **参数说明**： - `root_dir` (必需)：项目根目录路径 - `output_file` (可选)：思维导图输出文件路径，默认为 `folder_structure_mindmap.md` - `exclude_dirs` (可选)：排除的目录列表 **使用示例**： ```json { "root_dir": "/path/to/your/project", "output_file": "项目结构图.md", "exclude_dirs": ["temp", "cache"] } ``` ### 3. 更新文档 (`update_documentation`) **功能**：批量更新项目中的README.md文件和思维导图 **参数说明**： - `root_dir` (必需)：项目根目录路径 - `exclude_dirs` (可选)：排除的目录列表 - `update_mindmap` (可选)：是否更新思维导图，默认为 `true` **使用示例**： ```json { "root_dir": "/path/to/your/project", "exclude_dirs": ["logs", "backup"], "update_mindmap": true } ``` ### 4. 获取文件夹结构 (`get_folder_structure`) **功能**：获取项目的文件夹结构树 **参数说明**： - `root_dir` (必需)：项目根目录路径 - `exclude_dirs` (可选)：排除的目录列表 **使用示例**： ```json { "root_dir": "/path/to/your/project", "exclude_dirs": [".git", "node_modules"] } ``` ## 📋 常见问题解答 ### Q: 如何指定要处理的文件夹？ A: 在调用工具时，通过 `root_dir` 参数指定项目根目录路径。支持绝对路径和相对路径。 ### Q: 可以自定义排除的文件夹吗？ A: 可以！在调用任何工具时，都可以通过 `exclude_dirs` 参数指定要排除的文件夹列表。系统默认会排除 `.git`, `.trae`, `.claude-plugin` 等目录。 ### Q: 如何强制更新现有README文件？ A: 使用 `generate_readme_files` 工具时，将 `force_update` 参数设置为 `true` 即可覆盖现有的README文件。 ### Q: 生成的思维导图支持什么格式？ A: 目前支持Markdown格式的Mermaid思维导图，可以在支持Mermaid的Markdown查看器中直接查看。 ### Q: 如何自定义文件夹的描述？ A: 你可以直接修改 `folder_documentation_mcp.py` 文件中的 `folder_descriptions` 字典，添加你自己的文件夹描述映射。 ### Q: 支持多语言吗？ A: 当前版本主要针对中文项目优化，但你可以通过修改模板文件来支持其他语言。 ### Q: 如何处理特殊字符的文件夹名？ A: 系统会自动处理大部分特殊字符，但如果遇到问题，请检查文件夹命名是否符合系统规范。 ## 🎨 高级用法 ### 自定义README模板 你可以修改 `generate_readme_content` 函数来自定义README的模板和格式。 ### 批量处理多个项目 编写一个简单的脚本，循环调用MCP工具来处理多个项目： ```python projects = [ "/path/to/project1", "/path/to/project2", "/path/to/project3" ] for project in projects: # 调用MCP工具处理每个项目 result = mcp_client.call_tool("generate_readme_files", { "root_dir": project, "force_update": True }) print(f"处理 {project}: {result}") ``` ### 定时自动更新 结合系统的定时任务功能，可以定期自动更新项目文档： ```bash # 每周一上午9点自动更新文档 0 9 * * 1 cd /path/to/project && python -c "import mcp_client; mcp_client.call_tool('update_documentation', {'root_dir': '.'})" ``` ## 🛠️ 故障排除 ### 问题1：MCP服务器无法启动 **解决方案**： 1. 检查Python版本是否为3.8+ 2. 确保已安装所有依赖：`pip install mcp pydantic` 3. 查看错误日志，检查文件路径是否正确 ### 问题2：生成的文档格式不正确 **解决方案**： 1. 检查项目文件夹权限 2. 确认文件夹名不包含特殊字符 3. 检查磁盘空间是否充足 ### 问题3：MCP客户端无法识别服务器 **解决方案**： 1. 检查配置文件格式是否正确 2. 确认文件路径使用正确的分隔符 3. 重启MCP客户端 ### 问题4：处理大型项目时速度慢 **解决方案**： 1. 使用 `exclude_dirs` 排除不必要的目录 2. 分批处理子目录 3. 检查系统资源使用情况 ## 📞 技术支持 如果遇到无法解决的问题： 1. **查看日志**：检查MCP客户端的错误日志 2. **检查环境**：确认Python环境和依赖包版本 3. **社区支持**：在相关技术社区寻求帮助 4. **联系开发者**：通过GitHub Issues或邮件联系 ## 🔄 版本更新 - **v1.0.0**：初始版本，支持基本的文档生成功能 - **v1.1.0**（计划中）：增加模板自定义功能 - **v1.2.0**（计划中）：增加多语言支持 ## 📄 许可证 本项目采用MIT许可证，详见LICENSE文件。 --- *最后更新：2025年12月17日*