MCP Tool Definition Lookup Logging in DeusData Codebase Memory

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 using the core logging helpers from src/foundation/log.c.

Request Initiation (definition.lookup)

When the handle_definition_call function in 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.

/* 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.

/* 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.

/* 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.

/* 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. This INFO-level entry uses the tag mcp.request and captures the RPC method, tool name, error status boolean, and processing duration in microseconds.

/* 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, which implements cbm_log_info, cbm_log_warn, and cbm_log_error. The definition-specific logging logic is implemented in 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 <cache_dir>/logs). You can inspect these logs using standard JSON processing tools.

To view only definition lookup initiations:

jq -c 'select(.tag=="definition.lookup")' $CBM_INDEX_LOG/*.log

To view all definition-related results including both successful finds and unresolved symbols:

jq -c 'select(.tag|startswith("definition."))' $CBM_INDEX_LOG/*.log

A complete request flow produces sequential entries like this:

{"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. The specific logging calls for definition lookups are located in 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.

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