MCP Tools
Yupana exposes its capabilities as MCP tools, over stdio and streamable-HTTP.
Tools use the yupana_* naming convention, alongside Bobbin's bobbin_* and
Quipu's quipu_* on the same agent.
A parallel REST HTTP API (a per-tool endpoint for the broker and other
non-MCP consumers) is served by the resident daemon (yupana daemon, FR-27/FR-31). With [yupana.serve] use_daemon = true, the graph tools
here become thin clients of the same resident engine.
Build with the mcp feature and run yupana serve (stdio) or yupana serve --http
(streamable-HTTP on [yupana.serve] mcp_http_port, default 3040).
cargo build --features mcp
yupana serve # stdio, for a local agent
yupana serve --http # streamable-HTTP at http://127.0.0.1:3040/mcp
Live tools
| Tool | Purpose |
|---|---|
yupana_status | Base ref, tenant, available tiers, Quipu settings |
yupana_symbols | Symbol tree for a file |
yupana_references | Definition site(s) of a symbol, by name or by position |
yupana_analyze | Files/symbols summary for a subtree |
yupana_callers | Direct callers of a symbol (who calls it) |
yupana_callees | Direct callees of a symbol (what it calls) |
yupana_communities | Densely-connected symbol clusters (deterministic Louvain, FR-9) |
yupana_impact | Blast radius — transitive callers, N hops; reconciles against a cochange set (FR-11) |
yupana_dataflow | Local data dependence; interprocedural: true opts into Rust CPG |
yupana_verify | Verdict on a proposed edit buffer, before you write it (FR-23/FR-24) |
yupana_promote | Promote a subtree's facts to Quipu — SHACL-validate, then write (needs the quipu feature) |
yupana_ingest | Load generic (non-code) facts into the hot board graph (FR-35; needs the game-state feature) |
yupana_guard | Check proposed orders against game-state policies (FR-37; needs the game-state feature) |
yupana_whatif | Speculative, uncommitted impact of an order set over the board (FR-38; needs the game-state feature) |
yupana_path_check | Conformance of a plan or work-in-progress against a blessed golden path under gp-grammar/1 (FR-41/FR-42; needs the golden-path feature) |
yupana_symbols enumerates the same code graph as callers and impact: the
expected root-matching resident daemon when available, otherwise the transient
multi-language graph. Relative and absolute paths within the analysis root are
accepted, including cached files deleted from the working tree. When the graph holds no symbols for a file, the tool returns an error;
that absence cannot distinguish an unindexed, unsupported or symbol-less file.
It never reports that such a file is empty. Each symbol retains its tier and
start line. End lines are served when known from the transient graph and omitted
when the resident protocol does not carry them; the tool does not re-parse a
newer file to invent extents for an older snapshot.
The last three are the game-state harness. They are registered on every
build, as yupana_promote is, and refuse with a message naming the feature when
it is absent — a tool that accepted a board and silently did nothing would be
worse than one that is missing, because the caller would believe it had guarded.
See The Game-State Harness.
yupana_references
Give it symbol or a position (at_file + at_line, plus optional
at_col), not both concerns at once.
Names over-connect: a real tree has twelve builds, and asking by name gets all
twelve. When you are reading code you know where you are, so point at it:
{ "at_file": "src/beta.rs", "at_line": 7 }
The position resolves to the innermost symbol enclosing that line, and the reply holds that symbol alone — it does not re-expand to every symbol sharing its name, which would restore the ambiguity the position was given to remove.
at_col is one-based and requests LSP precision. An LSP result carries complete
start/end line+column spans and tier: "lsp". With no language server or
resolvable build, the request degrades to the name-based tree-sitter result,
which may intentionally contain multiple same-named definitions and carries
tier: "treesitter". It never ignores the column while claiming precision.
Passing a partial position is an error.
Position requests always take the transient build, never the resident daemon:
/references does not carry the node spans a position needs.
yupana_verify
Pass the full proposed contents of a file; get back ok plus any violations.
Only violations the edit introduces are reported — the file's current contents
are the baseline, so pre-existing breakage is not blamed on the edit.
Always read unchecked alongside ok. At the tree-sitter tier there is no
type information, so type-violation is never decided, and method calls,
path-qualified calls, imports, locals, and closures are deliberately left alone
rather than guessed at. ok: true means "nothing this tier can see is wrong",
not "this compiles".
Every response carries a tier tag; structure-reading requests will accept a
tenant parameter as multi-tenancy lands (Phase 3).
CPG dataflow opt-in
yupana_dataflow accepts interprocedural: true in a build with mcp,cpg.
The function, var, forward, hops, and path selectors keep their roles;
the result becomes the CPG report described in CLI reference,
including source-qualified witness paths, control edges, diagnostics, and search
truncation. Both the report and its facts carry tier: "cpg". Omit the flag for
the existing intra-procedural response. Without cpg, requesting the flag returns
an error rather than silently substituting a tree-sitter answer.