AI导哈

代码智能分析系统

MacGyver MCP是一个自主代码智能系统，通过多层分析、调用图、依赖跟踪和自学习语义搜索提供深入的代码理解，适用于代码分析、错误修复和功能分析。

  • by aviciot
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 aviciot/MacGyver_mcp

使用说明

MacGyver MCP🛠️

用于bug修复和特征分析的自主代码智能系统

MacGyver是一个MCP（模型上下文协议）服务器 远远超出AST解析 通过多层分析、调用图、依赖跟踪和自学习语义搜索提供深入的代码理解。

当前版本: 0.4.0

🎯 是什么让MacGyver与众不同？

大多数代码分析工具停留在 AST（抽象语法树） -他们看到函数名和结构，但不理解 代码如何流动，什么叫什么，或者为什么.

MacGyver提供 6层智能:

graph TB
    A[User Question:<br/>'How does authentication work?'] --> B[Layer 1: Smart Keyword Extraction]
    B --> C[Layer 2: Multi-Layer Index Search]
    C --> D[Layer 3: Call Graph Analysis]
    D --> E[Layer 4: Dependency Tracking]
    E --> F[Layer 5: Code Fetching + Context]
    F --> G[Layer 6: Architecture Patterns]
    G --> H[Comprehensive Answer<br/>with Code Snippets + Flow Diagrams]

    style A fill:#e1f5ff
    style H fill:#d4edda

📊 超越AST：6层智能堆栈

第1层：AST结构（基础）

让我们从 实际代码 看看AST给我们什么：

示例代码：

# auth.py
def login(username, password):
    """Authenticate user and create session"""
    user = validate_user(username, password)
    if user:
        session = create_session(user)
        return session
    return None

def validate_user(username, password):
    """Check credentials"""
    user_data = load_user_from_db(username)
    if check_password(user_data, password):
        return user_data
    return None

Python的AST看到了什么 （抽象语法树）：

graph TB
    subgraph "AST Tree for login()"
        A[Module: auth.py]
        A --> B[FunctionDef: login]
        B --> C[args: username, password]
        B --> D[body]
        D --> E[Assign: user = ...]
        E --> F1[Call: validate_user]
        D --> G[If statement]
        G --> H[Assign: session = ...]
        H --> I1[Call: create_session]
        G --> J[Return: session]
        D --> K[Return: None]
    end

    subgraph "AST Tree for validate_user()"
        L[FunctionDef: validate_user]
        L --> M[args: username, password]
        L --> N[body]
        N --> O[Assign: user_data = ...]
        O --> P1[Call: load_user_from_db]
        N --> Q[If statement]
        Q --> R[Call: check_password]
        Q --> S[Return: user_data]
        N --> T[Return: None]
    end

    style F1 fill:#fff3cd
    style I1 fill:#fff3cd
    style P1 fill:#fff3cd
    style R fill:#fff3cd

AST为我们提供了什么：

  • ✅ 函数名称： login, validate_user
  • ✅ 参数： username, password
  • ✅ 行号：2、10
  • ✅ 结构：if语句、赋值、返回

缺少什么：

  • ❌ login() 电话 validate_user() 和 create_session() （AST看到“呼叫”节点，但不连接它们）
  • ❌ validate_user() 电话 load_user_from_db() 和 check_password()
  • ❌ 谁打来的 login()?
  • ❌ 数据是如何在系统中流动的？

第二层：调用图提取（我们如何超越AST）

⚠️ 重要提示：这在索引过程中只会发生一次，而不是每个问题！

当你奔跑时 index_repositoryMacGyver分析AST以构建 调用图:

第一步：使用AST解析文件 （索引期间）

# In code_indexer.py:460-465
tree = ast.parse(source_code)

# Find all function definitions
for node in ast.walk(tree):
    if isinstance(node, ast.FunctionDef):
        func_name = node.name

        # Extract calls from this function's body
        calls = extract_function_calls(node)

步骤2：从AST中提取函数调用 （代码索引：253-284）

