# Claude Flow v2.2.0 - MCP集成的AI工作流系统

一个智能化代码分析和工作流自动化工具，支持MCP服务集成到Claude Code，提供预定义场景执行、自定义工作流构建、变量上下文传递和 CLI 工具集成。

## 🌟 核心特性

### MCP 服务集成
- **🔌 Claude Code 集成** - 完整支持 Model Context Protocol，可直接在Claude Code中使用
- **🛠️ 工作流即服务** - 通过MCP接口提供代码分析和工作流执行功能
- **📊 标准化输出** - 统一格式的分析结果，便于Claude Code处理和展示
- **⚡ 高性能处理** - 优化的服务架构，支持并发请求和大型项目分析

### 智能代码分析
- **📁 项目结构分析** - 自动分析代码组织结构和文件统计
- **🔍 深度代码审查** - 支持代码质量、安全性、性能等多维度分析
- **📦 智能文件打包** - 自动收集和整理项目文档及代码文件
- **🎯 场景化分析** - 提供7种预定义分析场景，满足不同需求

### 工作流自动化
- **🔄 多步骤工作流** - 支持复杂的自动化分析流程
- **🎛️ 变量传递系统** - 智能的上下文变量替换和数据传递
- **🚨 完善错误处理** - 分层错误处理、重试机制、多种错误处理模式
- **📊 执行监控** - 实时进度跟踪、详细日志记录、性能指标收集

### 安全与可靠性
- **🛡️ 安全加固** - 修复CLI注入漏洞，严格的输入验证和资源限制
- **✅ 高质量测试** - 核心测试覆盖率99.3%，确保功能稳定可靠
- **🔒 权限控制** - 安全的文件访问和命令执行机制

## 📦 安装

### 环境要求
- Python 3.7+
- Claude CLI (可选)
- Gemini CLI (可选)

### 安装步骤

1. **克隆项目仓库**

```bash
# 使用 git 克隆项目
git clone https://github.com/catlog22/Claude-flow-mcp.git

# 进入项目目录
cd Claude-flow-mcp

# 检查 Python 版本 (需要 3.7+)
python --version
```

2. **安装依赖（如果需要）**

```bash
# 安装测试依赖 (可选)
pip install -r requirements-test.txt

# 或安装运行时依赖 (可选)
pip install -r requirements.txt
```

3. **验证安装**

```bash
# 测试工具包功能
python claude_toolkit.py analyze .

# 查看可用场景
python claude_flow.py --list

# 测试MCP服务
python mcp_server.py --test
```

4. **配置 Claude CLI 和 Gemini CLI（根据需要）**
   - 安装并配置 Claude CLI
   - 安装并配置 Gemini CLI

## 🔌 MCP 服务安装配置

Claude Flow v2 支持作为 MCP (Model Context Protocol) 服务运行，可集成到 Claude Code 中使用。

### MCP 服务配置

1. **获取项目完整路径**

```bash
# 在项目目录中获取完整路径
cd Claude-flow-mcp
pwd  # Linux/Mac
cd   # Windows
```

2. **添加 MCP 服务配置到 Claude Code**

找到并编辑 Claude Code 的配置文件 `claude_desktop_config.json`：

**配置文件位置:**
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` 
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

在配置文件中添加（根据你的实际路径修改）：

**Windows 示例:**
```json
{
  "mcpServers": {
    "claude-flow": {
      "command": "python",
      "args": ["C:\\Users\\YourName\\Claude-flow-mcp\\mcp_server.py"],
      "env": {
        "PYTHONPATH": "C:\\Users\\YourName\\Claude-flow-mcp"
      }
    }
  }
}
```

**Linux/Mac 示例:**
```json
{
  "mcpServers": {
    "claude-flow": {
      "command": "python",
      "args": ["/home/yourname/Claude-flow-mcp/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/home/yourname/Claude-flow-mcp"
      }
    }
  }
}
```

> **重要**: 将 `/path/to/Claude-flow-mcp` 替换为你实际克隆项目的完整路径

3. **启动 MCP 服务**

```bash
# 进入项目目录
cd Claude-flow-mcp

# 直接运行 MCP 服务器
python mcp_server.py

# 或使用批处理脚本 (Windows)
start_mcp.bat

# 或使用 Shell 脚本 (Linux/Mac)
./start_mcp.sh
```

4. **验证 MCP 服务状态**

```bash
# 测试 MCP 连接
python test_mcp_client.py

