Skip to content

get_call_graph¶

Generate a call graph showing how functions call each other, detect entry points, and visualize code flow with Mermaid diagrams.

Quick Reference¶

get_call_graph(
    project_root: str = None,                    # Project directory
    entry_point: str = None,                     # Starting function
    depth: int = 10,                             # Max traversal depth
    include_circular_import_check: bool = True,  # Check for circular imports
    paths_from: str = None,                      # Source for path query
    paths_to: str = None,                        # Sink for path query
    focus_functions: list = None                 # Functions to focus on
) -> CallGraphResult

User Stories¶

Persona	Story	Tool Value
🔰 Alex (First-Timer)	"Visualize how functions call each other"	Understand code flow
👥 David (Team Lead)	"Show team how modules interact"	Architecture clarity
🔧 Chris (OSS Contributor)	"Trace how MCP tools are implemented"	Implementation patterns
🏢 Jennifer (Enterprise Architect)	"Trace execution paths across service boundaries"	Distributed system understanding

→ See all user stories

Parameters¶

Parameter	Type	Required	Default	Description
`project_root`	string	No	cwd	Project root directory
`entry_point`	string	No	None	Starting function (e.g., "main" or "app.py:main")
`depth`	int	No	10	Maximum depth to traverse
`include_circular_import_check`	bool	No	true	Check for circular imports
`paths_from`	string	No	None	Source function for path queries
`paths_to`	string	No	None	Sink function for path queries
`focus_functions`	list	No	None	Functions to focus subgraph on

Response Schema¶

{
  "data": {
    "nodes": [
      {
        "id": "string",
        "name": "string",
        "file": "string",
        "line": "integer",
        "type": "string",
        "is_entry_point": "boolean",
        "source_uri": "string"
      }
    ],
    "edges": [
      {
        "source": "string",
        "target": "string",
        "type": "string",
        "context": {
          "in_loop": "boolean",
          "in_try_block": "boolean",
          "in_conditional": "boolean"
        },
        "confidence": "float"
      }
    ],
    "entry_points": ["string"],
    "circular_imports": [
      {
        "cycle": ["string"],
        "files": ["string"]
      }
    ],
    "paths": [
      {
        "from": "string",
        "to": "string",
        "path": ["string"]
      }
    ],
    "mermaid_diagram": "string",
    "statistics": {
      "total_nodes": "integer",
      "total_edges": "integer",
      "max_depth_reached": "integer"
    }
  },
  "tier_applied": "string",
  "max_depth_applied": "integer",
  "max_nodes_applied": "integer",
  "duration_ms": "integer"
}

Examples¶

Basic Call Graph¶

AI PromptMCP Tool CallCLI CommandResponse

Generate a call graph for the src directory

{
  "project_root": "/project/src"
}

codescalpel get-call-graph src/

{
  "data": {
    "nodes": [
      {
        "id": "main::function::main",
        "name": "main",
        "file": "main.py",
        "line": 10,
        "type": "function",
        "is_entry_point": true,
        "source_uri": "file:///project/src/main.py#L10"
      },
      {
        "id": "services::function::process_data",
        "name": "process_data",
        "file": "services.py",
        "line": 25,
        "type": "function",
        "is_entry_point": false
      },
      {
        "id": "db::function::save_results",
        "name": "save_results",
        "file": "db.py",
        "line": 15,
        "type": "function",
        "is_entry_point": false
      }
    ],
    "edges": [
      {
        "source": "main::function::main",
        "target": "services::function::process_data",
        "type": "calls",
        "confidence": 1.0
      },
      {
        "source": "services::function::process_data",
        "target": "db::function::save_results",
        "type": "calls",
        "confidence": 1.0
      }
    ],
    "entry_points": ["main::function::main"],
    "circular_imports": [],
    "mermaid_diagram": "graph TD\n    main[main.py:main] --> process_data[services.py:process_data]\n    process_data --> save_results[db.py:save_results]",
    "statistics": {
      "total_nodes": 3,
      "total_edges": 2,
      "max_depth_reached": 2
    }
  },
  "tier_applied": "community",
  "max_depth_applied": 3,
  "duration_ms": 145
}

From Specific Entry Point¶

AI PromptMCP Tool CallCLI CommandResponse

Show the call graph starting from the handle_request function in routes.py

{
  "project_root": "/project/src",
  "entry_point": "routes.py:handle_request",
  "depth": 5
}

codescalpel get-call-graph src/ \
  --entry-point "routes.py:handle_request" \
  --depth 5

{
  "data": {
    "nodes": [
      {
        "id": "routes::function::handle_request",
        "name": "handle_request",
        "file": "routes.py",
        "line": 20
      },
      {
        "id": "auth::function::verify_token",
        "name": "verify_token",
        "file": "auth.py",
        "line": 45
      },
      {
        "id": "handlers::function::process_order",
        "name": "process_order",
        "file": "handlers.py",
        "line": 30
      },
      {
        "id": "db::function::execute_query",
        "name": "execute_query",
        "file": "db.py",
        "line": 10
      }
    ],
    "edges": [
      {"source": "routes::function::handle_request", "target": "auth::function::verify_token"},
      {"source": "routes::function::handle_request", "target": "handlers::function::process_order"},
      {"source": "handlers::function::process_order", "target": "db::function::execute_query"}
    ],
    "mermaid_diagram": "graph TD\n    handle_request --> verify_token\n    handle_request --> process_order\n    process_order --> execute_query"
  },
  "tier_applied": "pro",
  "max_depth_applied": 50,
  "duration_ms": 230
}