def _extract_function_calls_from_ast(func_node):
    """Extract REAL function calls from AST (not strings/comments!)"""
    calls = []

    for node in ast.walk(func_node):
        if isinstance(node, ast.Call):  # Found a function call!

            # Case 1: Simple call: validate_user()
            if isinstance(node.func, ast.Name):
                call_name = node.func.id  # "validate_user"

            # Case 2: Method call: obj.method()
            elif isinstance(node.func, ast.Attribute):
                call_name = node.func.attr  # "method"

            calls.append(call_name)

    return calls  # ["validate_user", "create_session"]

步骤3：构建调用图字典 （存储在PostgreSQL中）

# Result stored in database:
call_graph = {
    "auth.py:login": ["validate_user", "create_session"],
    "auth.py:validate_user": ["load_user_from_db", "check_password"],
    "database.py:load_user_from_db": ["execute_query"],
    "auth.py:create_session": ["generate_token", "store_session"],
    "database.py:store_session": ["execute_query"]
}

视觉表现：

graph LR
    subgraph "Call Graph (Built ONCE during indexing)"
        A[auth.py:login] -->|calls| B[auth.py:validate_user]
        A -->|calls| C[auth.py:create_session]
        B -->|calls| D[auth.py:check_password]
        B -->|calls| E[database.py:load_user_from_db]
        E -->|calls| F[database.py:execute_query]
        C -->|calls| G[auth.py:generate_token]
        C -->|calls| H[database.py:store_session]
        H -->|calls| F
    end

    style A fill:#ffeb9c
    style F fill:#f8cecc

    note1[Stored in PostgreSQL<br/>code_index.index_data.layer_3_dependencies.call_graph]
    style note1 fill:#e1f5ff

第四步：当你提问时 （使用预构建的图，无需重新解析！）

# User asks: "How does login reach the database?"

# 1. Load pre-built call graph from database (fast!)
call_graph = load_from_database("code_index")

# 2. Run path-finding algorithm (BFS/DFS)
paths = find_all_paths(
    start="auth.py:login",
    end="database.py:execute_query",
    graph=call_graph  # Pre-built!
)

# 3. Result (in milliseconds, not minutes):
# Path 1: login → validate_user → load_user_from_db → execute_query
# Path 2: login → create_session → store_session → execute_query

主要性能优势：

操作 时间 为什么？
索引存储库 （一次） 30-60秒 解析所有文件，构建调用图，存储在数据库中
提问 （多次） 150-300ms 只需查询预构建的图+获取代码
重新索引 （关于代码更改） 2-5秒 仅重新解析更改的文件

为什么这是95-100%准确：

  • ✅ AST只在代码中看到REAL函数调用（不在注释或字符串中）
  • ✅ 手柄： foo(), obj.method(), module.function()
  • ✅ 正则表达式在注释中匹配“function_name（）”时没有误报
  • ✅ 没有复杂呼叫模式的假阴性

真实示例：

# Question: "How does login reach the database?"

# MacGyver finds ALL paths (using pre-built call graph):
Path 1: auth.py:login → auth.py:validate_user → database.py:load_user_from_db → database.py:execute_query
Path 2: auth.py:login → auth.py:create_session → database.py:store_session → database.py:execute_query

# Also provides:
- Who calls login(): [api.py:api_handler, routes.py:auth_endpoint]
- What login calls: [validate_user, create_session]
- Cycle detection: ❌ No circular dependencies

第3层：依赖关系图（导入关系）

MacGyver的曲目 导入依赖关系 跨文件：

graph TD
    A[api.py] --> B[auth.py]
    A --> C[models.py]
    B --> D[database.py]
    B --> E[utils.py]
    C --> D
    D --> F[cache.py]
    F --> B

    style F fill:#f8cecc
    style B fill:#f8cecc

    note1[Circular Dependency Detected!<br/>auth.py → database.py → cache.py → auth.py]

    style note1 fill:#ffe6e6

检测：

  • ✅ 循环依赖关系（A导入B，B导入C，C导入A）
  • ✅ 未使用的进口
  • ✅ 跨层违规（从演示文稿导入业务逻辑）

第四层：智能关键字提取（语义搜索）

MacGyver使用 混合方法 （规则+法学硕士）理解问题：