# 检查服务可用性
python start_mcp_server.py --test
```

### MCP 功能特性

- **🚀 工作流执行**: 通过 `execute_workflow` 方法执行预定义场景
- **🔍 代码分析**: 通过 `analyze_code` 方法分析项目结构
- **📦 文件打包**: 通过 `pack_files` 方法打包项目文件
- **🛠️ 场景管理**: 支持列出和选择不同分析场景
- **📊 结果格式化**: 自动格式化输出结果，便于 Claude Code 使用
- **🎯 智能路径处理**: 自动解析相对路径和绝对路径
- **⚡ 高性能处理**: 支持大型项目的高效分析
- **🔄 实时状态反馈**: 详细的执行进度和结果信息

## 🎯 MCP 使用指南

### 基本MCP方法调用

在 Claude Code 中，MCP服务提供以下主要方法：

#### 1. 执行工作流 (`execute_workflow`)

```python
# 基本代码审查
execute_workflow("code_review", path="./src")

# 安全审计，启用调试模式
execute_workflow("security_audit", path=".", debug=True)

# 性能分析，指定输出格式
execute_workflow("performance_analysis", path="./src", output_format="markdown")

# 综合分析，设置错误处理模式
execute_workflow("comprehensive_analysis", path=".", error_mode="continue_on_error")
```

#### 2. 代码结构分析 (`analyze_code`)

```python
# 分析项目整体结构
analyze_code("./", analysis_type="structure")

# 分析特定目录的文件统计
analyze_code("./src", analysis_type="files")

# 深度分析包含子目录
analyze_code("./project", analysis_type="deep", include_subdirs=True)
```

#### 3. 文件打包 (`pack_files`)

```python
# 打包Python文件
pack_files("./src", file_types=["*.py"])

# 打包多种文件类型
pack_files("./", file_types=["*.py", "*.js", "*.md"])

# 打包指定目录，排除某些文件
pack_files("./src", exclude_patterns=["__pycache__", "*.pyc"])
```

### 高级使用技巧

#### 场景链式执行

```python
# 先分析结构，再执行代码审查
structure = analyze_code("./src", analysis_type="structure")
review = execute_workflow("code_review", path="./src", context=structure)
```

#### 自定义参数传递

```python
# 使用自定义配置执行工作流
execute_workflow("code_review", 
    path="./src",
    custom_params={
        "focus_areas": ["security", "performance"],
        "severity_threshold": "medium",
        "output_detail": "verbose"
    }
)
```

#### 批量处理

```python
# 批量分析多个目录
directories = ["./src", "./tests", "./docs"]
results = []
for dir_path in directories:
    result = analyze_code(dir_path, analysis_type="structure")
    results.append(result)
```

## 💬 在 Claude Code 中使用

### MCP 服务调用

在 Claude Code 中使用 `use claude-flow` 指令来启用 Claude Flow MCP 服务：

```
use claude-flow
```

启用后，你可以通过自然语言描述需求，系统会自动调用相应的MCP功能：

### 基础使用方式

#### 场景触发指令
```
use claude-flow

使用 code_review 场景分析 ./src 目录

使用 security_audit 场景检查整个项目的安全问题

使用 performance_analysis 场景分析项目性能
```

#### 自然语言描述
```
use claude-flow

请帮我分析这个Python项目的代码质量，重点关注安全问题和性能优化建议。

请对我的项目进行全面的代码审查，包括架构分析、安全检查和最佳实践评估。

帮我分析项目结构并打包所有源代码文件。
```

### 进阶使用技巧

#### 1. 组合场景执行
```
use claude-flow

使用 comprehensive_analysis 场景对整个项目进行全面分析

先用 code_review 场景审查代码，再用 security_audit 场景检查安全问题

使用 test_coverage 场景分析测试覆盖率
```

#### 2. 指定分析重点
```
use claude-flow

使用 security_audit 场景重点检查SQL注入和XSS漏洞

使用 performance_analysis 场景专注于算法效率和内存使用

使用 code_review 场景关注代码风格和架构设计
```

#### 3. 自定义输出要求
```
use claude-flow

使用 code_review 场景生成详细的Markdown格式报告

使用 security_audit 场景输出包含修复建议的完整报告

使用 dependency_analysis 场景分析并输出依赖安全报告
```

### 常用对话模板

#### 新项目评估
```
use claude-flow

我有一个新的Python Web项目，请帮我进行全面评估：

使用 comprehensive_analysis 场景分析整个项目，重点关注：
- 代码架构和组织结构
- 安全漏洞和风险点
- 性能瓶颈和优化机会
- 测试覆盖率和质量
```

#### 代码质量检查
```
use claude-flow

使用 code_review 场景深度分析我的项目代码质量，关注：
- 代码风格一致性
- 潜在bug和逻辑问题
- 架构设计合理性
- 最佳实践遵循情况
```

#### 安全审计检查
```
use claude-flow

使用 security_audit 场景对我的Web应用进行全面安全检查：
- OWASP Top 10 常见漏洞
- 依赖包安全问题
- 敏感信息泄露风险
- API接口安全性
```

#### 性能分析评估
```
use claude-flow

