get_graph_neighborhood¶

Extract a focused subgraph containing nodes within k hops of a center node. Prevents graph explosion when analyzing large codebases.

Quick Reference¶

get_graph_neighborhood(
    center_node_id: str,             # Center node ID
    k: int = 2,                      # Max hops from center
    max_nodes: int = 100,            # Max nodes to include
    direction: str = "both",         # outgoing, incoming, or both
    min_confidence: float = 0.0,     # Min edge confidence
    project_root: str = None,        # Project directory
    query: str = None                # Graph query (Enterprise)
) -> GraphNeighborhood

User Stories¶

Persona	Story	Tool Value
🔧 Chris (OSS Contributor)	"Extract focused subgraph for targeted analysis without loading entire codebase"	Memory efficiency
🏢 Jennifer (Enterprise Architect)	"Analyze k-hop neighborhoods in large monorepos without memory exhaustion"	Enterprise-scale analysis
👥 David (Team Lead)	"Focus on relevant code sections during impact analysis"	Focused reviews

→ See all user stories

Parameters¶

Parameter	Type	Required	Default	Description
`center_node_id`	string	Yes	-	Node ID (format: `lang::module::type::name`)
`k`	int	No	2	Maximum hops from center
`max_nodes`	int	No	100	Maximum nodes to include
`direction`	string	No	"both"	"outgoing", "incoming", or "both"
`min_confidence`	float	No	0.0	Minimum edge confidence
`project_root`	string	No	cwd	Project root directory
`query`	string	No	None	Graph query language (Enterprise)

Node ID Format¶

Node IDs follow the pattern: language::module::type::name

Examples: - python::services::function::process_order - python::models.user::class::User - python::utils::function::validate_email

Response Schema¶

{
  "data": {
    "center_node": "string",
    "k": "integer",
    "nodes": [
      {
        "id": "string",
        "name": "string",
        "type": "string",
        "file": "string",
        "line": "integer",
        "distance": "integer"
      }
    ],
    "edges": [
      {
        "source": "string",
        "target": "string",
        "type": "string",
        "confidence": "float"
      }
    ],
    "truncated": "boolean",
    "truncation_warning": "string | null",
    "mermaid_diagram": "string"
  },
  "tier_applied": "string",
  "duration_ms": "integer"
}

Examples¶

Get 2-Hop Neighborhood¶

AI PromptMCP Tool CallCLI CommandResponse

Show me all functions within 2 hops of process_order

{
  "center_node_id": "python::services::function::process_order",
  "k": 2
}

codescalpel get-graph-neighborhood process_order --k 2

{
  "data": {
    "center_node": "python::services::function::process_order",
    "k": 2,
    "nodes": [
      {
        "id": "python::services::function::process_order",
        "name": "process_order",
        "type": "function",
        "file": "services/order_service.py",
        "line": 45,
        "distance": 0
      },
      {
        "id": "python::validators::function::validate_order",
        "name": "validate_order",
        "file": "validators/order.py",
        "line": 10,
        "distance": 1
      },
      {
        "id": "python::db::function::save_order",
        "name": "save_order",
        "file": "db/orders.py",
        "line": 25,
        "distance": 1
      },
      {
        "id": "python::db::function::execute_query",
        "name": "execute_query",
        "file": "db/connection.py",
        "line": 15,
        "distance": 2
      },
      {
        "id": "python::validators::function::validate_items",
        "name": "validate_items",
        "file": "validators/items.py",
        "line": 5,
        "distance": 2
      }
    ],
    "edges": [
      {"source": "process_order", "target": "validate_order", "type": "calls"},
      {"source": "process_order", "target": "save_order", "type": "calls"},
      {"source": "save_order", "target": "execute_query", "type": "calls"},
      {"source": "validate_order", "target": "validate_items", "type": "calls"}
    ],
    "truncated": false,
    "mermaid_diagram": "graph TD\n    process_order((process_order))\n    process_order --> validate_order\n    process_order --> save_order\n    save_order --> execute_query\n    validate_order --> validate_items"
  },
  "tier_applied": "community",
  "duration_ms": 95
}

Outgoing Calls Only¶

AI PromptMCP Tool CallCLI CommandResponse

What functions does UserService.get_user call?

{
  "center_node_id": "python::services.user_service::method::UserService.get_user",
  "k": 2,
  "direction": "outgoing"
}

codescalpel get-graph-neighborhood UserService.get_user --k 2 --direction outgoing

{
  "data": {
    "center_node": "UserService.get_user",
    "direction": "outgoing",
    "nodes": [
      {"id": "...", "name": "get_user", "distance": 0},
      {"id": "...", "name": "validate_id", "distance": 1},
      {"id": "...", "name": "query_user", "distance": 1},
      {"id": "...", "name": "execute_query", "distance": 2}
    ],
    "edges": [
      {"source": "get_user", "target": "validate_id"},
      {"source": "get_user", "target": "query_user"},
      {"source": "query_user", "target": "execute_query"}
    ]
  }
}

Incoming Calls (Callers)¶

AI PromptMCP Tool CallCLI CommandResponse

What functions call execute_query?

{
  "center_node_id": "python::db::function::execute_query",
  "k": 2,
  "direction": "incoming"
}

codescalpel get-graph-neighborhood execute_query --k 2 --direction incoming

{
  "data": {
    "center_node": "execute_query",
    "direction": "incoming",
    "nodes": [
      {"name": "execute_query", "distance": 0},
      {"name": "save_order", "distance": 1},
      {"name": "get_user", "distance": 1},
      {"name": "process_order", "distance": 2},
      {"name": "handle_request", "distance": 2}
    ],
    "edges": [
      {"source": "save_order", "target": "execute_query"},
      {"source": "get_user", "target": "execute_query"},
      {"source": "process_order", "target": "save_order"},
      {"source": "handle_request", "target": "get_user"}
    ]
  }
}

