Zhiwen Assistant MCP

# API参考文档 ## 概述 优化版文件夹文档生成MCP服务器提供了丰富的API接口，支持文档生成、项目分析、模板管理等核心功能。本文档详细介绍了所有可用的API端点、参数和使用方法。 ## 基础信息 - **服务器地址**: `mcp://folder-docs-mcp` - **API版本**: v2.0.0 - **认证方式**: 令牌认证（可选） - **数据格式**: JSON ## 核心API端点 ### 1. 文档生成API #### 1.1 生成README文档 **端点**: `generate_readme` / `generate_readme_v2` **描述**: 为指定目录生成README文档 **参数**: ```json { "directory": "string", // 目标目录路径（必填） "output_path": "string", // 输出文件路径（可选） "template": "string", // 模板名称（可选） "include_hidden": "boolean", // 是否包含隐藏文件（可选） "max_depth": "number", // 最大递归深度（可选） "file_extensions": ["string"] // 文件扩展名过滤（可选） } ``` **响应**: ```json { "success": true, "data": { "output_file": "string", "file_count": "number", "directory_count": "number", "generation_time": "number" }, "message": "string" } ``` **示例**: ```python # 生成默认README result = generate_readme("./my-project") # 使用自定义模板和参数 result = generate_readme_v2( directory="./my-project", output_path="./docs/custom-readme.md", template="detailed", include_hidden=False, max_depth=15, file_extensions=[".py", ".js", ".md"] ) ``` #### 1.2 生成思维导图 **端点**: `generate_mindmap` / `generate_mindmap_v2` **描述**: 为指定目录生成思维导图 **参数**: ```json { "directory": "string", // 目标目录路径（必填） "output_path": "string", // 输出文件路径（可选） "format": "string", // 输出格式（mermaid/plantuml/drawio） "max_depth": "number", // 最大递归深度（可选） "include_files": "boolean" // 是否包含文件（可选） } ``` **响应**: ```json { "success": true, "data": { "output_file": "string", "node_count": "number", "max_depth": "number", "generation_time": "number" }, "message": "string" } ``` **示例**: ```python # 生成Mermaid格式思维导图 result = generate_mindmap( directory="./my-project", output_path="./docs/structure.md", format="mermaid" ) ``` ### 2. 项目分析API #### 2.1 分析项目结构 **端点**: `analyze_project` / `analyze_project_v2` **描述**: 深度分析项目结构和依赖关系 **参数**: ```json { "directory": "string", // 目标目录路径（必填） "depth": "number", // 分析深度（可选） "include_stats": "boolean", // 是否包含统计信息（可选） "dependency_analysis": "boolean", // 是否进行依赖分析（可选） "export_format": "string" // 导出格式（json/yaml/csv） } ``` **响应**: ```json { "success": true, "data": { "project_info": { "name": "string", "path": "string", "type": "string" }, "structure": { "directories": "number", "files": "number", "max_depth": "number" }, "statistics": { "file_types": "object", "size_distribution": "object", "language_distribution": "object" }, "dependencies": "array" }, "message": "string" } ``` **示例**: ```python # 基本分析 result = analyze_project("./my-project") # 详细分析 result = analyze_project_v2( directory="./my-project", depth=20, include_stats=True, dependency_analysis=True, export_format="json" ) ``` ### 3. 批量处理API #### 3.1 批量生成文档 **端点**: `batch_generate` **描述**: 批量为多个项目生成文档 **参数**: ```json { "projects": [ { "directory": "string", "type": "readme|mindmap|both", "output_dir": "string", "template": "string" } ], "parallel": "boolean", // 是否并行处理（可选） "continue_on_error": "boolean" // 出错时是否继续（可选） } ``` **响应**: ```json { "success": true, "data": { "total_projects": "number", "successful": "number", "failed": "number", "results": "array" }, "message": "string" } ``` **示例**: ```python # 批量处理多个项目 projects = [ {"directory": "./project1", "type": "both", "output_dir": "./docs1"}, {"directory": "./project2", "type": "readme", "output_dir": "./docs2"}, {"directory": "./project3", "type": "mindmap", "output_dir": "./docs3"} ] result = batch_generate( projects=projects, parallel=True, continue_on_error=True ) ``` ### 4. 模板管理API #### 4.1 列出可用模板 **端点**: `list_templates` **描述**: 获取所有可用的模板列表 **参数**: 无 **响应**: ```json { "success": true, "data": { "templates": [ { "name": "string", "description": "string", "type": "readme|mindmap", "format": "string", "variables": "array" } ] }, "message": "string" } ``` **示例**: ```python # 获取模板列表 result = list_templates() templates = result.data.templates for template in templates: print(f"模板: {template.name} - {template.description}") ``` #### 4.2 获取模板详情 **端点**: `get_template` **描述**: 获取指定模板的详细信息 **参数**: ```json { "template_name": "string" // 模板名称（必填） } ``` **响应**: ```json { "success": true, "data": { "name": "string", "description": "string", "content": "string", "variables": "array", "examples": "array" }, "message": "string" } ``` ### 5. 配置管理API #### 5.1 获取配置 **端点**: `get_config` **描述**: 获取当前配置信息 **参数**: ```json { "section": "string" // 配置节名称（可选） } ``` **响应**: ```json { "success": true, "data": { "output_dir": "string", "template_dir": "string", "cache_enabled": "boolean", "log_level": "string" }, "message": "string" } ``` #### 5.2 更新配置 **端点**: `set_config` **描述**: 更新配置设置 **参数**: ```json { "config": "object" // 配置对象（必填） } ``` **响应**: ```json { "success": true, "data": { "updated_keys": "array" }, "message": "string" } ``` ### 6. 缓存管理API #### 6.1 获取缓存状态 **端点**: `get_cache_status` **描述**: 获取缓存系统状态 **参数**: 无 **响应**: ```json { "success": true, "data": { "memory_cache": { "size": "number", "max_size": "number", "hit_rate": "number", "items": "number" }, "disk_cache": { "size": "number", "max_size": "number", "hit_rate": "number", "path": "string" } }, "message": "string" } ``` #### 6.2 清理缓存 **端点**: `clear_cache` **描述**: 清理缓存数据 **参数**: ```json { "type": "memory|disk|all", // 缓存类型（可选） "pattern": "string" // 清理模式（可选） } ``` **响应**: ```json { "success": true, "data": { "cleared_items": "number", "freed_space": "number" }, "message": "string" } ``` ### 7. 系统监控API #### 7.1 健康检查 **端点**: `health_check` **描述**: 检查系统健康状态 **参数**: 无 **响应**: ```json { "success": true, "data": { "status": "healthy|unhealthy", "version": "string", "uptime": "number", "components": { "cache": "object", "file_system": "object", "templates": "object" } }, "message": "string" } ``` #### 7.2 获取系统信息 **端点**: `get_system_info` **描述**: 获取系统详细信息 **参数**: 无 **响应**: ```json { "success": true, "data": { "platform": "string", "architecture": "string", "python_version": "string", "memory_usage": "object", "disk_usage": "object" }, "message": "string" } ``` ### 8. 安全API #### 8.1 生成安全令牌 **端点**: `generate_token` **描述**: 生成安全访问令牌 **参数**: ```json { "expires_in": "number", // 过期时间（秒，可选） "scope": "string" // 令牌范围（可选） } ``` **响应**: ```json { "success": true, "data": { "token": "string", "expires_at": "string", "scope": "string" }, "message": "string" } ``` #### 8.2 验证令牌 **端点**: `verify_token` **描述**: 验证访问令牌 **参数**: ```json { "token": "string" // 要验证的令牌（必填） } ``` **响应**: ```json { "success": true, "data": { "valid": "boolean", "user_id": "string", "scope": "string", "expires_at": "string" }, "message": "string" } ``` ## 错误处理 ### 标准错误响应格式 ```json { "success": false, "error": { "code": "string", "message": "string", "details": "object" } } ``` ### 常见错误代码 | 错误代码 | HTTP状态码 | 描述 | |---------|-----------|------| | INVALID_REQUEST | 400 | 请求参数无效 | | UNAUTHORIZED | 401 | 未授权访问 | | FORBIDDEN | 403 | 禁止访问 | | NOT_FOUND | 404 | 资源不存在 | | METHOD_NOT_ALLOWED | 405 | 方法不允许 | | INTERNAL_ERROR | 500 | 内部服务器错误 | | SERVICE_UNAVAILABLE | 503 | 服务不可用 | ### 错误示例 ```json { "success": false, "error": { "code": "INVALID_REQUEST", "message": "目录路径不存在", "details": { "directory": "./nonexistent", "reason": "Path does not exist" } } } ``` ## 认证和安全 ### 令牌认证 1. 生成令牌： ```python result = generate_token(expires_in=3600, scope="read write") token = result.data.token ``` 2. 使用令牌： ```python # 在请求头中添加令牌 headers = { "Authorization": f"Bearer {token}", "Content-Type": "application/json" } ``` ### 数据保护 - 所有敏感数据传输都使用HTTPS加密 - 密码和密钥使用bcrypt哈希 - 临时文件自动清理 - 输入验证和清理 ## 性能优化 ### 缓存策略 - **内存缓存**: 快速访问最近使用的数据 - **磁盘缓存**: 持久化缓存，重启后仍然有效 - **智能失效**: 基于文件修改时间的自动缓存失效 ### 批量处理 - 支持并行处理多个项目 - 智能资源管理，避免内存溢出 - 错误隔离，单个失败不影响其他任务 ## 版本兼容性 ### API版本策略 - **v1.x**: 基础功能，向后兼容 - **v2.x**: 增强功能，推荐使用 - **latest**: 最新功能，可能不稳定 ### 版本迁移 从v1升级到v2的主要变更： 1. **响应格式增强**: v2版本包含更多元数据 2. **错误处理改进**: 更详细的错误信息 3. **性能优化**: 更快的处理速度 4. **安全增强**: 更强的输入验证 ## 示例代码 ### 完整工作流程 ```python # 1. 初始化客户端 client = MCPClient("mcp://folder-docs-mcp") # 2. 生成访问令牌 token_result = client.generate_token(expires_in=3600) token = token_result.data.token client.set_auth_token(token) # 3. 检查系统健康 health = client.health_check() if health.data.status != "healthy": raise Exception("服务不健康") # 4. 获取可用模板 templates = client.list_templates() template_names = [t.name for t in templates.data.templates] # 5. 生成项目文档 result = client.generate_readme_v2( directory="./my-project", template="detailed", output_path="./docs/readme.md" ) # 6. 生成思维导图 mindmap_result = client.generate_mindmap( directory="./my-project", format="mermaid", output_path="./docs/structure.md" ) # 7. 分析项目 analysis = client.analyze_project_v2( directory="./my-project", depth=15, include_stats=True ) # 8. 清理缓存 client.clear_cache(type="all") print("文档生成完成!") ``` ## SDK和客户端库 ### Python SDK ```python from folder_docs_mcp import FolderDocsClient # 创建客户端 client = FolderDocsClient( endpoint="mcp://folder-docs-mcp", auth_token="your_token_here" ) # 使用API result = client.generate_readme("./my-project") ``` ### JavaScript SDK ```javascript import { FolderDocsClient } from 'folder-docs-mcp-js'; // 创建客户端 const client = new FolderDocsClient({ endpoint: 'mcp://folder-docs-mcp', authToken: 'your_token_here' }); // 使用API const result = await client.generateReadme('./my-project'); ``` ### CLI工具 ```bash # 生成README folder-docs generate ./my-project --type readme --output ./docs/ # 生成思维导图 folder-docs generate ./my-project --type mindmap --format mermaid # 批量处理 folder-docs batch --projects ./projects.json --parallel # 健康检查 folder-docs health-check ``` ## 故障排除 ### 常见问题 1. **认证失败** - 检查令牌是否过期 - 验证令牌格式是否正确 - 确认令牌权限范围 2. **路径访问错误** - 验证路径是否存在 - 检查文件权限 - 确认路径格式正确 3. **内存不足** - 减少批量处理数量 - 降低max_depth参数 - 清理缓存 4. **模板错误** - 检查模板语法 - 验证模板变量 - 确认模板存在 ### 调试模式 启用调试模式获取详细信息： ```python # 设置调试级别 client.set_debug_level("verbose") # 查看请求详情 client.enable_request_logging(True) # 获取性能统计 stats = client.get_performance_stats() ``` ## 更新日志 ### v2.0.0 (当前版本) - ✨ 新增批量处理API - ✨ 增强模板系统 - ✨ 改进错误处理 - 🚀 性能优化 - 🛡️ 安全增强 - 📊 监控和指标 ### v1.5.0 - ✨ 添加思维导图生成 - ✨ 支持自定义模板 - 🐛 修复路径处理bug ### 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)