使用 performance_analysis 场景分析我的应用性能：
- 代码执行效率
- 数据库查询优化
- 算法复杂度分析
- 内存使用情况
```

### 实用场景示例

#### 日常开发检查
```
use claude-flow

使用 code_review 场景检查我刚完成的功能模块

使用 security_audit 场景检查新添加的API接口安全性

使用 test_coverage 场景验证测试覆盖率是否达标
```

#### 项目发布前检查
```
use claude-flow

使用 comprehensive_analysis 场景对项目进行发布前全面检查

使用 security_audit 场景进行生产环境安全审计

使用 performance_analysis 场景检查性能是否满足要求
```

#### 代码重构支持
```
use claude-flow

使用 code_review 场景分析重构前的代码质量

使用 dependency_analysis 场景检查依赖关系复杂度

使用 performance_analysis 场景对比重构前后的性能差异
```

### 可用场景列表

- **code_review** - 全面代码质量审查
- **security_audit** - 安全漏洞检测和审计  
- **performance_analysis** - 性能分析和优化建议
- **test_coverage** - 测试覆盖率分析
- **documentation_review** - 文档完整性评估
- **dependency_analysis** - 依赖包安全和更新检查
- **comprehensive_analysis** - 综合多维度分析

### 实际应用场景

#### 场景1: 新项目初始评估
```python
# 步骤1: 分析项目结构
structure = analyze_code("./", analysis_type="structure")

# 步骤2: 执行综合分析
analysis = execute_workflow("comprehensive_analysis", path="./")

# 步骤3: 生成评估报告
```

#### 场景2: 代码质量检查
```python
# 步骤1: 执行代码审查
review = execute_workflow("code_review", path="./src")

# 步骤2: 安全审计
security = execute_workflow("security_audit", path="./")

# 步骤3: 测试覆盖率检查
coverage = execute_workflow("test_coverage", path="./")
```

#### 场景3: 项目文档生成
```python
# 步骤1: 打包相关文件
files = pack_files("./", file_types=["*.py", "*.md", "*.json"])

# 步骤2: 执行文档评估
docs = execute_workflow("documentation_review", path="./")

# 步骤3: 生成改进建议
```

### 配置文件说明

- `mcp_config.json` - MCP 服务运行配置
- `scenarios.json` - 预定义工作流场景定义
- `agent.json` - AI 代理提示词和参数配置

## 🚀 快速开始

### 基本用法

```bash
# 查看所有可用场景
python claude_flow_v2.py --list

# 执行代码审查场景
python claude_flow_v2.py --scenario code_review --path ./src

# 执行安全审计（启用调试模式）
python claude_flow_v2.py --scenario security_audit --path . --debug

# 使用错误继续模式执行
python claude_flow_v2.py --scenario comprehensive_analysis --error-mode continue_on_error

# 保存详细日志到文件
python claude_flow_v2.py --scenario code_review --path ./src --debug --log-file analysis.log
```

### 新版本调试和错误处理

```bash
# 基本调试模式 - 显示详细执行过程
python claude_flow_v2.py --scenario code_review --path ./src --debug

# 错误处理模式
# 1. 停止模式 (默认) - 遇到关键错误立即停止
python claude_flow_v2.py --scenario analysis --error-mode stop_on_error

# 2. 继续模式 - 记录错误但继续执行
python claude_flow_v2.py --scenario analysis --error-mode continue_on_error

# 3. 交互模式 - 遇到错误时询问用户
python claude_flow_v2.py --scenario analysis --error-mode interactive

# 日志配置
# 保存详细日志到文件
python claude_flow_v2.py --scenario security_audit --debug --log-file security_analysis.log

# 设置日志级别
python claude_flow_v2.py --scenario code_review --log-level DEBUG --log-file debug.log
```

### 自定义工作流

```bash
# 简单的工具包调用序列
python claude_flow_v2.py \
  --exec "files:analyze:src/" \
  --exec "docs:pack_claude_md" \
  --exec "config:pack:./config"

# 混合工具包和CLI调用
python claude_flow_v2.py \
  --exec "structure:analyze:." \
  --cli "review:claude:Review this structure [structure]:--permission-mode plan"

# 复杂的多步工作流（启用错误继续模式）
python claude_flow_v2.py \
  --exec "src_files:analyze:src/" \
  --exec "test_files:analyze:tests/" \
  --cli "coverage:gemini:Analyze test coverage - source: [src_files] tests: [test_files]:-y" \
  --cli "report:claude:Generate final report based on [coverage.stdout]:--output-format markdown" \
  --error-mode continue_on_error --debug