With Truncation¶

AI PromptMCP Tool CallCLI CommandResponse

Get neighborhood around main with limit of 20 nodes

{
  "center_node_id": "python::main::function::main",
  "k": 5,
  "max_nodes": 20
}

codescalpel get-graph-neighborhood main --k 5 --max-nodes 20

{
  "data": {
    "center_node": "main",
    "k": 5,
    "nodes": [...],
    "truncated": true,
    "truncation_warning": "Graph truncated at 20 nodes. 45 additional nodes exist within 5 hops.",
    "actual_k_reached": 3
  }
}

High Confidence Edges Only¶

AI PromptMCP Tool Call

Show only high-confidence call relationships

{
  "center_node_id": "python::services::function::process_order",
  "k": 3,
  "min_confidence": 0.8
}

Graph Query Language (Enterprise)¶

Enterprise tier supports a query language:

{
  "center_node_id": "python::controllers::function::handle_request",
  "query": "MATCH (n)-[:calls]->(m:function) WHERE m.name CONTAINS 'DB' RETURN n, m"
}

Mermaid Diagram¶

The tool generates neighborhood visualizations:

graph TD
    center((process_order))

    center --> validate_order
    center --> save_order

    validate_order --> validate_items
    save_order --> execute_query

    style center fill:#f96

Tier Differences¶

This tool is available at all tiers. What differs are the limits and capabilities:

Feature	Community	Pro	Enterprise
Availability	✅ Available	✅ Available	✅ Available
Basic neighborhood	✅	✅	✅
Max k (hops)	2	5	Unlimited
Max nodes	50	200	Unlimited
K-hop traversal	✅	✅	✅
Direction filter	✅	✅	✅
Confidence filter	Not available	✅	✅
Semantic neighbors	Not available	✅ Similar functions	✅ Advanced
Graph query language	Not available	Not available	✅ Custom queries

Use Cases¶

1. Impact Analysis¶

# Before changing a function, see what it affects
result = get_graph_neighborhood(
    center_node_id="python::utils::function::calculate_total",
    k=3,
    direction="incoming"  # What calls this?
)

2. Security Analysis¶

# Find path from user input to database
# Start from a known sink
result = get_graph_neighborhood(
    center_node_id="python::db::function::execute_query",
    k=5,
    direction="incoming",
    min_confidence=0.7
)
# Check if any nodes are user input sources

3. Focused Refactoring¶

# Extract subgraph for a specific feature
result = get_graph_neighborhood(
    center_node_id="python::services::function::process_payment",
    k=2,
    direction="both"
)
# combined_code shows what's needed for the payment feature

Tier Limits¶

get_graph_neighborhood capabilities vary by tier:

Feature	Community	Pro	Enterprise
Max k-hops	1	5	Unlimited
Max nodes	20	100	Unlimited
Direction filtering	✅	✅	✅
Confidence filtering	✅	✅	✅
Mermaid diagrams	✅	✅	✅ Enhanced
Semantic neighbors	❌	✅	✅
Logical relationships	❌	✅	✅
Graph query language	❌	❌	✅

Community Tier¶

✅ Extract 1-hop neighborhood around any node
✅ Filter by edge direction (incoming/outgoing/both)
✅ Filter by minimum confidence score
✅ Basic Mermaid visualization
⚠️ Max k=1 - Only immediate neighbors
⚠️ Max 20 nodes - Small subgraphs only
❌ No semantic neighbor detection
❌ No graph query language

Pro Tier¶

✅ All Community features
✅ Max k=5 - Multi-hop neighborhood exploration
✅ Max 100 nodes - Larger subgraphs
✅ Semantic neighbors - Find conceptually related nodes
✅ Logical relationships - Understand node connections
✅ Enhanced visualization - Better Mermaid diagrams
✅ Truncation warnings - Know when graph is incomplete

Enterprise Tier¶

✅ All Pro features
✅ Unlimited k-hops - Complete neighborhood
✅ Unlimited nodes - No size restrictions
✅ Graph query language - Custom queries (e.g., "MATCH (n)-[:calls]->(m:function) WHERE m.name CONTAINS 'DB' RETURN n, m")
✅ Advanced relationship detection - Deep semantic analysis
✅ Interactive exploration - Navigate graph dynamically

Key Difference: Neighborhood Size and Queries - Community: k=1, 20 nodes - Immediate neighbors only - Pro: k=5, 100 nodes, semantic neighbors - Multi-hop exploration - Enterprise: Unlimited k, unlimited nodes, query language - Complete graph analysis

→ See tier comparison

Best Practices¶

Start with small k - Increase if needed
Use direction - Focus on callers OR callees
Set max_nodes - Prevent memory issues
Check truncation - Results may be incomplete
Use for focused analysis - Not full project graphs

get_call_graph - Full project call graph
get_cross_file_dependencies - Dependency chains
get_project_map - Project overview

get_graph_neighborhood¶

Quick Reference¶

User Stories¶

Parameters¶

Node ID Format¶

Response Schema¶

Examples¶

Get 2-Hop Neighborhood¶

Outgoing Calls Only¶

Incoming Calls (Callers)¶

With Truncation¶

High Confidence Edges Only¶

Graph Query Language (Enterprise)¶

Mermaid Diagram¶

Tier Differences¶

Use Cases¶

1. Impact Analysis¶

2. Security Analysis¶

3. Focused Refactoring¶

Tier Limits¶

Community Tier¶

Pro Tier¶

Enterprise Tier¶

Best Practices¶

Related Tools¶