flowchart TB
    A[Question: 'How does Oracle analysis work?'] --> B{Step 1: Extract Keywords}
    B --> C[Rules-Based Extraction<br/>~1ms]
    C --> D{Confidence > 70%?}
    D -->|Yes| E[Fast Path: Use Dictionary]
    D -->|No| F[LLM Fallback<br/>~200ms]
    F --> G[Learn New Keywords]
    G --> H[Update Dictionary]
    E --> I[Search Index]
    H --> I
    I --> J[Rank by Relevance]
    J --> K[Return Top Matches]

    style E fill:#d4edda
    style F fill:#fff3cd
    style G fill:#cfe2ff

例子：

# Question: "How does Oracle analysis work?"

# Step 1: Smart Keyword Extraction
Keywords extracted: ["oracle", "analysis"]
❌ Removed stopwords: ["how", "does", "work"]

# Step 2: Search across 5 index layers
Layer 1 (Quick Nav):
  - oracle_analysis() in oracle_tools.py:245 → Score: 20
    (name:oracle +10, name:analysis +10)

Layer 2 (Symbols):
  - analyze_query() in oracle_connector.py:89 → Score: 13
    (param:oracle +5, name:analyze +8)

Layer 3 (Dependencies):
  - OracleAnalyzer class in analyzers.py:156 → Score: 15
    (class:oracle +10, method:analyze +5)

# Step 3: Rank by confidence
1. oracle_analysis() - Confidence: 87% (very_high)
2. OracleAnalyzer - Confidence: 75% (high)
3. analyze_query() - Confidence: 65% (high)

自学：

  • 你第一次问“缓存是如何工作的？”→ 使用LLM（200ms）
  • MacGyver了解到：“缓存”是一个技术关键字
  • 下次→ 使用字典（1ms）⚡

第5层：代码获取+上下文

MacGyver不仅能找到代码，还能获取 带有上下文的实际代码:

# Instead of just: "Found oracle_analysis() at line 245"

# MacGyver shows:
File: oracle_tools.py
Line: 245
Confidence: 87% (very_high)

Code:
>>> 237 | def oracle_analysis(query: str, schema: str):
    238 |     """Analyze Oracle query performance"""
    239 |     # Parse query AST
    240 |     ast = parse_sql(query)
    241 |
>>> 245 |     # Get execution plan <-- FOUND HERE
    246 |     plan = fetch_explain_plan(query, schema)
    247 |
    248 |     # Analyze indexes
    249 |     indexes = check_index_usage(plan)
    250 |
    251 |     return {
    252 |         'plan': plan,
    253 |         'recommendations': generate_recommendations(indexes)
    254 |     }

特征：

  • ✅ 前后显示8行（可配置）
  • ✅ 突出显示确切的线条
  • ✅ 多个片段，便于全面理解
  • ✅ 直接与GitHub集成（无需本地克隆）

第6层：架构模式检测

MacGyver识别 建筑层 自动：

graph TB
    subgraph "Entry Points (API Layer)"
        A1[login_endpoint]
        A2[register_endpoint]
        A3[query_handler]
    end

    subgraph "Business Logic Layer"
        B1[validate_user]
        B2[process_order]
        B3[calculate_price]
    end

    subgraph "Data Access Layer"
        C1[execute_query]
        C2[cache_get]
        C3[cache_set]
    end

    subgraph "Utilities"
        D1[hash_password]
        D2[format_date]
        D3[send_email]
    end

    A1 --> B1
    A2 --> B1
    A3 --> B2
    B1 --> C1
    B2 --> C1
    B2 --> C2
    C1 --> C3
    B1 --> D1
    B2 --> D3

    style A1 fill:#e1f5ff
    style B1 fill:#fff3cd
    style C1 fill:#f8cecc
    style D1 fill:#e2e3e5

检测：

  • ✅ 入口点：未被任何人调用的函数（API终结点）
  • ✅ 热点：许多其他人调用的函数（共享实用程序）
  • ✅ 独立代码：既不调用也不被调用的函数（死代码？）
  • ✅ 设计图案：Singleton、工厂、装饰商等。

