Claude Flow

一个智能化代码分析和工作流自动化工具，支持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. 克隆项目仓库

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

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

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

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

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

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

3. 验证安装

# 测试工具包功能
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. 获取项目完整路径

# 在项目目录中获取完整路径
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 示例:

{
  "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 示例:

{
  "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 服务

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

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

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

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

4. 验证 MCP 服务状态

# 测试 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)

# 基本代码审查
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)

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

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

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

3. 文件打包 (pack_files)

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

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

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

高级使用技巧

场景链式执行

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

自定义参数传递

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

批量处理

# 批量分析多个目录
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: 新项目初始评估

# 步骤1: 分析项目结构
structure = analyze_code("./", analysis_type="structure")

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

# 步骤3: 生成评估报告

场景2: 代码质量检查

# 步骤1: 执行代码审查
review = execute_workflow("code_review", path="./src")

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

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

场景3: 项目文档生成

# 步骤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 代理提示词和参数配置

🚀 快速开始

基本用法

# 查看所有可用场景
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

新版本调试和错误处理

# 基本调试模式 - 显示详细执行过程
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

自定义工作流

# 简单的工具包调用序列
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 - 代码审查

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

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

security_audit - 安全审计

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

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

performance_analysis - 性能分析

代码性能评估、瓶颈识别和优化建议。

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

test_coverage - 测试覆盖率

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

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

documentation_review - 文档评估

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

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

dependency_analysis - 依赖分析

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

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

comprehensive_analysis - 综合分析

全面的项目分析，包含多个维度的评估。

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] - 引用数组元素

📝 场景配置格式

基本格式

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

示例场景

{
  "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"
    }
  }
}

🔍 调试和监控

调试模式

# 启用详细调试信息
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

导出执行结果

# 导出上下文到文件
python claude_flow.py --scenario comprehensive_analysis --export results.json

执行历史

系统会自动记录：

• 每个步骤的执行时间
• 成功/失败状态
• 错误信息和堆栈跟踪
• 上下文变量的变化

🛠️ 命令行用法

基本命令

# 查看可用场景
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 仓库
• Claude Code 文档

---

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