Tracing & debugging MCP

Every editor spawns its own bookmark-context mcp process at session start, so several run at once and the OS process list can’t tell them apart.

Always on — /stats

GET /stats reports each process with client (cursor, claude-code, or unknown, inferred from the parent process chain), started_at, ppid, parent_name, and uptime_seconds. The extension’s memory tooltip in the status footer shows one line per MCP server. Nothing is written to disk.

Opt-in — spawn / exit events

BOOKMARK_CONTEXT_TRACE=1

or [trace] processes = true. Appends one line per process start and stop to ~/.local/share/bookmark-context/trace/processes.jsonl.

Opt-in — tool calls

BOOKMARK_CONTEXT_MCP_TRACE=1

or [trace] mcp_tools = true (also enabled by BOOKMARK_CONTEXT_TRACE=1). Appends tool name, duration, and outcome to trace/mcp-tools.jsonl.

Queries are recorded as a length, never text; a failure logs the exception type without its message. Both logs rotate at 1 MB and keep one .jsonl.1 archive. Environment variables override the config file.

Raw protocol

For a JSON-RPC problem rather than a behavioural one, run mcp_debug.py as a stdio proxy in place of the server:

{ "command": "python3", "args": ["/path/to/bookmark-context/mcp_debug.py"] }

It logs full message bodies — queries included — to /tmp/mcp_raw.log. Put the normal command back when you’re done.