io.github.ShuffzordPublished by GitHub account Shuffzordv0.9.2Updated Oct 29, 2026
Create and update roadmap tree nodes and statuses in the RoadRaven desktop app (must be running).
Connects an assistant to the RoadRaven desktop app so it can read, create, edit, move and delete roadmap tree nodes and update their status live.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
The MCP server and Claude Code plugin for RoadRaven, a local desktop app that shows your project's plan as a tree and updates it live as the work happens. The server gives an agent 21 tools to read the open roadmap, create, edit, move and delete nodes, and set their status. The plugin adds two skills that tell Claude how to use those tools to plan and run real work.
Source-available, FSL-1.1-MIT.
Every tool talks to the RoadRaven desktop app over a local connection on
127.0.0.1. With the app closed, tools return app_not_running; with no
roadmap open, no_file_loaded. The app only opens or saves files where you
already work, so a request for another path returns path_not_permitted.
Install the app first: see Install.
@roadraven/mcp from npm through npx, pinned to the plugin's exact version, as a local stdio MCP server.event-api.json in RoadRaven's user-data folder (~/.config/RoadRaven on Linux, %LOCALAPPDATA%\RoadRaven on Windows), which the desktop app writes with its local port.127.0.0.1, to read and edit the open roadmap. It sends nothing anywhere else and collects no telemetry.npx @roadraven/mcp init yourself: it offers to add a short RoadRaven section to a CLAUDE.md, and asks first.Three ways, easiest first.
Setup Wizard. Launch RoadRaven. The first-run Setup Wizard detects Claude Code and OpenCode and registers this server with one click. Re-open it from the ⚙ button in the top bar. If the Claude Code plugin below is already installed, the wizard defers to it.
Claude Code plugin. Requires Node.js >= 24. From inside Claude Code:
Any other MCP host. Requires Node.js >= 24. Pin the version that matches your installed app (the app warns on a major.minor mismatch):
To add a short RoadRaven section to a CLAUDE.md (it asks whether to use
the current project or ~/.claude/CLAUDE.md), run
npx -y @roadraven/[email protected] init.
The skills ship with the Claude Code plugin install only. The Setup Wizard
and npx paths give you the tools without them.
roadraven:orchestrate turns a request into a roadmap tree (goal,
phases, tasks), writes a brief per phase, hands each phase to a sub-agent,
re-runs your project's own checks to verify the result, and keeps node
status current while you watch.
roadraven:work-node is how one task gets done: claim a node, set it in
progress, checkpoint into its notes, touch only the files the brief names,
prove a fix with a failing test first, run the checks, report, set the final
status.
Both skills find your project's test, lint and build commands from its README, package manifest or CI config, so they work in any language. If the app is not running they ask you once to start it, then fall back to a markdown worklog and say so.
Source: plugins/claude-code/README.md at commit bf061a7
Update RoadRaven node status
Push a status update to a node. Requires the desktop app to be running and a roadmap loaded. Routes through the agent dispatcher so the change appears in the event-log drawer (Ctrl+Shift+L).
metanodeIdrequiredstatusrequiredexpectedRevisionCheck RoadRaven Event API
Returns the current Event API URL, PID, and startedAt — or an error if the app is not running.
Takes no parameters.
Get the loaded RoadRaven roadmap
Return the full schema tree from the desktop app, with live-event statuses merged in, plus the current `revision` (pass it as expectedRevision on writes to detect stale reads). Long roadmaps can exceed the tool-result limit, so trim the answer: for a long roadmap or for polling, pass omitNotes: true and hideCompleted: true; to read one phase, pass rootId (that node's id) and depth. A stub is one line { id, title, status, type, childCount } standing in for a node whose children are left out; read those children with rootId set to the stub's id. Notes can also be fetched with getNode/findNodes. Requires the app to be running and a file to be loaded.
depthrootIdomitNoteshideCompletedGet a single RoadRaven node
Return a node by UUID, with its immediate parent ID, full ancestor chain (root-to-parent), and the current roadmap `revision`. Status reflects the live overlay if a recent event landed.
nodeIdrequiredFind RoadRaven nodes by structured filter
Search nodes by AND-combined filter: titleContains (case-insensitive substring), status (one status, or a list of statuses to get e.g. all open work in one call), type, metaKey + metaValue, parentId. All fields optional. Set omitNotes for a short list without notes and timestamps. Returns matching nodes (without their children; use parentId or getNode for those) with their parent IDs.
typestatusmetaKeyparentIdmetaValueomitNotestitleContainsGet RoadRaven status configuration
Return the loaded roadmap's statusConfig array (display labels/colors for statuses). Agent mutations accept only core node statuses.
Takes no parameters.
Get RoadRaven type configuration
Return the loaded roadmap's typeConfig array (the valid node-type IDs and their visual configuration).
Takes no parameters.
Get the currently open RoadRaven file
Return filePath (or null if untitled), isUntitled flag, document title, and total nodeCount. Works even when no file is loaded — returns null filePath and isUntitled=false.
Takes no parameters.
Create a new RoadRaven node
Add a child node under parentId with the given title. Optional: id (UUID or slug — supply it when recovering/recreating a node so its identity stays stable and history/metadata continuity survives file churn; duplicate_id if it already exists), type, core status (defaults to not-started), notes (markdown), metadata. Returns the new node's id. Requires a loaded roadmap.
idtypenotestitlerequiredstatusmetadataparentIdrequiredexpectedRevisionCreate a new RoadRaven roadmap
Initialize an in-memory untitled schema (mirrors File > New). Optional: title, statusConfig, typeConfig. The agent must call saveFileAs to persist the new roadmap to disk.
titletypeConfigstatusConfigRename a RoadRaven node
Change a node's title.
titlerequirednodeIdrequiredexpectedRevisionUpdate a RoadRaven node's type
Change a node's type string. Use getTypeConfig to discover valid types.
typerequirednodeIdrequiredexpectedRevisionUpdate a RoadRaven node's notes
Set a node's notes string (markdown). mode "replace" (default) overwrites the entire notes field — pass an empty string to clear. mode "append" adds a blank line then your text after the existing notes; recommended for agent progress lines.
modenotesrequirednodeIdrequiredexpectedRevisionPatch a RoadRaven node's metadata (shallow merge)
Shallow-PATCH a node's metadata. Each key in `patch` overwrites the same key in node.metadata; null value deletes that key. Unlisted keys are preserved. Returns the final metadata object.
patchrequirednodeIdrequiredexpectedRevisionBatch-update RoadRaven nodes atomically
Apply up to 100 node updates (status, notes, metadata patch) in ONE atomic call — the roadmap revision advances exactly once for the whole batch and the response returns the final `revision` so you can chain further writes without re-reading. All-or-nothing: every item is validated first (node exists, status id in statusConfig); any failure returns batch_validation_failed with per-item {index, nodeId, code} and NOTHING is applied. Ideal for replaying a set of changes after stale_write: call getRoadmap once, rebuild all updates against the fresh tree, and resend the whole batch with expectedRevision.
updatesrequiredexpectedRevisionMove a RoadRaven node to a new parent
Re-parent a node to newParentId at optional position (0 = first child; omit = last child). Blocks cycles (cannot move into own subtree) and cross-$ref-boundary moves.
nodeIdrequiredpositionnewParentIdrequiredexpectedRevisionDelete a RoadRaven node
Delete a node. Leaf nodes delete immediately; non-leaf nodes require cascade:true (returns cascade_required with childCount otherwise). Cannot delete the last remaining root.
nodeIdrequiredcascadeexpectedRevisionSave the currently open RoadRaven file
Force-flush the autosave debouncer immediately. Returns ok or save_error. For untitled schemas, call saveFileAs first.
Takes no parameters.
Save the RoadRaven roadmap to a new path
Save the loaded roadmap to a new file path. Path must satisfy the same allowlist as user actions (within the loaded directory, or previously user-picked).
pathrequiredOpen a RoadRaven file by path
Flush any pending autosave, then load a roadmap file by path. Path must satisfy the path-allowlist (same as user actions). The agent may need to ask the user to open the target directory first.
pathrequiredFit the entire RoadRaven tree into the viewport
Compute a zoom + pan that fits all nodes into the viewport with margin. No-op when no roadmap is loaded. Used by automated demos / recordings to pull-back the camera; safe for live agent use too.
Takes no parameters.
Show a node in RoadRaven
Select a node, centre the camera on it, open its side panel and bring the RoadRaven window to the front. Where the window manager refuses to raise the window, the node is still selected. Use it to show the human the node you are on.
nodeIdrequired80% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Declare a license in the repository or the registry entry.
/plugin marketplace add Shuffzord/RoadRaven/plugin install roadraven@roadravenclaude mcp add -s user roadraven -- npx -y @roadraven/[email protected]Plan the CSV export feature as a roadmap in RoadRaven and run it phase by phase.Pick up the first not-started node in the open roadmap, do the work, and keep its status current.