Code Flow MCP

🚀 CodeFlow：认知负载优化的代码分析工具

CodeFlow 是一款强大的基于 Python 的代码分析工具，旨在帮助开发者和自主代理以最小的认知负担理解复杂的代码库。它能生成详细的调用图、识别关键代码元素，并提供语义搜索功能，同时遵循优先考虑人类理解的原则。

通过从抽象语法树（AST）中提取丰富的元数据，并利用持久向量存储（ChromaDB），CodeFlow 实现了对代码结构和行为的高效查询与可视化。

该工具提供了两个主要接口：

• 命令行工具（CLI Tool）：用于直接分析和查询代码库的命令行界面。
• MCP 服务器（MCP Server）：一个模型上下文协议（MCP）服务器，可与 AI 助手和集成开发环境（IDE）集成，实现实时代码分析。

✨ 主要特性

核心分析能力

• 深度 AST 元数据提取（Python）：收集函数和类的全面详细信息，包括：
  • 参数、返回类型、文档字符串
  • 圈复杂度和非注释代码行数（NLOC）
  • 应用的装饰器（如 @app.route、@transactional）
  • 显式捕获的异常
  • 局部声明的变量
  • 推断的外部库/模块依赖
  • 用于高效变更检测的源代码主体哈希
• 智能调用图生成：
  • 构建函数到函数调用的图。
  • 采用多种启发式方法识别代码库中的潜在入口点。
• 持久向量存储（ChromaDB）：
  • 将所有提取的代码元素和调用边存储为语义嵌入。
  • 支持对代码库的函数及其元数据进行快速语义搜索和过滤查询。
  • 将分析结果持久化到磁盘，允许直接查询先前分析过的项目，无需重新解析。

可视化与输出

• Mermaid 图表可视化：
  • 为调用图生成基于文本的 Mermaid 流程图语法。
  • 突出显示与语义查询相关的函数。
  • 包含 LLM 优化模式，用于生成简洁、节省令牌的图表示，适合大语言模型处理，提供清晰的别名和全限定名（FQN）映射。

MCP 服务器特性

• 实时分析：对动态代码库进行文件监控并增量更新。
• 基于工具的 API：通过 MCP 工具为 AI 助手提供分析功能。
• 会话上下文：为复杂的分析工作流维护每个会话的状态。
• 综合工具：语义搜索、调用图生成、函数元数据检索、入口点识别和 Mermaid 图生成。

命令行工具特性

• 批量分析：完成代码库分析并生成报告。
• 交互式查询：对已分析的代码库进行语义搜索。
• 灵活输出：JSON 报告、Mermaid 图表和控制台输出。
• 增量更新：查询现有分析结果，无需重新进行全面处理。

认知负载优化

• 设计原则旨在使工具的输出及其自身的代码库易于理解和使用。
• 心智模型简单性：代码和输出具有清晰、可预测的模式。
• 显式行为：注重清晰性而非简洁性，使隐式操作可见（如装饰器）。
• 信息隐藏与局部性：模块定义明确，将相关代码放在一起。
• 最少背景知识：数据具有自描述性，采用常见模式，减少记忆需求。
• 策略性抽象：仅在真正降低整体复杂性时引入抽象层。
• 线性理解：代码和输出结构便于从上到下轻松阅读。

📦 安装指南

从源代码安装

克隆仓库并安装依赖：

git clone https://github.com/yourusername/codeflow.git
cd codeflow
pip install -e .

这将以可编辑模式安装该包，并使命令行工具和 MCP 服务器可用。

命令行工具

命令行工具作为一个模块可用：

python -m code_flow_graph.cli.code_flow_graph --help

MCP 服务器

MCP 服务器作为一个脚本可用：

code_flow_graph_mcp_server --help

💻 使用示例

命令行工具

code_flow_graph.cli.code_flow_graph 模块是命令行分析的主要入口点。所有命令都以以下形式开始：

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY]

将 [YOUR_CODE_DIRECTORY] 替换为你的项目路径。如果省略，则使用当前目录（.）。

1. 分析代码库并生成报告

此命令将解析你的代码库，构建调用图，填充 ChromaDB 向量存储（持久化在 <YOUR_CODE_DIRECTORY>/code_vectors_chroma/），并生成一个 JSON 报告。

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --language python --output my_analysis_report.json