```

## 📋 预定义场景

### code_review - 代码审查
全面的代码质量审查，包括架构分析、安全检查和最佳实践评估。

```bash
python claude_flow_v2.py --scenario code_review --path ./src
```

### security_audit - 安全审计
专注于安全漏洞检测、配置文件审查和敏感信息扫描。

```bash
python claude_flow_v2.py --scenario security_audit --path . --debug
```

### performance_analysis - 性能分析
代码性能评估、瓶颈识别和优化建议。

```bash
python claude_flow.py --scenario performance_analysis --path ./src
```

### test_coverage - 测试覆盖率
测试覆盖率分析和缺失测试识别。

```bash
python claude_flow.py --scenario test_coverage --path .
```

### documentation_review - 文档评估
项目文档完整性和质量评估。

```bash
python claude_flow.py --scenario documentation_review --path .
```

### dependency_analysis - 依赖分析
项目依赖包分析、安全检查和更新建议。

```bash
python claude_flow.py --scenario dependency_analysis --path .
```

### comprehensive_analysis - 综合分析
全面的项目分析，包含多个维度的评估。

```bash
python claude_flow.py --scenario comprehensive_analysis --path .
```

## 🎛️ 高级功能

### Agent 变量系统
支持通过 `[agent:name]` 格式引用预定义的 agent 配置，可用于自定义工作流：

**可用 Agent 类型:**
- `code-developer` - 代码开发和 TDD 最佳实践
- `code-review` - 代码质量和安全审查
- `security-audit` - 安全漏洞检测专家
- `performance-optimizer` - 性能优化分析
- `documentation` - 技术文档生成

### 变量系统
支持复杂的变量传递和数据流控制：
- `[variable]` - 引用变量值
- `[variable.field]` - 引用嵌套字段
- `[variable.array.0]` - 引用数组元素


## 📝 场景配置格式

### 基本格式
```json
{
  "scenario_name": {
    "step1": "工具包方法调用",
    "step2": {
      "executor": "claude|gemini",
      "content": "执行内容，支持 [变量] 替换",
      "params": "CLI参数"
    },
    "step3": "另一个工具包调用或字符串处理"
  }
}
```

### 示例场景
```json
{
  "my_analysis": {
    "structure": "analyze:[input_path]",
    "docs": "pack_claude_md",
    "review": {
      "executor": "claude",
      "content": "分析项目结构: [structure.summary]，文档: [docs.metadata]",
      "params": "--permission-mode plan --output-format markdown"
    },
    "summary": {
      "executor": "gemini",
      "content": "生成总结报告: [review.stdout]",
      "params": "-y --debug"
    }
  }
}
```

## 🔍 调试和监控

### 调试模式
```bash
# 启用详细调试信息
python claude_flow.py --scenario code_review --path . --debug

# Dry run 模式（仅显示步骤，不执行）
python claude_flow.py --scenario security_audit --dry-run

# 静默模式
python claude_flow.py --scenario quick_scan --path . --quiet
```

### 导出执行结果
```bash
# 导出上下文到文件
python claude_flow.py --scenario comprehensive_analysis --export results.json
```

### 执行历史
系统会自动记录：
- 每个步骤的执行时间
- 成功/失败状态
- 错误信息和堆栈跟踪
- 上下文变量的变化

## 🛠️ 命令行用法

### 基本命令
```bash
# 查看可用场景
python claude_flow.py --list

# 执行特定场景
python claude_flow.py --scenario code_review --path ./src

# 启用调试模式
python claude_flow.py --scenario security_audit --debug

# 导出结果
python claude_flow.py --scenario comprehensive_analysis --export results.json
```

## 📁 配置说明

### 重要配置文件
- `mcp_server.py` - MCP 服务入口
- `scenarios.json` - 预定义分析场景
- `agent.json` - AI 代理配置

## ⚠️ 使用注意

- 确保 Python 3.7+ 环境
- MCP 服务需要正确配置路径
- 大文件会自动跳过以提高性能

## 🔧 故障排除

### 常见问题
- **MCP连接失败**: 检查配置文件路径是否正确
- **场景不存在**: 使用 `python claude_flow.py --list` 查看可用场景
- **权限错误**: 确保对目标目录有读取权限

## 📈 版本说明

**当前版本：v2.2.0**
- ✅ 完整 MCP 协议支持，可直接集成到 Claude Code
- ✅ 7种预定义分析场景，满足不同项目需求
- ✅ 99.3% 测试覆盖率，确保功能稳定可靠
- ✅ 安全加固和完善的错误处理机制

## 🤝 项目信息

### 开源许可
本项目基于 MIT 许可证开源

### 相关链接
- [GitHub 仓库](https://github.com/catlog22/Claude-flow-mcp)
- [Claude Code 文档](https://docs.anthropic.com/claude/docs)

---

**让代码分析和工作流自动化变得简单高效！**