MCP server

The reference fleet ships an MCP server: templates/fleet/mcp/yen-mcp.sh. It answers agents over stdio (JSON-RPC 2.0, one message per line) by running yen queries on the fleet. It serves the fleet in its directory.

cd templates/fleet
nix run .#yen-mcp

Tools

This table is read from the server script itself (14 tools):

Tool	What it answers
`yen_schema`	Every kind, aspect and invariant of the fleet.
`yen_check`	Invariants: violations, incomplete, ok, and the why rules of each violation.
`yen_context`	One scope: parent, children, aspects, elements given and received, errors.
`yen_explain`	Why an aspect is active, inactive or undefined at a scope.
`yen_errors`	Error records, optionally only one code.
`yen_declared_in`	The files that answer a declaration path.
`yen_export`	The fleet as sorted N-Triples with sha256 and count. The agent decides whether to store it.
`yen_stage`	Evaluate a change (a module as JSON) without applying it: ok, errors, violations, diff, refused, sha.
`yen_queries`	The stored-query catalog: each query with its required and optional parameters.
`yen_ask`	Run a stored query by name with an args object. Errors (missing-param, unknown query) come back as the result.
`yen_impact`	The scopes an element of a scope reaches over routed elements, by depth.
`yen_labels`	Trust labels per aspect; with floor n, the edges whose aspect has trust below n.
`yen_why_not`	Whether an invariant atom is violated, and the why/whyNot rules for it.
`yen_program`	Dry-run a change program (list of op objects): valid, errors, ok, violations, diff.

Each answer is { complete; result }, or { complete = false; error }. A timeout is never an empty answer. Arguments reach Nix through a file and builtins.fromJSON, never through string interpolation.

Register it

Any MCP client that starts a stdio server can use it. For example, in an mcpServers config:

{ "mcpServers": { "yen": { "command": "nix", "args": [ "run", "/path/to/fleet#yen-mcp" ] } } }

Variable	Meaning
`YEN_FLEET`	the fleet directory (default: the parent of `mcp/`)
`YEN_FLAKE`	its flake ref (default: from the git top)
`YEN_TIMEOUT`	seconds per nix call (default 120)

Contribute Community Sponsor