How to Use the `trace_path` MCP Tool for Call-Chain Analysis in Codebase-Memory-MCP

The trace_path MCP tool performs breadth-first searches over the code-graph to trace call chains, data flows, and cross-service dependencies by querying a SQLite-backed graph store.

The codebase-memory-mcp repository implements a Memory-Cache-Protocol (MCP) server that exposes 14 built-in tools for code analysis. The trace_path tool lets you query call-chain information directly from the graph without needing separate source-code searches, making it ideal for impact analysis and dependency tracing.

What Is the trace_path MCP Tool?

trace_path is one of 14 built-in MCP tools that operate on the code-graph constructed by codebase-memory-mcp. It performs breadth-first search (BFS) traversals over the underlying SQLite store to discover relationships between functions. The tool supports three distinct modes that determine which edge types the BFS follows:

• calls – Follows CALLS edges only (simple caller/callee relationships)
• data_flow – Follows CALLS plus DATA_FLOW edges to track argument and value propagation
• cross_service – Follows CALLS, HTTP_CALLS, ASYNC_CALLS, DATA_FLOWS, and all CROSS_* edges for micro-service boundaries

Tool Architecture and Implementation

Registration and Schema in src/mcp/mcp.c

The tool is registered in the MCP server at line 399 with a JSON schema that defines the expected parameters. According to the source at src/mcp/mcp.c, the registration includes:

{"trace_path", "Trace path",
 "Trace paths through the code graph. Modes: calls (callers/callees), data_flow (value "
 "propagation with args at each hop), cross_service (through HTTP/async Route nodes). "
 "Use INSTEAD OF grep for callers, dependencies, impact analysis, or data flow tracing.",
 {"type":"object","properties":{ … },"required":["function_name","project"]}}

The schema requires both function_name and project parameters, with optional fields for direction, depth, mode, risk_labels, and include_tests.

Dispatch and BFS Traversal Logic

When the MCP server receives a request with method set to "trace_path" or "trace_call_path", the dispatcher at line 5572 in src/mcp/mcp.c routes the call:

if (strcmp(tool_name, "trace_path") == 0 || strcmp(tool_name, "trace_call_path") == 0) {
    … // call trace_path implementation
}

The implementation performs BFS over the graph stored in SQLite (defined in src/store/store.h and src/store/store.c). The direction parameter (inbound, outbound, or both) determines whether the traversal follows incoming callers, outgoing callees, or both. The depth parameter limits the BFS radius (defaulting to 3 hops). Results are wrapped in an MCP content envelope: {"content":[{"type":"text","text":"<inner JSON>"}]}.

trace_path Modes and Edge Types

calls Mode

calls mode traces only explicit function invocations through CALLS edges. Use this for simple dependency analysis when you need to know who calls a function or what a function calls.

data_flow Mode

data_flow mode extends the search to include DATA_FLOW edges, enabling you to track how specific values propagate through the call stack. When combined with the parameter_name argument, you can trace the journey of a variable from its origin through multiple function hops.

cross_service Mode

cross_service mode is designed for distributed systems. It follows HTTP_CALLS, ASYNC_CALLS, and CROSS_* edges to trace interactions across service boundaries, exposing inter-service RPC calls and asynchronous routes that standard call tracing would miss.

How to Query Call Chains with trace_path

All examples use the mcp_call wrapper to invoke the tool via JSON-RPC.

Basic Outbound Call Traces

To discover what functions Compute calls up to three levels deep:

mcp_call trace_path '{"project":"myproj","function_name":"Compute","direction":"outbound","depth":3}'

This returns a JSON array of callees reachable within the specified depth.

Inbound Caller Analysis

To find all functions that eventually call HandleRequest:

mcp_call trace_path '{"project":"myproj","function_name":"HandleRequest","direction":"inbound"}'

Inbound direction reverses the BFS to follow caller edges rather than callee edges.

Bidirectional Context Queries

For full context (both callers and callees), use the both direction with increased depth:

mcp_call trace_path '{"project":"myproj","function_name":"ServiceInit","direction":"both","depth":5}'

Data-Flow Tracking

To track how the raw_input parameter propagates through subsequent calls:

mcp_call trace_path '{
  "project":"myproj",
  "function_name":"ParseInput",
  "direction":"outbound",
  "mode":"data_flow",
  "parameter_name":"raw_input"
}'

This mode reveals not just which functions are called, but how specific data values flow between them.

Cross-Service Tracing

To trace HTTP and async calls across service boundaries:

mcp_call trace_path '{
  "project":"myproj",
  "function_name":"UserLogin",
  "direction":"outbound",
  "mode":"cross_service"
}'

This follows edges through Route nodes to identify inter-service dependencies in micro-service architectures.

Risk-Labelled Results

Add risk classifications to each hop based on distance from the start node:

mcp_call trace_path '{
  "project":"myproj",
  "function_name":"DeleteRecord",
  "direction":"outbound",
  "risk_labels":true
}'

When enabled, each result receives a classification of CRITICAL, HIGH, MEDIUM, or LOW.

Integration Testing Examples

The integration test in tests/test_integration.c (lines 369-379) demonstrates a typical query:

snprintf(args, sizeof(args),
         "{\"function_name\":\"Compute\",\"project\":\"%s\","
         "\"direction\":\"outbound\",\"max_depth\":3}",
         g_project);
char *resp = call_tool("trace_path", args);
ASSERT_NOT_NULL(resp);
ASSERT_TRUE(strstr(resp, "Compute") || strstr(resp, "Multiply") || strstr(resp, "not found"));

This test verifies that trace_path either returns expected functions like Compute and Multiply, or gracefully reports "not found" when names do not match exactly.

The CLI front-end in src/cli/cli.c (lines 470-480) provides human-readable documentation mapping common tasks to tool invocations:

• Who calls X? → trace_path(direction="inbound")
• What does X call? → trace_path(direction="outbound")
• Full context → trace_path(direction="both")
• Risk-classified trace → trace_path(risk_labels=true)

Summary

• trace_path queries the codebase-memory-mcp graph store via BFS traversal implemented in src/store/store.c.
• The tool supports three modes: calls (basic dependencies), data_flow (value propagation), and cross_service (distributed tracing).
• Required parameters are function_name and project; optional parameters include direction (inbound/outbound/both), depth, and risk_labels.
• Results are returned as JSON within an MCP content envelope for uniform parsing by downstream tools.
• Integration tests in tests/test_integration.c validate both successful traces and graceful "not found" handling.

Frequently Asked Questions

How do I trace who is calling a specific function?

Use the inbound direction parameter. For example: mcp_call trace_path '{"project":"myproj","function_name":"TargetFunc","direction":"inbound"}'. This reverses the BFS to traverse caller edges rather than callees, showing you the complete call stack leading to your target function.

What is the difference between trace_path and trace_call_path?

There is no functional difference. According to the dispatch logic in src/mcp/mcp.c at line 5572, both tool names route to the same implementation: if (strcmp(tool_name, "trace_path") == 0 || strcmp(tool_name, "trace_call_path") == 0). The alias exists for backward compatibility or user preference.

Can I use trace_path to analyze data flow for specific variables?

Yes. Set the mode parameter to "data_flow" and optionally specify parameter_name to trace how a specific variable propagates through the call chain. This follows both CALLS and DATA_FLOW edges to show argument passing and value modification through function hops.

What are the performance implications of increasing the depth parameter?

The BFS traversal executes against a SQLite backend defined in src/store/store.h. While the default depth of 3 balances coverage and performance, increasing depth to 5 or higher for cross_service mode on large codebases may increase query latency significantly, as the search space grows exponentially with each hop.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}