Find Paths Between Functions¶

AI PromptMCP Tool CallCLI CommandResponse

Find all call paths from handle_request to execute_query

{
  "project_root": "/project/src",
  "paths_from": "routes.py:handle_request",
  "paths_to": "db.py:execute_query"
}

codescalpel get-call-graph src/ \
  --paths-from "routes.py:handle_request" \
  --paths-to "db.py:execute_query"

{
  "data": {
    "paths": [
      {
        "from": "routes::function::handle_request",
        "to": "db::function::execute_query",
        "path": [
          "routes::function::handle_request",
          "handlers::function::process_order",
          "db::function::execute_query"
        ],
        "length": 3
      },
      {
        "from": "routes::function::handle_request",
        "to": "db::function::execute_query",
        "path": [
          "routes::function::handle_request",
          "services::function::get_data",
          "db::function::execute_query"
        ],
        "length": 3
      }
    ],
    "total_paths_found": 2
  },
  "tier_applied": "pro",
  "duration_ms": 180
}

Detect Circular Imports¶

AI PromptMCP Tool CallCLI CommandResponse

Check the project for circular imports

{
  "project_root": "/project/src",
  "include_circular_import_check": true
}

codescalpel get-call-graph src/ --include-circular-import-check

{
  "data": {
    "circular_imports": [
      {
        "cycle": ["models", "services", "models"],
        "files": ["models.py", "services.py"]
      }
    ],
    "has_circular_imports": true,
    "suggestion": "Consider using lazy imports or restructuring modules"
  },
  "tier_applied": "community",
  "duration_ms": 95
}

Focus on Specific Functions¶

AI PromptMCP Tool CallCLI CommandResponse

Show the call graph around the authentication functions

{
  "project_root": "/project/src",
  "focus_functions": ["verify_token", "check_permissions", "login"]
}

codescalpel get-call-graph src/ \
  --focus-functions "verify_token,check_permissions,login"

{
  "data": {
    "nodes": [
      {"id": "auth::function::verify_token", "name": "verify_token"},
      {"id": "auth::function::check_permissions", "name": "check_permissions"},
      {"id": "auth::function::login", "name": "login"},
      {"id": "routes::function::protected_route", "name": "protected_route"},
      {"id": "db::function::get_user", "name": "get_user"}
    ],
    "edges": [
      {"source": "protected_route", "target": "verify_token"},
      {"source": "verify_token", "target": "check_permissions"},
      {"source": "login", "target": "get_user"}
    ],
    "focus_applied": true
  },
  "tier_applied": "pro",
  "duration_ms": 120
}

Tier Limits¶

get_call_graph capabilities vary by tier:

Feature	Community	Pro	Enterprise
Max depth	3	50	Unlimited
Max nodes	50	500	Unlimited
Entry point detection	✅	✅	✅
Circular import check	✅	✅	✅
Basic Mermaid visualization	✅	✅	✅
Advanced visualization	❌	✅	✅ Enhanced
Path queries (paths_from/paths_to)	❌	✅	✅
Focus mode	❌	✅	✅
Call context (loops/conditionals)	❌	✅	✅ Full
Confidence scoring	❌	✅	✅
Graph query language	❌	❌	✅

Community Tier¶

✅ Generate basic call graphs
✅ Entry point detection (main, routes, CLI)
✅ Circular import detection
✅ Basic Mermaid diagrams
⚠️ Max depth of 3 - Shallow call graph only
⚠️ Max 50 nodes - Graph truncated for large codebases
❌ No path queries or focus mode
❌ No call context or confidence scoring

Pro Tier¶

✅ All Community features
✅ Max depth of 50 - Deep call chain analysis
✅ Max 500 nodes - Handle larger codebases
✅ Path queries - Find paths from source to sink
✅ Focus mode - Extract subgraph around specific functions
✅ Call context - Know if calls are in loops/conditionals
✅ Confidence scoring - Reliability of each edge
✅ Advanced Mermaid - Better visualization with context

Enterprise Tier¶

✅ All Pro features
✅ Unlimited depth - Complete call graph
✅ Unlimited nodes - No truncation
✅ Graph query language - Custom graph traversals (e.g., "MATCH (n)-[:calls]->(m:function) WHERE m.name CONTAINS 'DB'")
✅ Full call context - Complete execution context
✅ Source URIs - Click-through to IDE
✅ Enhanced visualization - Interactive diagrams

Key Difference: Depth and Query Capabilities - Community: Depth 3, 50 nodes - Quick overview of immediate calls - Pro: Depth 50, 500 nodes, path queries - Trace execution paths for security - Enterprise: Unlimited, query language - Complete call graph analysis

→ See tier comparison

Mermaid Diagram¶

The mermaid_diagram field contains a ready-to-render diagram:

graph TD
    main[main.py:main] --> process[services.py:process_data]
    main --> validate[validators.py:validate]
    process --> save[db.py:save_results]
    process --> log[logger.py:log_event]

Edge Context (Pro+)¶

Edges include context about where calls occur:

{
  "source": "process_order",
  "target": "send_notification",
  "context": {
    "in_loop": false,
    "in_try_block": true,
    "in_conditional": true
  },
  "confidence": 0.95
}

Best Practices¶

Start from entry points - Use entry_point for focused analysis
Use path queries for security - Find routes from input to sinks
Check circular imports - Prevent import errors
Visualize with Mermaid - Easy to understand graphs

get_project_map - Project structure overview
get_graph_neighborhood - K-hop subgraphs
cross_file_security_scan - Security with graph