MCP tools reference

gald3r mcp runs a minimal JSON-RPC 2.0 MCP server over stdio (gald3r_mcp, internal/mcpserver). Point any MCP-compatible client (Claude Code, Cursor, etc.) at it and it exposes the tools below via tools/list / tools/call.

Prompt & memory tools

Tool	What it does
gald3r_prompt_get	Fetch a prompt/judgment asset's rendered text (binds any ${slot} inputs). Shipped gald3r-internal assets are refused.
gald3r_prompt_list	List prompt/judgment assets (kind: persona|role|rubric|playbook|voice|rule).
gald3r_memory_recall	Chat-native recall over the file-first vault plus scoped memory records (user/project/workspace/team/company), merged into one token-budgeted result.

Code-graph tool (pillar 5, )

Tool	What it does
gald3r_explore	Explore the code graph: declarations, direct callers/callees, transitive blast radius ("what would break if this changed"), and — by default — the resolved file's own source content, all in one call. Mirrors gald3r graph explore (and its narrower CLI siblings graph impact/graph callers).

gald3r_explore is backed by gald3r_cartograph/graphquery — the SAME query implementation the gald3r graph explore|impact|callers CLI verbs call, so the MCP tool and the CLI can never report different answers for the same query. It reads pillar 4's committable graph artifact (gald3r_cartograph/graph/graph.jsonl, kept fresh automatically by gald3r worktree create's auto-rebuild hook, or built directly with cartograph-build); a missing artifact comes back as a domain-level tool result (isError: true) naming the exact command to run, not a JSON-RPC error.

Byte-parity guarantee: the source field in a gald3r_explore response is fetched through gald3r.ai/engine/tools/handlers.ReadFileHandler — the exact function backing gald3r's own read_file agent tool — so it is always byte-identical to a direct read_file call on the same file. There is only ever one file-reading code path in this codebase; a graph-mediated file view can never grow a second, subtly different one.

Argument	Type	Default	Notes
target	string	— (required)	A repo-relative file path, or a bare symbol name.
file	string	""	Disambiguates target when it names a symbol declared in more than one file.
depth	integer	3	Transitive blast-radius walk depth (hops).
max_nodes	integer	200	Cap on edges/files visited during the transitive walk.
include_source	boolean	true	Include the resolved file's own source content. Set false to skip the file read entirely.
graph_path	string	<project root>/gald3r_cartograph/graph/graph.jsonl	Override the graph artifact path.

When target names a symbol declared in more than one file and file does not disambiguate it, the response carries only query/ambiguous (the candidate declarations) — re-call with an explicit file.

Transitive queries (the impact field, and the standalone CLI graph impact) operate at FILE granularity rather than per-symbol: a raw call-site fact never records which declaration encloses it, so there is no fact to answer "which specific function three hops up would be affected" — only "which file would be affected". See gald3r_cartograph/graphquery's own doc.go for the full honesty note. Direct queries (callers/callees, depth 0) stay symbol-precise and carry the same confidence tier (EXTRACTED/INFERRED/AMBIGUOUS) pillars 2-3 already assigned — never upgraded, never invented.

Record-mutation tools (part of the record-mutation API)

A plain-language edit request ("pause task 42 and drop its score to 8") maps onto these SAME Mutate<Class> calls one layer up, via the project-agent resolution layer (gald3r_project/board/resolve) — see agent-record-edits.md for that contract and its current integration status.

One tool per .gald3r record class, each routing to the same typed Go mutation function (gald3r_project/board/ops or gald3r_project/board/artifact's Mutate<Class>) the CLI verbs and the autopilot dispatcher call — a <class>_update verb is a thin wrapper over the identical call, never parallel logic. Every tool's inputSchema is generated by reflection over the exact Go struct (<Class>UpdateFields) the corresponding Mutate<Class> function accepts, so the schema and the Go function can never drift apart. Only the fields you supply change — omitted fields are left untouched. uuid/created_date/created_at are never accepted: no UpdateFields struct carries a field for them, and a caller who tries anyway gets a named refused: immutable_field: ... error rather than a silently-dropped value.

Tool	Id parameter	Class	Notes
gald3r_task_update	task_id	Task	validates against task_file.v1.schema.yaml
gald3r_bug_update	bug_id	Bug	validates against bug_file.v1.schema.yaml
gald3r_adr_update	adr_id	Architecture Decision Record	supersedes/superseded_by are owned by the supersede workflow, not exposed here
gald3r_todo_update	todo_id	TO-DO	user_authorized (bool) is required — TO-DOs are user-write-only; the call is refused if it is missing or false, regardless of which other fields are supplied
gald3r_idea_update	idea_id	IDEA_BOARD.md idea	promoted_to is owned by the promote workflow, not exposed here
gald3r_decision_update	decision_id	DECISIONS.md ruling	supersedes/superseded_by are owned by the supersede workflow, not exposed here
gald3r_prd_update	prd_id	PRD	PRD Freeze Gate (C-019): a released/superseded PRD refuses every field change outright — use @g-prd-revise instead
gald3r_feature_update	feature_id	Staged feature	—
gald3r_subsystem_update	name	Subsystem spec	narrower field set (status/parent_system/parent_subsystem/min_tier) — children/dependencies/dependents/owners/locations are real file content this tool cannot reflect and are left byte-for-byte untouched
gald3r_release_update	release_id	Release spec	file-only (no DB row for this class yet)
gald3r_constraint_update	constraint_id	CONSTRAINTS.md row	severity must be block or warn
gald3r_document_update	kind	Singleton document	only kind: "project" (PROJECT.md) and kind: "plan" (PLAN.md) are mutable — every other document kind is a regenerated index and must never be hand-patched; frontmatter_scalars (required) is a key -> literal YAML scalar text map, so quote a string value yourself when the key needs it, e.g. {"status": "'active'"}

Example call

{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "gald3r_task_update",
    "arguments": { "task_id": "42", "status": "paused", "priority_score": 8 }
  }
}

Errors

A bad id, an unknown enum value, a missing required argument, or an attempt to set an immutable field all come back as a JSON-RPC -32602 Invalid params error carrying a machine-checkable reason: token (e.g. task_not_found, invalid_status, immutable_field, user_authorization_required) — never a silent no-op. An unexpected failure (a DB write error, a render failure) comes back as -32603 Internal error instead, so a client can tell "your input was wrong" apart from "something broke on the server side."

A missing .gald3r/ project root (resolved by walking up from the server process's working directory) is reported as a domain-level tool result (isError: true) rather than a JSON-RPC error, matching gald3r_memory_recall's existing convention.