2. 查询代码库（分析 + 查询）

运行全面分析，然后立即执行语义搜索。如果代码发生了更改，这将更新向量存储。

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --language python --query "functions that handle user authentication"

3. 查询现有分析结果（仅查询）

一旦代码库被分析过（即 [YOUR_CODE_DIRECTORY] 中存在 code_vectors_chroma/ 目录），你可以在不重新运行全面分析的情况下更快地查询它：

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --no-analyze --query "functions related to data serialization"

4. 生成 Mermaid 调用图

你可以为与查询相关的函数生成调用图的 Mermaid 图表。 标准 Mermaid（用于可视化渲染）：

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --query "database connection pooling" --mermaid

输出是 Mermaid 语法，可以复制到 Mermaid 查看器（如 VS Code 扩展、Mermaid.live）中进行可视化。

LLM 优化的 Mermaid（用于 AI 代理）：

python -m code_flow_graph.cli.code_flow_graph [YOUR_CODE_DIRECTORY] --query "main entry point setup" --llm-optimized

此输出去除了视觉样式，并使用短别名作为节点 ID，带有显式的 %% Alias: ShortID = Fully.Qualified.Name 注释。这在为大语言模型提供所有必要结构信息的同时，最小化了令牌数量。

命令行参数

• <directory>：（位置参数，可选）代码库目录的路径（默认：当前目录 .）。这也是持久 ChromaDB 存储的基础目录（<directory>/code_vectors_chroma/）。
• --language：编程语言（python 或 typescript，默认：python）。
• --output：分析报告的输出文件（默认：code_analysis_report.json）。仅在全面分析时使用。
• --query <QUESTION>：执行语义查询。
• --no-analyze：（标志）跳过 AST 提取和图构建。需要 --query。假设存在现有向量存储。
• --mermaid：（标志）为查询结果生成 Mermaid 图。需要 --query。
• --llm-optimized：（标志）生成针对大语言模型令牌数量优化的 Mermaid 图（去除样式）。意味着 --mermaid。

示例报告输出

code_analysis_report.json 提供了一个全面的 JSON 结构，包括摘要、识别的入口点、类摘要和详细的调用图（包含所有元数据的函数和边）。

MCP 服务器

MCP 服务器通过模型上下文协议为 CodeFlow 的分析功能提供编程访问。它可以与 AI 助手、IDE 和其他支持 MCP 的工具集成。

启动服务器

使用默认配置启动 MCP 服务器：

python -m code_flow_graph.mcp_server

或使用自定义配置文件：

python -m code_flow_graph.mcp_server --config path/to/config.yaml

可用工具

服务器通过 MCP 协议公开以下工具：

• ping：测试服务器连接性
• semantic_search：使用自然语言查询进行函数语义搜索
• get_call_graph：以 JSON 或 Mermaid 格式检索调用图
• get_function_metadata：获取特定函数的详细元数据
• query_entry_points：获取代码库中所有识别的入口点
• generate_mermaid_graph：生成用于调用图可视化的 Mermaid 图表
• update_context：使用键值对更新会话上下文
• get_context：检索当前会话上下文

使用客户端进行测试

使用包含的客户端测试服务器功能：

python client.py

这将执行握手并测试基本工具功能。

📚 详细文档

MCP 服务器配置

MCP 服务器使用一个 YAML 配置文件（默认：code_flow_graph/mcp_server/config/default.yaml）：

watch_directories: ["code_flow_graph"]  # 要监控更改的目录
ignored_patterns: ["venv", "**/__pycache__"]  # 分析期间要忽略的模式
chromadb_path: "./code_vectors_chroma"  # ChromaDB 向量存储的路径
max_graph_depth: 3  # 图遍历的最大深度
embedding_model: "all-MiniLM-L6-v2" # 使用的嵌入模型

通过创建自己的配置文件并使用 --config 传递它来自定义这些设置。

示例

命令行工具示例

基本分析

# 分析当前目录并生成报告
python -m code_flow_graph.cli.code_flow_graph . --output analysis.json

# 分析特定项目
python -m code_flow_graph.cli.code_flow_graph /path/to/my/project --language python

