# RoadRaven (npm · @roadraven/mcp)

Create and update roadmap tree nodes and statuses in the RoadRaven desktop app (must be running).

- Trust score: 84/100 (high trust)
- Change this week: +38
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-10-17

## Components

- npm · `@roadraven/mcp`: 84/100 (this document), [markdown](https://verifymcp.io/servers/shuffzord-roadraven/roadraven-mcp.md), [page](https://verifymcp.io/servers/shuffzord-roadraven/roadraven-mcp)

## Channel facts

- Registry: `npm`
- Package: `@roadraven/mcp`
- Version: `0.9.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-10-17.

- **Supply Chain Security**: 98/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 31 of 92 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 84/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to Shuffzord/RoadRaven).
  - License check failed: the license (FSL-1.1-MIT) isn't a recognized OSI-approved license.
  - Actively maintained (last published 4 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 78/100
  - AI-judged instruction clarity (excellent).
  - Tool/resource definitions use about 1956 tokens (~88/item across 22 items; 22 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 60/100
  - Stability observed for 18 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 82/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 46% of tool parameters carry a description.
- **Tool Safety**: 75/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 0 of 1 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "deleteNode" implies "delete" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 22 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the RoadRaven MCP server?

RoadRaven runs locally as an npm package, launched with npx -y @roadraven/mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add shuffzord-roadraven -- npx -y @roadraven/mcp
```

### Cursor

```json
{
  "mcpServers": {
    "shuffzord-roadraven": {
      "command": "npx",
      "args": [
        "-y",
        "@roadraven/mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "shuffzord-roadraven": {
      "command": "npx",
      "args": [
        "-y",
        "@roadraven/mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add shuffzord-roadraven -- npx -y @roadraven/mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "shuffzord-roadraven": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@roadraven/mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add shuffzord-roadraven --command npx --arg -y --arg @roadraven/mcp
```

### Hermes

```yaml
mcp_servers:
  shuffzord-roadraven:
    command: "npx"
    args: ["-y", "@roadraven/mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "shuffzord-roadraven": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "@roadraven/mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add shuffzord-roadraven -t stdio -c npx -a -y @roadraven/mcp
```

### Other

```json
{
  "mcpServers": {
    "shuffzord-roadraven": {
      "command": "npx",
      "args": [
        "-y",
        "@roadraven/mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-10-17 (score 84, +1)

No change was recorded against any check on this day. Stability & Change Management went from 57 to 60. That category is still filling its 30-day observation window: 17 days of observed history at the previous scan, 18 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-15 (score 83, +1)

No change was recorded against any check on this day. Stability & Change Management went from 50 to 53. That category is still filling its 30-day observation window: 15 days of observed history at the previous scan, 16 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-13 (score 82, +36)

- [security improvement] Injection markers: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Stability: unverified → 0.47

### 2026-10-12 (score 46, 0)

- [security] Tool safety: Tool safety not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional] Capabilities: Protocol version not yet verified: we do not have a sandbox capture of the MCP handshake this version of the package performs yet.
- [functional] Tool coverage: Tool coverage not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- [functional] Schema quality: Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional] Package version: 0.8.7 → 0.9.0
- [functional] Package version: 0.8.7 → 0.8.9

### 2026-10-09 (score 46, −29)

- [security regression] Tool safety: pass → unverified
- [security] Stability: Stability not yet verified: this package could not be installed in a clean environment, so we have no schema to compare.
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Capabilities: pass → unverified
- [functional] First check of Schema quality: unverified

### 2026-09-30 (score 75, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-09-29 (score 60)

First indexed and scored.

## MCP tools (22)

### `updateNodeStatus` (~135 tokens)

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).

Input parameters:

- `expectedRevision` (integer): Revision from your last getRoadmap/getNode read. If the roadmap changed since, the write fails with stale_write instead of clobbering.
- `meta` (object): Arbitrary key-value metadata, e.g. { branch, commit, ci_run_id }
- `nodeId` (string, required): The node UUID from the roadmap
- `status` (string, required): Core node status

### `getEventApiStatus` (~33 tokens)

Check RoadRaven Event API

Returns the current Event API URL, PID, and startedAt — or an error if the app is not running.

### `getRoadmap` (~104 tokens)

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). Pass omitNotes: true for polling (large roadmaps exceed the tool-result limit): it leaves out notes and the createdAt/updatedAt timestamps; fetch notes with getNode/findNodes. Requires the app to be running and a file to be loaded.

Input parameters:

- `omitNotes` (boolean)

### `getNode` (~59 tokens)

Get 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.

Input parameters:

- `nodeId` (string, required): ID of the target node

### `findNodes` (~114 tokens)

Find RoadRaven nodes by structured filter

Search nodes by AND-combined filter: titleContains (case-insensitive substring), status, type, metaKey + metaValue, parentId. All fields optional. Returns matching nodes (without their children; use parentId or getNode for those) with their parent IDs.

Input parameters:

- `metaKey` (string)
- `metaValue`
- `parentId` (string)
- `status` (string)
- `titleContains` (string): Case-insensitive substring against node.title
- `type` (string)

### `getStatusConfig` (~32 tokens)

Get RoadRaven status configuration

Return the loaded roadmap's statusConfig array (display labels/colors for statuses). Agent mutations accept only core node statuses.

### `getTypeConfig` (~28 tokens)

Get RoadRaven type configuration

Return the loaded roadmap's typeConfig array (the valid node-type IDs and their visual configuration).

### `getOpenFile` (~50 tokens)

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.

### `createNode` (~269 tokens)

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.

Input parameters:

- `expectedRevision` (integer): Revision from your last getRoadmap/getNode read. If the roadmap changed since, the write fails with stale_write instead of clobbering.
- `id` (string): Optional caller-supplied node id (UUID or slug ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$). Use when recreating a node so its identity stays stable and history/metadata continuity survives file churn. Fails w…
- `metadata` (object)
- `notes` (string)
- `parentId` (string, required): ID of the parent node
- `status` (string): Core node status — defaults to not-started
- `title` (string, required): Node title
- `type` (string): Node type id

### `createRoadmap` (~71 tokens)

Create 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.

Input parameters:

- `statusConfig` (array)
- `title` (string)
- `typeConfig` (array)

### `renameNode` (~66 tokens)

Rename a RoadRaven node

Change a node's title.

Input parameters:

- `expectedRevision` (integer): Revision from your last getRoadmap/getNode read. If the roadmap changed since, the write fails with stale_write instead of clobbering.
- `nodeId` (string, required)
- `title` (string, required)

### `updateNodeType` (~77 tokens)

Update a RoadRaven node's type

Change a node's type string. Use getTypeConfig to discover valid types.

Input parameters:

- `expectedRevision` (integer): Revision from your last getRoadmap/getNode read. If the roadmap changed since, the write fails with stale_write instead of clobbering.
- `nodeId` (string, required)
- `type` (string, required)

### `updateNodeNotes` (~160 tokens)

Update 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.

Input parameters:

- `expectedRevision` (integer): Revision from your last getRoadmap/getNode read. If the roadmap changed since, the write fails with stale_write instead of clobbering.
- `mode` (string): How to combine with existing notes. "replace" (default) overwrites the entire notes field; "append" adds a blank line then your text after the existing notes — recommended for agent progress lines.
- `nodeId` (string, required)
- `notes` (string, required)

### `updateNodeMetadata` (~103 tokens)

Patch 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.

Input parameters:

- `expectedRevision` (integer): Revision from your last getRoadmap/getNode read. If the roadmap changed since, the write fails with stale_write instead of clobbering.
- `nodeId` (string, required)
- `patch` (object, required)

### `updateNodes` (~190 tokens)

Batch-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.

Input parameters:

- `expectedRevision` (integer): Revision from your last getRoadmap/getNode read. If the roadmap changed since, the write fails with stale_write instead of clobbering.
- `updates` (array, required): 1..100 node updates applied atomically as one change

### `moveNode` (~108 tokens)

Move 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.

Input parameters:

- `expectedRevision` (integer): Revision from your last getRoadmap/getNode read. If the roadmap changed since, the write fails with stale_write instead of clobbering.
- `newParentId` (string, required)
- `nodeId` (string, required)
- `position` (integer)

### `deleteNode` (~92 tokens)

Delete 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.

Input parameters:

- `cascade` (boolean)
- `expectedRevision` (integer): Revision from your last getRoadmap/getNode read. If the roadmap changed since, the write fails with stale_write instead of clobbering.
- `nodeId` (string, required)

### `saveFile` (~35 tokens)

Save the currently open RoadRaven file

Force-flush the autosave debouncer immediately. Returns ok or save_error. For untitled schemas, call saveFileAs first.

### `saveFileAs` (~47 tokens)

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).

Input parameters:

- `path` (string, required)

### `openFile` (~58 tokens)

Open 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.

Input parameters:

- `path` (string, required)

### `cameraFitView` (~51 tokens)

Fit 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.

### `revealNode` (~74 tokens)

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.

Input parameters:

- `nodeId` (string, required): ID of the target node

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/shuffzord-roadraven/roadraven-mcp#diagnostics

## Score history

- 2026-10-17: 84
- 2026-10-16: 83
- 2026-10-15: 83
- 2026-10-14: 82
- 2026-10-13: 82
- 2026-10-12: 46
- 2026-10-09: 46
- 2026-10-07: 75
- 2026-10-05: 75
- 2026-10-04: 75
- 2026-10-03: 75
- 2026-10-02: 75
- 2026-10-01: 75
- 2026-09-30: 75
- 2026-09-29: 60

## Common questions

### What is the RoadRaven MCP server?

RoadRaven is an MCP server listed in the public MCP registry as io.github.Shuffzord/roadraven. Create and update roadmap tree nodes and statuses in the RoadRaven desktop app (must be running). This page covers its npm package (@roadraven/mcp).

### Is the RoadRaven MCP server safe to use?

RoadRaven scores 84 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 17 October 2026. It declares no install or post-install scripts. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the RoadRaven MCP server expose?

RoadRaven exposes 22 tools: updateNodeStatus, getEventApiStatus, getRoadmap, getNode, findNodes, and 17 more. Their descriptions and schemas cost roughly 1,956 tokens of context every time the server is loaded.

### Is the RoadRaven MCP server still maintained?

RoadRaven is still listed as active in the MCP registry. We last reached this channel on 17 October 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the RoadRaven MCP server under?

RoadRaven declares the FSL-1.1-MIT licence, which is not on the OSI-approved list. Read the terms before using it at work, and note this covers the source only, not the cost of any service it calls.

## Links

- npm package: https://www.npmjs.com/package/@roadraven/mcp
- Socket report: https://socket.dev/npm/package/@roadraven/mcp
- Repository: https://github.com/Shuffzord/RoadRaven
- Website: https://shuffzord.github.io/RoadRaven/
- Changelog RSS feed: https://verifymcp.io/servers/shuffzord-roadraven/roadraven-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/shuffzord-roadraven/roadraven-mcp.json
- HTML version of this page: https://verifymcp.io/servers/shuffzord-roadraven/roadraven-mcp