Skip to main content
Version: Next

MCP server (beta)

whodunit-mcp is a separate, read-only MCP server over the same Apache DevLake database the Grafana dashboards read. It lets any MCP-speaking agent — Claude Desktop, Claude Code, or another MCP client — ask for attribution data directly, without you running dun status or opening a dashboard.

Not released. This page describes what is built today, what is deliberately not built yet, and how to try it locally. Nothing here is a promise about a ship date.

What it does today​

Three tools, over stdio only — no HTTP listener, no network surface:

  • list_metrics — the catalog of available metrics, each with its parameters, chart type, and the caveat text that already ships on the Grafana panel it comes from.
  • run_metric — runs one catalog metric with bound parameters (never string-interpolated SQL) and returns rows plus the metric's chart type.
  • describe_schema — the tables a metric can touch, with the traps called out inline: nanosecond epochs, six status values not five, NULL is not zero.

Every metric comes from a committed catalog.json — 279 entries generated from the same 19 dashboards / panels the Grafana setup already validates, not from a model writing SQL against the schema. That is the core design decision behind this server: the risk isn't a wrong query, it's a plausible-sounding wrong number narrated with confidence (whodunit's own dashboard work found three of these — see Where each number comes from), and the fix is to route every answer through SQL that already passed that bar instead of generating new SQL per question.

What isn't built yet​

  • Known-empty detection. A metric backed by a structurally empty table (e.g. Change Failure Rate when incidents is empty) does not yet explain itself — it can still return a bare zero rather than "this requires configuration X, which isn't present."
  • The release gate. No foreign-instance proof yet (everything has only been tested against the maintainer's own DevLake), no documented privacy position for per-person queries, no catalog-drift CI tying the vendored catalog.json to a pinned whodunit revision — right now it's vendored from whodunit's working state as of 2026-09-10, unpinned.
  • A dedicated read-only database user. The server has a startup probe that refuses to run if it detects write access, but creating and documenting a proper GRANT SELECT-only MySQL user is still a manual step you do yourself (see the README's setup section), not something the project ships for you.

Try it locally​

Requires a running DevLake + Grafana stack (see DevLake setup) and Go to build the server.

git clone https://github.com/navjyotnishant/whodunit-mcp
cd whodunit-mcp
go build ./cmd/whodunit-mcp

Point it at your lake database with environment variables:

export WHODUNIT_MCP_LAKE_HOST=localhost
export WHODUNIT_MCP_LAKE_PORT=3306
export WHODUNIT_MCP_LAKE_USER=<read-only user you created>
export WHODUNIT_MCP_LAKE_PASSWORD=<password>
export WHODUNIT_MCP_LAKE_DATABASE=lake

Multiple databases on the same host (e.g. a lake_demo alongside lake) are supported via a comma-separated WHODUNIT_MCP_LAKE_DATABASES instead of the singular form — one host, one credential, several database names, not several hosts or credentials.

Wire the binary into an MCP client (Claude Desktop's config, or any other stdio MCP client) pointing at the built binary. A .mcpb bundle build (./mcpb/build.sh) is also in the repo for a packaged Claude Desktop extension.

Where this is going​

The remaining work is tracked as the "DevLake MCP server" epic. Phases 0 (baseline) and 1 (the catalog.json generator) live in whodunit's own repo and are done; this repo is Phase 2 (the server you can try above). Phases 3 (known-empty detection) and 4 (the release gate) are what's between here and a tagged release.