API Reference

All 31 MCP tools exposed by the deciduous server, organized by category. Tools marked CLI have a direct CLI equivalent. Tools marked MCP-only are exclusive to the MCP server.

Graph CRUD

Tools for creating, connecting, and modifying nodes and edges.

add_node

Add a new node to the decision graph. CLI: deciduous add

Parameter	Type	Required	Description
`node_type`	string	Yes	`goal`, `decision`, `option`, `action`, `outcome`, `observation`, `revisit`
`title`	string	Yes	Node title
`description`	string		Longer description with more detail
`confidence`	integer		Confidence level 0-100
`prompt`	string		Verbatim user prompt (for context recovery)
`files`	string		Comma-separated list of associated files
`branch`	string		Git branch (auto-detected if omitted)
`commit`	string		Git commit hash, or `"HEAD"` to auto-detect

Example

add_node({ node_type: "goal", title: "Add search functionality", confidence: 90 })

{ "id": 42, "node_type": "goal", "title": "Add search functionality" }

link_nodes

Create an edge between two nodes. CLI: deciduous link

Parameter	Type	Required	Description
`from_id`	integer	Yes	Source node ID
`to_id`	integer	Yes	Target node ID
`rationale`	string		Reason for this connection
`edge_type`	string		`leads_to` (default), `requires`, `chosen`, `rejected`, `blocks`, `enables`

Example

link_nodes({ from_id: 1, to_id: 2, rationale: "possible approach", edge_type: "leads_to" })

{ "from_id": 1, "to_id": 2, "edge_type": "leads_to" }

unlink_nodes

Remove an edge between two nodes. CLI: deciduous unlink

Parameter	Type	Required	Description
`from_id`	integer	Yes	Source node ID
`to_id`	integer	Yes	Target node ID

delete_node

Delete a node and all its connected edges. CLI: deciduous delete

Parameter	Type	Required	Description
`node_id`	integer	Yes	ID of the node to delete
`dry_run`	boolean		If true, preview what would be deleted without deleting (default: false)

update_status

Change the status of a node. CLI: deciduous status

Parameter	Type	Required	Description
`node_id`	integer	Yes	Node ID to update
`status`	string	Yes	`pending`, `active`, `completed`, `rejected`, `superseded`, `abandoned`

update_prompt

Add or update the verbatim user prompt stored on a node. CLI: deciduous prompt

Parameter	Type	Required	Description
`node_id`	integer	Yes	Node ID to update
`prompt`	string	Yes	The verbatim user prompt text

Querying

Tools for listing, searching, and inspecting graph data.

list_nodes

List all nodes with optional filters. CLI: deciduous nodes

Parameter	Type	Description
`branch`	string	Filter by git branch
`node_type`	string	Filter by type (`goal`, `decision`, `option`, etc.)
`status`	string	Filter by status (`active`, `pending`, `completed`, etc.)
`theme`	string	Filter by theme name

list_edges

List all edges in the decision graph. CLI: deciduous edges

No parameters.

show_node

Show detailed information about a single node including connections, themes, and documents. CLI: deciduous show

Parameter	Type	Required	Description
`node_id`	integer	Yes	Node ID to display

get_graph

Export the full decision graph as JSON (all nodes and edges). CLI: deciduous graph

No parameters.

search_nodes

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

Parameter	Type	Required	Description
`query`	string	Yes	Search text (matched against title, description, and prompt)
`node_type`	string		Filter results by node type
`branch`	string		Filter results by branch

Example

search_nodes({ query: "authentication", node_type: "decision" })

{ "count": 3, "nodes": [ { "id": 45, "node_type": "decision", "title": "Choose Auth0 for OAuth" }, ... ]}

Analysis

Tools for traversing, tracing, and understanding the graph structure.

trace_chain

BFS traversal from a starting node. Returns the connected subgraph with depth. MCP-only

Parameter	Type	Required	Description
`node_id`	integer	Yes	Starting node ID
`max_depth`	integer		Maximum traversal depth (0 = unlimited, default: 0)
`direction`	string		`both` (default), `outgoing`, `incoming`

Example

trace_chain({ node_id: 1, direction: "outgoing", max_depth: 3 })

{ "start_node_id": 1, "node_count": 8, "edge_count": 9, "nodes": [ { "id": 1, "node_type": "goal", "title": "Add MCP server", "depth": 0 }, { "id": 2, "node_type": "option", "title": "Embedded server", "depth": 1 }, ... ]}

get_node_context

Get a node’s full neighborhood: the node itself, parents, children, siblings, themes, and documents. MCP-only

Parameter	Type	Required	Description
`node_id`	integer	Yes	Node ID to get context for

Example

get_node_context({ node_id: 45 })

Node: #45 [decision] "Choose embedded MCP server" (92%) Parents: #42 [option], #43 [option], #44 [option] Children: #46 [action], #47 [action], #48 [action]

