Zhiwen Assistant MCP

# 智文助手增强版部署与使用指南 ## 概述 智文助手增强版是基于原始文件夹文档生成器的升级版本，集成了安全验证、配置管理、性能监控等优化特性。 ### 主要特性 - 🔒 **安全验证**: 路径验证、敏感信息检测、文件类型验证 - ⚙️ **配置管理**: 支持YAML/JSON配置文件，配置验证和默认值处理 - 🚀 **性能优化**: 内存缓存、磁盘缓存、异步处理 - 📊 **监控统计**: 服务器性能统计、缓存状态监控 - 🛡️ **错误处理**: 完善的异常处理和日志记录 - 📝 **代码质量**: 遵循PEP 8规范，完整的类型注解和文档 ## 文件结构 ``` 我的MCP服务器/ ├── enhanced_folder_docs_mcp.py # 增强版MCP服务器主文件 ├── mcp_config.yaml # 主配置文件 ├── security/ # 安全验证模块 │ └── __init__.py ├── config/ # 配置管理模块 │ ├── __init__.py │ └── default.yaml # 默认配置文件 ├── cache/ # 缓存目录 ├── logs/ # 日志目录 ├── test_enhanced_modules.py # 模块测试文件 ├── code_quality_check.py # 代码质量检查工具 └── 增强版MCP服务器部署指南.md # 本文件 ``` ## 安装依赖 ```bash # 创建虚拟环境（推荐） python -m venv mcp-env source mcp-env/bin/activate # Linux/Mac # 或 mcp-env\Scripts\activate # Windows # 安装依赖 pip install mcp fastmcp pydantic pyyaml ``` ## 配置说明 ### 1. 主配置文件 (mcp_config.yaml) ```yaml # 服务器配置 server: host: localhost port: 8080 transport: stdio # stdio 或 streamable-http log_level: INFO request_timeout: 30 max_concurrent_requests: 10 # 安全配置 security: enable_path_validation: true enable_content_filtering: true max_file_size: 52428800 # 50MB allowed_extensions: - .py - .md - .txt - .json - .yaml # ... 更多扩展名 # 性能配置 performance: cache_ttl: 3600 # 1小时 cache_memory_size: 1000 cache_disk_enabled: true cache_disk_dir: cache parallel_workers: 4 # 选项配置 options: exclude_dirs: - .git - .trae - __pycache__ - node_modules force_update: false output_file: folder_structure_mindmap.md ``` ### 2. 安全配置 - **路径验证**: 防止路径遍历攻击，限制危险系统目录访问 - **敏感信息检测**: 自动检测API密钥、密码、邮箱等敏感信息 - **文件类型验证**: 只允许处理指定类型的文件 - **文件大小限制**: 防止处理过大的文件 ### 3. 性能配置 - **内存缓存**: 缓存处理结果，提高重复操作性能 - **磁盘缓存**: 持久化缓存，重启后仍然有效 - **并行处理**: 支持多线程处理，提高大目录处理速度 - **超时控制**: 防止长时间运行的请求 ## 使用方法 ### 1. 启动服务器 ```bash # 使用stdio传输协议（默认） python enhanced_folder_docs_mcp.py # 使用HTTP传输协议 # 需要在配置文件中设置 transport: streamable-http python enhanced_folder_docs_mcp.py ``` ### 2. 可用工具 #### 安全检查工具 ```python await security_check({ "path": "要检查的路径", "base_dir": "基础目录" }) ``` #### 配置管理工具 ```python # 获取配置 await config_manager_tool({ "action": "get", "key": "server.port" # 可选 }) # 设置配置 await config_manager_tool({ "action": "set", "key": "server.port", "value": "8080" }) # 验证配置 await config_manager_tool({ "action": "validate" }) ``` #### 性能统计工具 ```python await performance_stats() ``` #### README生成工具 ```python await generate_readme_files({ "root_dir": "/path/to/project", "exclude_dirs": [".git", "__pycache__"], "force_update": false }) ``` #### 思维导图生成工具 ```python await generate_mindmap({ "root_dir": "/path/to/project", "output_file": "folder_structure_mindmap.md", "exclude_dirs": [".git", "__pycache__"] }) ``` #### 文档更新工具 ```python await update_documentation({ "root_dir": "/path/to/project", "exclude_dirs": [".git", "__pycache__"], "update_mindmap": true }) ``` ### 3. 集成示例 #### 在Claude Desktop中配置 编辑 `claude_desktop_config.json`: ```json { "mcpServers": { "enhanced-folder-docs": { "command": "python", "args": ["/path/to/enhanced_folder_docs_mcp.py"], "env": { "MCP_CONFIG_FILE": "/path/to/mcp_config.yaml" } } } } ``` ## 测试 ### 1. 运行模块测试 ```bash # 测试所有模块 python test_enhanced_modules.py # 查看详细测试结果 python -m unittest test_enhanced_modules.py -v ``` ### 2. 代码质量检查 ```bash # 检查主文件 python code_quality_check.py enhanced_folder_docs_mcp.py # 检查所有Python文件 python code_quality_check.py . # 检查特定模块 python code_quality_check.py . --pattern "security/*.py" python code_quality_check.py . --pattern "config/*.py" ``` ## 故障排除 ### 1. 常见问题 #### 模块导入失败 ``` 错误: 缺少必要的MCP依赖 解决: pip install mcp fastmcp pydantic pyyaml ``` #### 配置文件错误 ``` 错误: 配置验证失败 解决: 检查配置文件格式，运行配置验证工具 ``` #### 路径安全验证失败 ``` 错误: 路径验证失败 解决: 检查路径是否包含危险字符，更新allowed_paths配置 ``` #### 权限问题 ``` 错误: 无权限访问目录 解决: 确保有读写权限，检查文件权限设置 ``` ### 2. 调试方法 #### 启用详细日志 ```yaml logging: level: DEBUG file: logs/mcp_server.log ``` #### 检查配置 ```python await config_manager_tool({"action": "validate"}) await config_manager_tool({"action": "get"}) ``` #### 监控性能 ```python await performance_stats() ``` ## 性能优化建议 ### 1. 缓存配置 - 根据内存大小调整 `cache_memory_size` - 根据磁盘空间调整 `cache_disk_max_size` - 根据数据更新频率调整 `cache_ttl` ### 2. 并发处理 - 根据CPU核心数调整 `parallel_workers` - 根据网络环境调整 `request_timeout` ### 3. 安全权衡 - 启用路径验证会增加计算开销，但提高安全性 - 启用内容过滤可能会误报，需要调整敏感信息模式 ## 更新日志 ### v2.0.0 (2025-12-18) - ✨ 新增安全验证模块 - ✨ 新增配置管理模块 - ✨ 新增性能监控功能 - 🔧 改进缓存机制 - 🐛 修复已知问题 - 📝 完善文档和测试 ### v1.0.0 (初始版本) - 基础文件夹文档生成功能 - README.md生成 - 思维导图生成 ## 贡献指南 1. Fork 项目 2. 创建特性分支: `git checkout -b feature/new-feature` 3. 提交更改: `git commit -am 'Add new feature'` 4. 推送分支: `git push origin feature/new-feature` 5. 提交Pull Request ### 代码规范 - 遵循PEP 8规范 - 添加类型注解 - 编写单元测试 - 更新文档 ## 许可证 MIT License ## 支持 如有问题，请： 1. 查看本文档的故障排除部分 2. 检查日志文件 `logs/mcp_server.log` 3. 运行测试确保模块正常工作 4. 提交Issue描述问题详情