MCP server

The same read-only query layer is available to IDEs and coding agents over the Model Context Protocol, so the why is one tool call away without shelling out. Install the extra and start a stdio server:

pip install 'whyfile[mcp]'
whyfile --mcp --graph graphify-out/graph.json

Register it with a client (Claude Code, Cursor, IDE agents). For Claude Code, add to .mcp.json at the project root (launch the server from the project root so a --base-style git diff resolves against your repo):

{
  "mcpServers": {
    "whyfile": {
      "command": "whyfile",
      "args": ["--mcp", "--graph", "graphify-out/graph.json"]
    }
  }
}

Seven intent_* tools are exposed: six read-only query tools plus one explicit write tool, each a thin wrapper over the CLI command of the same name, so a tool result is identical to its CLI counterpart’s JSON:

Tool	Inputs	What it does
`intent_explain`	`node`	Why is this node like this: the intent that motivates a code/doc node, or an intent node’s claim, rationale, alternatives, and relations.
`intent_list`	`kind?`, `min_confidence?`, `provenance?`	The intent inventory, optionally filtered.
`intent_why`	`question`, `top?`	Ranked intent matching a natural-language question.
`intent_changed`	`files[]` or `base`	The intent governing changed files, constraints first.
`intent_coverage`	(none)	Which code has recorded intent and which is dark.
`intent_digest`	`since`	What intent was added, removed, or superseded since a checkpoint.
`intent_capture` (write)	`chosen`, `rationale`, `question?`, `options?`, `recommendation?`	Persist a resolved decision as a record + a `captured` node, without shelling out.

The six query tools are read-only, LLM-free, and free at query time (they read the local graph, make no backend call). intent_capture is the one write tool (B5): it is explicit (a distinctly named tool, never a mode on a read tool), schema-validated, and scoped to capturing a decision, so the read-only guarantee of the others is unchanged. Results carry both a JSON body and MCP structuredContent; a real failure sets isError, while a missing intent layer returns a graceful no_intent_layer result rather than an error. The server only reads a local graph: no mutations, no pipeline runs, no secrets, safe to hand to any agent. See ADR-0018 for the design.

​MCP server

MCP server