Zhiwen Assistant MCP

# 智文助手安装指南 本文档提供智文助手的详细安装和配置说明。 ## 📋 系统要求 ### 基础要求 - **操作系统**: Windows 10+, macOS 10.14+, Ubuntu 18.04+ - **Python版本**: Python 3.8 或更高版本 - **内存**: 最少 512MB，推荐 2GB+ - **磁盘空间**: 最少 100MB ### 推荐环境 - **操作系统**: Windows 11 或 Ubuntu 20.04+ - **Python版本**: Python 3.10+ - **内存**: 4GB+ - **磁盘空间**: 500MB+ ## 🔧 安装步骤 ### 方法一：从GitHub安装（推荐） 1. **克隆仓库** ```bash git clone https://github.com/kscz0000/Zhiwen-Assistant-MCP.git cd Zhiwen-Assistant-MCP ``` 2. **创建虚拟环境** ```bash python -m venv zhiwen-env # Windows zhiwen-env\Scripts\activate # macOS/Linux source zhiwen-env/bin/activate ``` 3. **安装依赖** ```bash pip install -r requirements.txt ``` 4. **验证安装** ```bash python folder_documentation_mcp.py --help ``` ### 方法二：使用pip安装 ```bash pip install zhiwen-assistant ``` ### 方法三：下载分发包 1. 访问 [Releases页面](https://github.com/kscz0000/Zhiwen-Assistant-MCP/releases) 2. 下载最新版本的分发包 3. 解压到目标目录 4. 运行自动安装脚本： ```bash python install.py ``` ## ⚙️ 配置设置 ### 基础配置 1. **复制配置文件** ```bash cp mcp_config.yaml.example mcp_config.yaml ``` 2. **编辑配置文件** ```yaml # 服务器基本配置 server: name: "智文助手-文件夹文档生成器" version: "2.0.0" transport: "stdio" # 功能选项配置 options: exclude_dirs: - ".git" - "__pycache__" - "node_modules" force_update: false output_file: "folder_structure_mindmap.md" max_depth: 10 # 性能配置 performance: cache_ttl: 3600 max_concurrent_operations: 5 enable_performance_monitoring: true # 安全配置 security: enable_security_validation: true scan_sensitive_content: true block_dangerous_files: true ``` ### 高级配置 #### 1. 自定义文件夹描述 在 `config/custom_descriptions.yaml` 中添加： ```yaml custom_descriptions: "src": "源代码目录" "tests": "测试代码目录" "docs": "文档目录" "utils": "工具函数目录" ``` #### 2. 安全规则配置 在 `security/rules.yaml` 中配置： ```yaml blocked_patterns: - "*.pem" - "*.key" - "password*" - "secret*" allowed_paths: - "/projects/*" - "/workspace/*" ``` ## 🧪 验证安装 ### 1. 功能测试 ```bash # 测试基础功能 python test_integration.py # 测试MCP功能 python test_mcp_functionality.py ``` ### 2. 手动测试 ```python # 创建测试目录 mkdir test_project cd test_project mkdir src tests docs # 运行智文助手 python ../folder_documentation_mcp.py # 检查生成的文档 ls README.md ls folder_structure_mindmap.md ``` ## 🔧 故障排除 ### 常见问题 #### 1. Python版本不兼容 **错误**: `SyntaxError: invalid syntax` **解决**: 升级Python到3.8+ ```bash python --version # 如果版本低于3.8，请升级Python ``` #### 2. 依赖安装失败 **错误**: `ERROR: Could not install packages` **解决**: 使用国内镜像源 ```bash pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/ ``` #### 3. 权限问题 **错误**: `PermissionError: [Errno 13] Permission denied` **解决**: ```bash # Windows # 以管理员身份运行PowerShell # macOS/Linux sudo python folder_documentation_mcp.py ``` #### 4. 中文编码问题 **错误**: `UnicodeEncodeError` **解决**: 设置环境变量 ```bash # Windows set PYTHONIOENCODING=utf-8 # macOS/Linux export PYTHONIOENCODING=utf-8 ``` ### 日志查看 查看详细日志： ```bash # Windows type logs\zhiwen.log # macOS/Linux tail -f logs/zhiwen.log ``` ## 🚀 下一步 安装完成后，您可以： 1. 阅读 [使用指南](USAGE.md) 了解详细使用方法 2. 查看 [API文档](API.md) 了解编程接口 3. 阅读 [配置说明](CONFIGURATION.md) 了解高级配置选项 ## 📞 技术支持 如果遇到问题，请： 1. 查看 [常见问题](https://github.com/kscz0000/Zhiwen-Assistant-MCP/issues) 2. 提交新的 [Issue](https://github.com/kscz0000/Zhiwen-Assistant-MCP/issues/new) 3. 发送邮件到 support@zhiwen-assistant.com --- *更新时间: 2025-12-19*