🔥 现实世界示例：“查询缓存是如何工作的？”

让我们看看所有6层的实际情况：

步骤1：智能关键字提取

Input: "How does query caching work?"
Keywords: ["query", "caching", "cache"]
Removed: ["how", "does", "work"]

第二步：多层搜索

Found 8 matches across index:
  1. cache_query() in cache_manager.py:156 [score: 23, confidence: 89%]
  2. get_cached_result() in cache_manager.py:78 [score: 18, confidence: 78%]
  3. invalidate_cache() in cache_manager.py:201 [score: 15, confidence: 72%]

步骤3：调用图分析

graph LR
    A[execute_query] --> B{Cache Check}
    B -->|Cache Hit| C[get_cached_result]
    B -->|Cache Miss| D[run_actual_query]
    D --> E[cache_query]
    E --> F[redis_client.setex]
    C --> G[return_to_user]
    E --> G

    style C fill:#d4edda
    style E fill:#fff3cd

步骤4：代码段（前3个匹配项）

匹配1:cache_query（）-置信度89%

>>> 156 | def cache_query(query: str, result: dict, ttl: int = 3600):
    157 |     """Store query result in Redis cache"""
    158 |     cache_key = hash_query(query)
    159 |     redis_client.setex(cache_key, ttl, json.dumps(result))
    160 |     logger.info(f"Cached query: {cache_key}")

匹配2：get_ached_result（）-置信度78%

>>> 78  | def get_cached_result(query: str) -> Optional[dict]:
    79  |     """Retrieve cached query result from Redis"""
    80  |     cache_key = hash_query(query)
    81  |     cached = redis_client.get(cache_key)
    82  |     return json.loads(cached) if cached else None

步骤5：执行流程

Entry Point: execute_query()
  ↓
1. Check cache: get_cached_result()
  ↓
2a. If found → Return cached
2b. If not found → Run query
  ↓
3. Store result: cache_query()
  ↓
4. Return to user

步骤6：相关功能

Functions that call cache_query():
  - execute_query() [main entry point]
  - batch_query_executor() [bulk operations]

Functions called by cache_query():
  - hash_query() [key generation]
  - redis_client.setex() [Redis storage]

Cache invalidation handled by:
  - invalidate_cache() [manual invalidation]
  - auto_expire via TTL [automatic cleanup]

总结答案：

查询缓存分为3个步骤：（1）使用哈希查询键检查Redis缓存，（2）如果未命中，则执行查询并使用1小时TTL存储结果，（3）返回结果。cache_query（）函数处理存储，get_ached_result（）处理检索。缓存命中完全绕过数据库。缓存通过invaldate_Cache（）手动失效，或通过TTL到期自动失效。

🛠️ 可用工具

代码智能

工具 说明 示例
ask_about_code 自然语言代码搜索 “身份验证是如何工作的？”
index_repository 构建5层代码索引 为您的仓库建立索引以实现快速搜索
explain_code_index 显示索引中的内容 查看索引文件、函数、类
visualize_architecture 显示代码层和热点 了解系统架构
trace_feature_flow 逐步执行跟踪 查看系统中的数据流
find_all_paths 查找函数之间的路径 A如何到达B？
analyze_code_quality 综合质量报告 获取代码质量等级（A-F）
detect_dead_code 查找未使用的函数 清理未使用的代码
detect_circular_dependencies 查找导入周期 修复循环导入
detect_complexity_issues 查找深层调用链 确定重构目标

Bug分析

工具 说明 示例
analyze_bug 分析GitHub问题 确定bug是否可以修复
list_allowed_repositories 显示白名单存储库 查看MacGyver可以访问哪些存储库
check_repository_access 检查仓库权限 分析前验证访问权限

特征分析

工具 说明 示例
analyze_feature 分析功能请求 评估实现复杂性

📈 性能特征

搜索速度

