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 用於文件監控。