MCP API Reference

All 31 tools. Parameters, types, CLI equivalents.
← Back to Quick Start & Tutorial

Graph CRUD

add_nodedeciduous add

Create a node in the decision graph.

Param	Type	Required	Description
`node_type`	string	Yes	goal, decision, option, action, outcome, observation, revisit
`title`	string	Yes	Node title
`description`	string		Longer description
`confidence`	int		0-100
`prompt`	string		Verbatim user prompt
`files`	string		Comma-separated file paths
`branch`	string		Git branch (auto-detected)
`commit`	string		Commit hash or "HEAD"

link_nodesdeciduous link

Create an edge between two nodes.

Param	Type	Required	Description
`from_id`	int	Yes	Source node ID
`to_id`	int	Yes	Target node ID
`rationale`	string		Why this connection exists
`edge_type`	string		leads_to, requires, chosen, rejected, blocks, enables

unlink_nodesdeciduous unlink

Remove an edge. Params: from_id, to_id (both required)

delete_nodedeciduous delete

Delete a node + edges. Params: node_id (req), dry_run (bool)

update_statusdeciduous status

Change status. Params: node_id, status (both required)

update_promptdeciduous prompt

Set prompt text. Params: node_id, prompt (both required)

Querying

list_nodesdeciduous nodes

List nodes with optional filters.

Param	Type	Description
`branch`	string	Filter by git branch
`node_type`	string	Filter by type
`status`	string	Filter by status
`theme`	string	Filter by theme name

search_nodesMCP-only

Full-text search across titles, descriptions, and prompts.

Param	Type	Required	Description
`query`	string	Yes	Search text
`node_type`	string		Filter results by type
`branch`	string		Filter results by branch

list_edgesdeciduous edges

All edges. No params.

show_nodedeciduous show

Detailed node view. Param: node_id (req)

get_graphdeciduous graph

Full graph JSON. No params.

Analysis

trace_chainMCP-only

BFS traversal from a node. Returns full connected subgraph with depth.

Param	Type	Required	Description
`node_id`	int	Yes	Start node
`max_depth`	int		0 = unlimited
`direction`	string		both, outgoing, incoming

get_node_contextMCP-only

Node's full neighborhood: parents, children, siblings, edges.

Param	Type	Required
`node_id`	int	Yes

get_timelinedeciduous archaeology timeline

Chronological view, newest first.

Param	Type	Description
`limit`	int	Max nodes (default 50, 0=all)
`node_type`	string	Filter by type
`branch`	string	Filter by branch
`since`	string	YYYY-MM-DD cutoff

get_pulsedeciduous pulse

Graph health: counts, active goals, orphans. Param: branch

find_orphansMCP-only

Nodes violating connection rules. No params.

get_branch_summaryMCP-only

All nodes on a branch, by type. Param: branch (req)

Sessions

start_sessionMCP-only

Begin a conversation session. Creates root goal; all add_node calls auto-associate.

Param	Type	Required	Description
`name`	string	Yes	Session name ("cowork: auth refactor")
`goal_title`	string	Yes	Root goal title
`goal_prompt`	string		Original user prompt (verbatim)

end_sessionMCP-only

Close active session. Param: summary (optional)

resume_sessionMCP-only

Reconnect to a previous session. Param: session_id (req)

get_sessionMCP-only

View session + nodes. Param: session_id (omit = current)

list_sessionsMCP-only

All sessions. Param: active_only (bool)

Documents & Themes

attach_documentdeciduous doc attach

Attach file to node. Params: node_id, file_path (req), description

list_documentsdeciduous doc list

List attachments. Param: node_id (omit = all)

create_themedeciduous themes create

Create theme. Params: name (req), color, description

list_themesdeciduous themes list

All themes. No params.

tag_nodedeciduous tag add

Tag a node. Params: node_id, theme (both req)

untag_nodedeciduous tag remove

Untag a node. Params: node_id, theme (both req)

Export

export_dotdeciduous dot

Export graph as DOT format for Graphviz visualization.

Param	Type	Description
`roots`	string	Root node IDs (comma-separated, traverses children)
`nodes`	string	Specific IDs or ranges ("1-11", "1,3,5")
`title`	string	Graph title
`rankdir`	string	TB or LR

generate_writeupdeciduous writeup

PR writeup. Params: title, roots, nodes, no_dot, no_test_plan

events_statusdeciduous events status

Multi-user sync status. No params.

Architecture

Functional core, imperative shell. Everything except the server loop is testable without IO.

Module	Role	IO
`protocol.rs`	JSON-RPC 2.0 + MCP message types, parsing, constructors	None
`tools.rs`	31 tool definitions with JSON Schema parameters	None
`handlers.rs`	Tool dispatch: (Database, Value) → Result<Value>	Database
`query.rs`	BFS, node context, timeline, pulse, orphans (pure)	None
`mod.rs`	Stdin/stdout loop, session state, MCP lifecycle	Stdin/stdout

108 MCP-specific tests. 272 total across the codebase.