┌─────────────────────────┬──────────────┬─────────────┐
│ Operation               │ Cold Start   │ Warm (Cache)│
├─────────────────────────┼──────────────┼─────────────┤
│ Keyword Extraction      │ 200ms (LLM)  │ 1ms (Dict)  │
│ Index Search            │ 3-5ms        │ 1-2ms       │
│ Call Graph Analysis     │ 10-15ms      │ 5-8ms       │
│ Code Snippet Fetch      │ 100-200ms    │ 50-100ms    │
│ Full Question Answer    │ 400-600ms    │ 150-300ms   │
└─────────────────────────┴──────────────┴─────────────┘

准确性比较

┌─────────────────────────┬──────────┬─────────┐
│ Analysis Type           │ MacGyver │ Regex   │
├─────────────────────────┼──────────┼─────────┤
│ Call Graph Accuracy     │ 95-100%  │ 30-50%  │
│ Dead Code Detection     │ 98%      │ 60%     │
│ Circular Deps Detection │ 100%     │ 75%     │
│ Semantic Search Match   │ 85-92%   │ 40-60%  │
└─────────────────────────┴──────────┴─────────┘

🚀 快速开始

先决条件

  • Docker和Docker Compose
  • PostgreSQL数据库
  • GitHub个人访问令牌
  • （可选）用于LLM回退的Anthropic API密钥

1.克隆和设置

git clone https://github.com/aviciot/MacGyver_mcp.git
cd MacGyver_mcp

# Copy environment template
cp .env.example .env

2.配置环境

编辑 .env:

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=macgyver
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-password

# GitHub Access
GITHUB_TOKEN=your-github-token

# Optional: LLM Fallback (for keyword extraction)
ANTHROPIC_API_KEY=your-api-key  # Optional, improves search quality

3.配置存储库

编辑 server/config/settings.yaml:

macgyver:
  allowed_repositories:
    - repository: "yourusername/your-repo"
      permissions: "full"
      github_token: "${GITHUB_TOKEN}"
      description: "Your project"

4.运行数据库迁移

docker-compose up -d postgres
python server/run_migration.py

5.启动MacGyver

# Development mode (hot reload)
docker-compose up macgyver

# Or run locally
cd server
pip install -r requirements.txt
python server.py

6.为您的存储库建立索引

# Via MCP client
{
  "tool": "index_repository",
  "params": {
    "repository": "yourusername/your-repo",
    "force_reindex": false
  }
}

7.开始提问！

{
  "tool": "ask_about_code",
  "params": {
    "repository": "yourusername/your-repo",
    "question": "How does authentication work?"
  }
}

📚 数据库模式

MacGyver使用PostgreSQL和专用 macgyver 架构：

