log-probe-mcp

An agent-agnostic MCP server for hypothesis-driven, runtime-data-backed debugging.

Point any MCP-compatible coding agent (Claude Code, Cursor, etc.) at it and say something like:

Debug this using the log-probe mcp — checkout returns the wrong cart for some users.

log-probe-mcp never edits your code. Instead it runs a local HTTP log-ingestion server, correlates incoming logs to specific executions (a script run, a test invocation, a request), and tracks hypotheses — so the calling agent can drive the classic debugging loop (form hypotheses → instrument → reproduce → analyze → converge) with real runtime data instead of guessing from static code, and without a human manually copy-pasting console output back into the chat.

How it works

1. The agent calls probe_server_start to spin up a local HTTP server that accepts structured log events (POST /ingest).
2. It records a debugging session and a few falsifiable hypotheses (debug_session_create, hypothesis_create).
3. It fetches the logging contract (instrumentation_get_contract) and inserts a few log calls at the decision points that would distinguish between the hypotheses, using its own file-editing tools — log-probe-mcp only tells it what to send and where to send it, it never touches your source files itself.
4. It reproduces the bug, either by running a script/test itself (execution_run, which also captures stdout/stderr automatically) or by minting an execution for something already running (execution_create) and asking a human to trigger it.
5. It reads the real data back (execution_get_logs, execution_compare for flaky/intermittent bugs) and marks each hypothesis confirmed/refuted with evidence (hypothesis_update).
6. Once resolved, it applies the actual fix itself, removes the temporary instrumentation, and optionally writes a durable record (knowledge_base_export, debug_session_resolve).

Call debug_workflow_guide (or use the debug MCP prompt, on clients that support prompts) for the full step-by-step guidance an agent needs to run this loop well.

Installation / client config

{
  "mcpServers": {
    "log-probe": {
      "command": "npx",
      "args": ["-y", "log-probe-mcp"]
    }
  }
}

For local development against a checkout of this repo, build it and point a client directly at dist/bin.js:

{
  "mcpServers": {
    "log-probe": {
      "command": "node",
      "args": ["/absolute/path/to/log-probe-mcp/dist/bin.js"]
    }
  }
}

Data (the SQLite store and any exported knowledge-base files) lives under .log-probe/ in the project the agent is working in. Because MCP clients don't consistently launch servers with cwd set to the project root, the authoritative source is, in priority order: the dataDir argument to probe_server_start, the LOG_PROBE_DATA_DIR environment variable, then the server process's own cwd.

Tool surface

Tool	Purpose
probe_server_start / probe_server_stop / probe_server_status	Ingestion server lifecycle
debug_session_create / _list / _get / _resolve	Track a debugging investigation
hypothesis_create / _update / _list	Track falsifiable hypotheses and their evidence
execution_create / _run / _end / _list / _get_logs / _compare	Mint/run/query correlated executions
instrumentation_get_contract	The ingestion HTTP contract + ready-to-paste snippets per language
debug_workflow_guide	The hypothesis-driven methodology, full guide or per-stage
knowledge_base_export	Writes a durable markdown record of a session

Plus a debug MCP prompt for clients that support the prompts primitive — a thin wrapper around debug_workflow_guide's content, so guidance is reachable via tools everywhere regardless of prompt support.

Ingestion contract

Instrumented code sends a POST to <ingestion url>/ingest with a JSON body (single event, or an array of up to 500 for batching):

{
  "executionId": "exec_...",
  "hypothesisId": "hyp_...",
  "level": "info",
  "message": "cache key computed",
  "data": { "key": "route:/x" },
  "source": "checkout.ts:88"
}

executionId must already exist (minted via execution_create or execution_run) — this is what correlation is built on. Instrumentation should always be fire-and-forget with a short timeout; see instrumentation_get_contract for language-specific snippets that already do this correctly.

Known limitations

• The ingestion server binds 127.0.0.1 only and has no auth token — acceptable for a local dev tool, but don't run it anywhere multi-tenant or expose the port.
• One MCP server process serves one data directory for its lifetime; to point at a different project, restart/reconnect the client rather than changing dataDir mid-session.

Example

examples/buggy-node-service/ is a small, intentionally-buggy HTTP server for trying the full workflow end to end — see its README.

Development

npm install
npm run build       # compiles to dist/ and copies the SQL migration
npm run dev          # tsx watch, for iterating
npm run typecheck
npm test
npm run inspect       # build + launch the MCP inspector against dist/bin.js