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

> Learn to use the trace_path MCP tool for effective call-chain analysis. Explore code graphs, data flows, and dependencies within your codebase efficiently.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c), the registration includes:

```c
{"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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) routes the call:

```c
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h) and [`src/store/store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash
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`:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_integration.c) (lines 369-379) demonstrates a typical query:

```c
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.