MCP Tools Reference

trurlic serve exposes 14 tools over stdio. Eight are read-only (concurrent, read lock); six mutate the graph (exclusive write lock + file lock, full-graph validation before commit). Every tool carries annotations; all are closed-world. Unknown tool names return isError: true.

Read tools

advance

The orchestration hub. Computes the next workflow step and returns the next action. Call before acting on a component and again after each action; the ready field is the only signal that implementation may begin.

Parameter	Type	Required	Description
component	string	Yes	Component name (kebab-case) or "project"
task_type	enum	No	new_component, feature, fix, learn, review, harden, bootstrap. Inferred from graph state if omitted.
mode	enum	No	agent or interactive. If omitted, advance returns requires_mode: true — present the choice to the user.
task	string	No	Task context passed through to step prompts
step_evidence	object	No	Map of step_name → evidence string. Gated (interactive) steps require ≥20 bytes.

Returns { step, action, requires_user_input, ready } (or requires_mode).

get_context

The architectural brief for a component: project-wide rules, component decisions, patterns, related decisions from connected components, and the override policy.

Parameter	Type	Required	Description
component	string	Yes	Component name or "project"
task	string	No	Current coding task description
depth	enum	No	full (default) or constraints (choice text only, ~60–70% fewer tokens)

get_architecture

Full system overview: components, connections, decision counts, patterns, and project-wide decisions. Flags components with zero decisions as needing design. No parameters.

check_pattern

Check whether an approach is already covered by existing decisions. Returns matching decisions by relevance, or a suggested_component if uncovered.

Parameter	Type	Required	Description
description	string	Yes	Pattern or approach to check

get_step_prompt

The prompt for a specific workflow step — system instructions, component context, and step focus. Called as directed by advance.

Parameter	Type	Required	Description
component	string	Yes	Component name or "project"
step	enum	Yes	One of the 16 workflow steps
mode	enum	Yes	agent or interactive (selects the prompt variant)
task	string	No	Task context
task_type	enum	No	Task type for variant prompts

get_decisions_for_file

Reverse lookup: given a file path, every decision whose code_refs reference it (exact match or directory prefix). Does not include project-wide rules — pair with get_context for full coverage.

Parameter	Type	Required	Description
file	string	Yes	Relative path or directory (e.g. src/store/write.rs or src/store). Absolute paths and .. are rejected.

get_decision_history

A decision’s current state (choice, reason, attribution, created) plus every prior version in chronological order and a revision count.

Parameter	Type	Required	Description
name	string	Yes	Decision name (without .toml)

verify_against_decisions

Call after implementing, before committing. Returns the decisions that apply to the files you changed, plus instructions to check each for compliance (verdicts: RESPECTED / VIOLATED / NEEDS_REVIEW). Project-wide rules are always included.

Parameter	Type	Required	Description
component	string	Yes	Component name or "project"
changed_files	string[]	Yes	Non-empty list of relative paths you changed. Absolute paths and .. are rejected.

Write tools

All write tools validate the full graph before committing. Invalid mutations are refused with a clear error.

record_decision

Record a single decision. Validates all edges, commits atomically, and returns the decision name, path, warnings, and any detected pattern opportunity.

Parameter	Type	Required	Description
component	string	Yes	Component name or "project"
choice	string	Yes	Concise decision title
reason	string	Yes	Reasoning behind the decision
attribution	enum	Yes	user (human present) or agent (autonomous)
alternatives	string[]	No	Rejected options with reasons
depends_on	string[]	No	Decision names this depends on
constrains	string[]	No	Decision names this constrains
tags	string[]	No	Categorical tags
code_refs	object[]	No	{ file, symbol? } locations. Agent mode should always include these.

record_pattern

Synthesize a reusable rule from two or more decisions.

Parameter	Type	Required	Description
name	string	Yes	Human-readable pattern name
description	string	Yes	What the pattern means
decisions	string[]	Yes	Decision names — must all exist, minimum 2
components	string[]	No	Component names (inferred from decisions if omitted)
tags	string[]	No	Categorical tags

update_decision

Modify a decision in place; its name and every edge survive unchanged.

Parameter	Type	Required	Description
name	string	Yes	Existing decision name
mode	enum	Yes	revise or promote
choice	string	No	New choice text (revise only)
reason	string	No	New reason text (revise only)
tags	string[]	No	New tags (revise only)
code_refs	object[]	No	New { file, symbol? } refs (revise only)

• revise — update content; the previous choice/reason is versioned into history.
• promote — mark an agent decision as human-reviewed (attribution → user). Only when the user has explicitly reviewed it; never autonomously, never in agent mode.

remove_decision

Remove a decision with cascade awareness. Refuses if others DependsOn it or a pattern would drop below two members; reports affected patterns and edges.

Parameter	Type	Required	Description
name	string	Yes	Decision filename (without .toml)

destructiveHint: true.

add_component

Parameter	Type	Required	Description
name	string	Yes	Kebab-case component name
description	string	No	One-line role summary

add_connection

Directional connection (data/control flow) that surfaces related decisions in get_context and get_step_prompt.

Parameter	Type	Required	Description
from	string	Yes	Source component name
to	string	Yes	Target component name