get_timeline

Chronological view of nodes, newest first. CLI: deciduous archaeology timeline

Parameter	Type	Description
`limit`	integer	Max nodes to return (default: 50, 0 = all)
`node_type`	string	Filter by node type
`branch`	string	Filter by git branch
`since`	string	Only show nodes after this date (YYYY-MM-DD)

get_pulse

Graph health check: summary statistics, active goals, recent activity, orphans, and connection gaps. CLI: deciduous pulse

Parameter	Type	Required	Description
`branch`	string		Filter by git branch

Example

get_pulse({ branch: "main" })

total_nodes: 142 | total_edges: 198 By type: goal: 12, option: 28, decision: 15, action: 42, outcome: 38, observation: 7 Active goals: #1 "Build MVP", #89 "Add search", #120 "Migrate to Postgres"

find_orphans

Find nodes that violate connection rules (outcomes without parent actions, actions without parent decisions, etc.). Root goals are excluded since they are valid orphans. MCP-only

No parameters.

get_branch_summary

Summary of all decisions and activity on a specific git branch. MCP-only

Parameter	Type	Required	Description
`branch`	string	Yes	Git branch name to summarize

Sessions

Tools for managing conversation-scoped decision trees. All session tools are MCP-only.

start_session

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

Parameter	Type	Required	Description
`name`	string	Yes	Session name (e.g., `"cowork: auth refactor"`)
`goal_title`	string	Yes	Title for the root goal node
`goal_prompt`	string		Verbatim initial user prompt

Example

start_session({ name: "auth refactor", goal_title: "Refactor auth to OAuth2" })

{ "session_id": 3, "root_node_id": 42, "name": "auth refactor" }

end_session

Close the active session with an optional summary.

Parameter	Type	Required	Description
`summary`	string		Brief summary of what was accomplished

get_session

View a session’s details and all its nodes.

Parameter	Type	Required	Description
`session_id`	integer		Session ID to query (omit for current session)

resume_session

Reconnect to a previous session by ID. Use after breaks or server restarts.

Parameter	Type	Required	Description
`session_id`	integer	Yes	Session ID to resume

list_sessions

List all conversation sessions.

Parameter	Type	Required	Description
`active_only`	boolean		If true, only show sessions that haven’t ended (default: false)

Documents & Themes

Tools for attaching files and organizing nodes with tags.

attach_document

Attach a file to a decision graph node. CLI: deciduous doc attach

Parameter	Type	Required	Description
`node_id`	integer	Yes	Node ID to attach the file to
`file_path`	string	Yes	Path to the file to attach
`description`	string		Description of the document

list_documents

List documents attached to a node, or all documents. CLI: deciduous doc list

Parameter	Type	Required	Description
`node_id`	integer		Node ID to list documents for (omit for all)

create_theme

Create a new theme for tagging nodes. CLI: deciduous themes create

Parameter	Type	Required	Description
`name`	string	Yes	Theme name (lowercase, dash-separated)
`color`	string		Hex color code (default: `#6b7280`)
`description`	string		Theme description

list_themes

List all defined themes. CLI: deciduous themes list

No parameters.

tag_node

Add a theme tag to a node. CLI: deciduous tag add

Parameter	Type	Required	Description
`node_id`	integer	Yes	Node ID to tag
`theme`	string	Yes	Theme name to apply

untag_node

Remove a theme tag from a node. CLI: deciduous tag remove

Parameter	Type	Required	Description
`node_id`	integer	Yes	Node ID to untag
`theme`	string	Yes	Theme name to remove

Export

Tools for generating visualizations, writeups, and sync status.

export_dot

Export the decision graph as DOT format for Graphviz visualization. CLI: deciduous dot

Parameter	Type	Description
`roots`	string	Root node IDs (comma-separated) – traverses children
`nodes`	string	Specific IDs or ranges (e.g., `"1-11"` or `"1,3,5-10"`)
`title`	string	Graph title
`rankdir`	string	`TB` (top-bottom, default) or `LR` (left-right)

generate_writeup

Generate a PR writeup from the decision graph. Returns markdown. CLI: deciduous writeup

Parameter	Type	Description
`title`	string	PR title
`roots`	string	Root node IDs (comma-separated)
`nodes`	string	Specific node IDs or ranges
`no_dot`	boolean	Skip DOT graph section (default: false)
`no_test_plan`	boolean	Skip test plan section (default: false)

events_status

Show the status of event-based multi-user sync. CLI: deciduous events status

No parameters.

Tool Count by Category

Category	Count	MCP-only
Graph CRUD	6	0
Querying	5	1 (`search_nodes`)
Analysis	6	4 (`trace_chain`, `get_node_context`, `find_orphans`, `get_branch_summary`)
Sessions	5	5
Documents & Themes	6	0
Export	3	0
Total	31	10

Keyboard shortcuts

Deciduous