erDiagram
    REPOSITORIES ||--o{ BUG_ANALYSES : has
    REPOSITORIES ||--o{ FIX_ATTEMPTS : has
    REPOSITORIES ||--o{ CODE_INDEX : has
    REPOSITORIES ||--o{ FEATURE_ANALYSES : has

    REPOSITORIES {
        int id PK
        string name
        string owner
        string permissions
        timestamp indexed_at
    }

    BUG_ANALYSES {
        int id PK
        int repository_id FK
        int issue_number
        string decision
        float quality_score
        float complexity_score
        json analysis_data
    }

    CODE_INDEX {
        int id PK
        int repository_id FK
        string commit_sha
        json index_data
        int total_files
        int total_functions
    }

    KEYWORD_DICTIONARY {
        string keyword PK
        string category
        boolean learned_from_llm
        int usage_count
        float confidence_score
    }

7表：

  • repositories -索引存储库
  • bug_analyses -问题分析结果
  • fix_attempts -Bug修复尝试（未来）
  • code_index -5层代码智能
  • feature_analyses -功能请求分析
  • rate_limits -API速率限制
  • keyword_dictionary -自学搜索关键词

🔒 安全和访问控制

三层角色体系

graph TB
    A[API Request] --> B{Authentication}
    B -->|Valid API Key| C{Check Role}
    B -->|Invalid| D[401 Unauthorized]

    C -->|Viewer| E[Read-Only Tools]
    C -->|Developer| F[Analysis Tools]
    C -->|Admin| G[Full Access]

    E --> H[list_repositories<br/>explain_index]
    F --> I[ask_about_code<br/>analyze_bug<br/>visualize_architecture]
    G --> J[All Tools<br/>+ Bug Fixes]

    style E fill:#e1f5ff
    style F fill:#fff3cd
    style G fill:#d4edda

存储库权限

# Read-only access
- repository: "facebook/react"
  permissions: "analyze_only"

# Full access (future: will allow bug fixing)
- repository: "yourusername/your-repo"
  permissions: "full"

🎯 用例

1.引进新开发人员

Q: "How does the authentication system work?"
A: Shows all auth-related code with execution flows

2.Bug调查

Q: "Where does the database connection get established?"
A: Traces from entry point → connection pool → query execution

3.代码审查准备

Tool: analyze_code_quality
Output: Grade B (78/100)
Issues:
  - 3 circular dependencies detected
  - 12 unused functions (dead code)
  - 5 functions with complexity > 10

4.架构文档

Tool: visualize_architecture
Output:
  - Entry points: 8 API endpoints
  - Business logic: 45 functions
  - Data access: 12 database functions
  - Hotspots: execute_query() called by 23 functions

5.重构规划

Tool: detect_complexity_issues
Output:
  - process_order() has call depth 8 (recommend: split)
  - checkout_flow() calls 15 functions (recommend: simplify)

📊 5层代码索引详解

graph TB
    A[Layer 1: Quick Nav] --> B[Layer 2: Symbols]
    B --> C[Layer 3: Dependencies]
    C --> D[Layer 4: Patterns]
    D --> E[Layer 5: History]

    A1[Functions, Classes, Line Numbers] --> A
    B1[Parameters, Decorators, Return Types] --> B
    C1[Call Graph + Import Graph] --> C
    D1[Design Patterns, Hotspots] --> D
    E1[Past Queries, Popular Searches] --> E

    style A fill:#e1f5ff
    style B fill:#fff3cd
    style C fill:#d4edda
    style D fill:#ffd7e5
    style E fill:#e2e3e5

第1层：快速导航（结构）

{
  "files": {
    "auth.py": {
      "functions": [
        {"name": "login", "line": 45, "params": ["username", "password"]}
      ],
      "classes": [
        {"name": "UserAuth", "methods": ["validate", "create_session"]}
      ]
    }
  }
}

第二层：符号（细节）

{
  "symbols": {
    "auth.py:login": {
      "decorators": ["@require_https"],
      "params": ["username: str", "password: str"],
      "returns": "SessionToken",
      "complexity": 5
    }
  }
}

第3层：依赖关系

{
  "call_graph": {
    "auth.py:login": ["auth.py:validate_user", "session.py:create_session"]
  },
  "import_graph": {
    "auth.py": ["database.py", "utils.py"]
  }
}

第4层：模式（架构）

{
  "entry_points": ["api.py:login_endpoint"],
  "hotspots": ["database.py:execute_query"],
  "design_patterns": {
    "singleton": ["DatabaseConnection"],
    "factory": ["QueryBuilder"]
  }
}

第五层：历史（学习）

{
  "popular_searches": [
    {"query": "authentication", "count": 45},
    {"query": "database", "count": 38}
  ]
}

🧪 测试

# Run all tests
python tests/run_tests.py

# Run specific test suite
pytest tests/integration/test_macgyver.py -v

# Test code indexing
python tests/debug/test_code_indexing.py

# Test architecture tools
python tests/debug/test_macgyver_comprehensive.py

🗺️ 路线图

第二阶段：自主修复Bug（2025年第二季度）

  • 自动PR创建
  • 测试执行和验证
  • 人工审批工作流程

第三阶段：多语言支持（2025年第三季度）

  • JavaScript/TypeScript
  • Java
  • 走

第四阶段：高级功能（2025年第四季度）

  • 代码建议和改进
  • 自动重构
  • 性能优化提示

看 ROADMAP.md 了解详情。

📝 许可证

MIT许可证-请参阅 许可证

🤝 贡献

我们欢迎捐款！感兴趣的领域：

  • 附加语言支持（JS、Java、Go）
  • 性能优化
  • 文档改进
  • Bug报告和功能请求

📞 支持

内置于❤️ 使用模型上下文协议（MCP）

相关 MCP