# MCP Tool Definition Lookup Logging in DeusData Codebase Memory > Explore MCP tool definition lookup logging in the DeusData codebase-memory-mcp repo. Understand emitted JSON logs for definition.lookup, definition.found, definition.unresolved, and definition.error, plus request metrics. - Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) - Tags: how-to-guide - Published: 2026-07-03 --- **The DeusData codebase-memory-mcp server emits structured JSON log entries for every tool definition lookup via the `cbm_log_info`, `cbm_log_warn`, and `cbm_log_error` functions, tagging them as `definition.lookup`, `definition.found`, `definition.unresolved`, or `definition.error`, while also recording overall request metrics through `cbm_log_mcp_request`.** The DeusData/codebase-memory-mcp repository provides a Model Context Protocol (MCP) server that enables AI assistants to query symbol definitions across codebases. Understanding the **MCP tool definition lookup logging** is essential for debugging symbol resolution failures and monitoring query performance. The logging system writes machine-readable JSON Lines to the logfile specified by the `CBM_INDEX_LOG` environment variable. ## Log Levels and Tags for Definition Lookups The MCP server uses a structured logging approach where each definition lookup generates specific tagged entries. These logs are implemented in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) using the core logging helpers from [`src/foundation/log.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/log.c). ### Request Initiation (definition.lookup) When the `handle_definition_call` function in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) receives a definition tool request, it immediately logs an INFO-level entry with the tag `definition.lookup`. This entry captures the tool name, project context, source file path, target symbol, and the JSON-RPC request ID. ```c /* Logged at the start of every definition lookup */ cbm_log_info("definition.lookup", "tool", tool_name, "project", project, "path", src_path, "symbol", symbol, "request_id", req_id); ``` ### Successful Resolution (definition.found) After resolving the symbol to its definition location, the server emits a `definition.found` INFO entry. This structured log includes the symbol name, definition file path (`def_path`), line number (`def_line`), internal node identifier, and the match count. ```c /* Logged when definition is successfully resolved */ cbm_log_info("definition.found", "symbol", symbol, "def_path", def_path, "def_line", line, "node_id", node_id, "match_count", count, "request_id", req_id); ``` ### Missing Symbols (definition.unresolved) If the lookup completes without finding the requested symbol, the server logs a WARN-level entry tagged `definition.unresolved`. This captures the symbol name and a reason string (e.g., "no symbol in index") to help diagnose why resolution failed. ```c /* Logged when symbol cannot be found in the index */ cbm_log_warn("definition.unresolved", "symbol", symbol, "reason", "no symbol in index", "request_id", req_id); ``` ### Error Conditions (definition.error) When internal failures occur during the lookup process—such as store errors or malformed requests—the server emits an ERROR-level entry with the tag `definition.error`. This includes the error message, error code, and the associated request ID. ```c /* Logged when the handler encounters an internal failure */ cbm_log_error("definition.error", "error_msg", err_msg, "error_code", err_code, "request_id", req_id); ``` ### Generic Request Logging (mcp.request) Every RPC call, including definition lookups, is recorded via `cbm_log_mcp_request` in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c). This INFO-level entry uses the tag `mcp.request` and captures the RPC method, tool name, error status boolean, and processing duration in microseconds. ```c /* Logged for every tool call including definition lookups */ cbm_log_mcp_request(req.method, tool_name, is_err, request_dur_us); ``` ## Source Code Implementation The logging infrastructure resides in [`src/foundation/log.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/log.c), which implements `cbm_log_info`, `cbm_log_warn`, and `cbm_log_error`. The definition-specific logging logic is implemented in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) within the `handle_definition_call` function, which orchestrates the lookup workflow and emits the appropriate log entries at each stage. ## Accessing and Filtering Logs Logs are written as JSON Lines to the directory specified by the `CBM_INDEX_LOG` environment variable (defaulting to `/logs`). You can inspect these logs using standard JSON processing tools. To view only definition lookup initiations: ```bash jq -c 'select(.tag=="definition.lookup")' $CBM_INDEX_LOG/*.log ``` To view all definition-related results including both successful finds and unresolved symbols: ```bash jq -c 'select(.tag|startswith("definition."))' $CBM_INDEX_LOG/*.log ``` A complete request flow produces sequential entries like this: ```json {"tag":"definition.lookup","tool":"definition","project":"myproj","path":"src/foo.c","symbol":"myFunc","request_id":13} {"tag":"definition.found","symbol":"myFunc","def_path":"src/bar.c","def_line":42,"node_id":12345,"match_count":1,"request_id":13} {"tag":"mcp.request","method":"tools/call","tool":"definition","is_error":false,"duration_us":1834,"request_id":13} ``` ## Summary - **Request tracking**: Every definition lookup starts with a `definition.lookup` INFO entry containing the symbol and file path. - **Result logging**: Successful resolutions emit `definition.found` with location details, while missing symbols trigger `definition.unresolved` WARN entries. - **Error handling**: Internal failures are captured as `definition.error` ERROR entries with specific error codes. - **Performance metrics**: The `mcp.request` tag records overall request duration and success status for all tool calls. - **Output format**: All logs are written as JSON Lines to the path specified by `CBM_INDEX_LOG`. ## Frequently Asked Questions ### Where does the MCP server write definition lookup logs? The server writes logs to the directory specified by the `CBM_INDEX_LOG` environment variable, typically defaulting to a logs subdirectory within the cache folder. Each log entry is a single line of JSON, making the logs easily searchable with tools like `jq` or `grep`. ### How can I distinguish between successful and failed definition lookups in the logs? Successful lookups emit the `definition.found` INFO tag, while failed lookups due to missing symbols emit the `definition.unresolved` WARN tag. Critical errors during processing use the `definition.error` ERROR tag. You can filter for these specific tags to separate successful resolutions from failures. ### Which source files contain the logging implementation for tool definition lookups? The core logging functions (`cbm_log_info`, `cbm_log_warn`, `cbm_log_error`) are implemented in [`src/foundation/log.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/log.c). The specific logging calls for definition lookups are located in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) within the `handle_definition_call` function, which coordinates the lookup process and emits the structured log entries. ### What information is included in the generic MCP request log for definition lookups? The `cbm_log_mcp_request` function records an INFO entry with the tag `mcp.request` that includes the RPC method name (`tools/call`), the tool name (`definition`), a boolean indicating if the request resulted in an error, and the total processing duration in microseconds. This provides a high-level view of request throughput and latency.