语义搜索

# 查找处理用户认证的函数
python -m code_flow_graph.cli.code_flow_graph . --query "user authentication login"

# 搜索数据库操作
python -m code_flow_graph.cli.code_flow_graph . --query "database queries CRUD operations"

可视化

# 为 API 端点生成 Mermaid 图表
python -m code_flow_graph.cli.code_flow_graph . --query "API endpoints" --mermaid

# 生成用于 AI 分析的 LLM 优化图
python -m code_flow_graph.cli.code_flow_graph . --query "error handling" --llm-optimized

MCP 服务器示例

语义搜索

{
  "tool": "semantic_search",
  "input": {
    "query": "functions that handle user authentication",
    "n_results": 5,
    "filters": {}
  }
}

获取函数元数据

{
  "tool": "get_function_metadata",
  "input": {
    "fqn": "myapp.auth.authenticate_user"
  }
}

生成调用图

{
  "tool": "get_call_graph",
  "input": {
    "fqns": ["myapp.main"],
    "format": "mermaid"
  }
}

更新上下文

{
  "tool": "update_context",
  "input": {
    "current_focus": "authentication_module",
    "analysis_depth": "detailed"
  }
}

测试

MCP 服务器测试

运行 MCP 服务器测试套件：

pytest tests/mcp_server/

这包括以下测试：

• 服务器初始化和工具注册
• 工具功能（语义搜索、调用图等）
• 配置加载
• 文件监控和增量更新

命令行工具测试

通过对测试文件运行分析来测试命令行工具：

# 测试基本功能
python -m code_flow_graph.cli.code_flow_graph tests/ --output test_report.json

# 测试查询
python -m code_flow_graph.cli.code_flow_graph tests/ --query "test functions"

集成测试

使用客户端脚本进行端到端测试：

python client.py

这将测试 MCP 协议握手和基本工具交互。

🔧 技术细节

该工具分为三个主要组件，设计清晰且易于维护：

核心组件

1. AST 提取器 (core/ast_extractor.py)

   • 将源代码解析为抽象语法树。
   • 为 FunctionElement 和 ClassElement 对象提取丰富的元数据（复杂度、装饰器、依赖等）。
   • 根据 .gitignore 过滤文件以进行相关分析。

2. 调用图构建器 (core/call_graph_builder.py)

   • 根据提取的 AST 数据构建函数调用的有向图。
   • 使用多种启发式方法识别应用程序的入口点。
   • 提供结构化的 FunctionNode 和 CallEdge 对象，包含丰富的元数据。

3. 向量存储 (core/vector_store.py)

   • 与 ChromaDB 集成，实现持久、可查询的知识库。
   • 存储函数和边的语义嵌入及其详细元数据。
   • 支持语义搜索 (query_functions) 并通过源代码哈希实现高效更新。

MCP 服务器架构

• 服务器 (mcp_server/server.py)：基于 MCP SDK 的服务器，处理 MCP 协议和工具注册。
• 分析器 (mcp_server/analyzer.py)：核心分析逻辑，带有文件监控以进行增量更新。
• 工具 (mcp_server/tools.py)：MCP 工具实现，带有请求/响应模型。
• 配置 (mcp_server/config/)：基于 YAML 的配置管理。

命令行工具架构

• 代码图分析器 (cli/code_flow_graph.py)：分析管道的主要协调器。
• 命令行参数解析和输出格式化。
• 与核心组件集成以进行分析和查询。

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

路线图

• 增强 TypeScript 解析，并实现与 Python 的功能对等。
• 进行高级数据流分析（超越简单的局部变量）。
• 与其他可视化工具（如 Graphviz）集成。
• 为各种框架提供更复杂的入口点检测。
• 直接与 IDE 集成，实现实时分析和导航。
• 支持其他编程语言。
• 提供基于 Web 的用户界面，用于交互式代码探索。
• 开发插件系统，用于自定义分析规则。

致谢

本项目基于以下优秀工作构建：

• ChromaDB
• Sentence Transformers
• Python AST 模块
• Mermaid.js 用于图表绘制。
• MCP SDK 用于 MCP 服务器框架。
• Watchdog 用于文件监控。