系统MCP平此

Environment variables

The server reads three env vars at runtime. The repository ships no machine-specific defaults: a path you don't set is a feature you don't use. Set them in the env block of your MCP host config (Claude Code: ~/.claude.json; Claude Desktop: claude_desktop_config.json) and, when you also use the wflow-do CLI from a shell, in your shell profile (~/.zshrc or ~/.bashrc).

Example MCP host env block (Claude Code or Desktop):

"env": {
  "WORKFLOWY_API_KEY": "<your token>",
  "SECONDBRAIN_DIR": "/absolute/path/to/secondBrain",
  "WORKFLOWY_INDEX_PATH": "/absolute/path/to/secondBrain/memory/name_index.json"
}

Example shell profile (so the CLI agrees with the MCP server):

export SECONDBRAIN_DIR="/absolute/path/to/secondBrain"
export WORKFLOWY_INDEX_PATH="$SECONDBRAIN_DIR/memory/name_index.json"

Neither path needs to be inside the user's home directory — a Dropbox / iCloud / Google Drive folder works as long as the host process can read and write it. Paths with spaces are fine in the MCP env block (JSON quoting handles it) and in the shell profile (the export line quotes the value).

---

Tool reference

The server exposes 41 tools. node_id accepts any of: full UUID (with or without hyphens), 12-char URL-suffix short hash, or 8-char prefix. parent_id (and any other parent-scoped argument) accepts null or omission as "workspace root" across the whole tool surface — create_node, batch_create_nodes, insert_content, list_children, and the rest behave the same way.

Native task completion. complete_node(node_id) toggles the Workflowy completed boolean — the legacy #done tag-as-completion workaround is deprecated for tasks. bulk_update(operation: "complete"|"uncomplete", filter: …) toggles a filtered set in one call; transaction accepts the same ops with rollback. Wire payload is POST /nodes/{id} with {"completed": true|false}.

Reordering siblings (reorder_nodes). Workflowy's move_node priority is position-relative-to-siblings and renormalises after every call, so a naive forward priority=0,1,2,… loop fights itself when you try to batch-reorder a set. reorder_nodes(parent_id, node_ids[]) takes the desired head-first order and walks it in reverse, issuing move_node with priority=0 per id — every move plants its node at position 0, the previously-planted nodes shift one step right, and after N moves the head of the parent's children is the requested sequence. Side effect: ids not currently under parent_id are reparented as part of the reorder (the primitive is built on move_node, not a sibling- only assertion). Capped at 200 ids per call. Returns Complete or Partial { reason: cancelled | timeout } with per-id `ok / error / skipped` entries; partial outcomes are safe to re-issue with the full list because each reverse-priority-0 move is idempotent. The orchestration lives once in crate::workflows::reorder_nodes_via_priority and is shared with wflow-do reorder --parent <id> --node <id> --node <id>.

Mirror creation (convention). Workflowy's REST API does not expose native mirror creation, so create_mirror(canonical_node_id, target_parent_id) implements the documented mirror_of: / canonical_of: note convention that audit_mirrors already understands: a new node is created under the target parent with the same name as the canonical, and its description carries mirror_of: <canonical_uuid>. Edits to the canonical do not propagate to the mirror — the link is structural and human-curated, not live. Pass an optional pillar to write a canonical_of: <pillar> marker to the canonical when it lacks one; existing markers are never overwritten. Pass dry_run=true to preview the resolved canonical, target_parent, and mirror name (verbatim copy of the canonical's name) without writing — useful when batching multiple mirror passes across a synthesis. The mirror's create + the optional canonical edit (and the dry-run preview) run through the shared crate::workflows module, the same code path the wflow-do create-mirror [--dry-run] CLI calls.

scope_resolved diagnostic field. Every tool that accepts an Option<NodeId> for parent_id (create_node, batch_create_nodes, insert_content, create_mirror, list_children, find_node, search_nodes) returns a scope_resolved field naming what the server actually targeted: workspace_root when the resolved scope was None (caller passed null or omitted), or scoped:<full-uuid> otherwise. Read this field after every call where parent_id was null/omitted to verify the server resolved to where you intended — pre-2026-05-09 callers had no way to audit this without inspecting the wire payload.

insert_content payload cap. The hard cap is 80 lines per call, lowered from 200 on 2026-05-04 after the failure-report 2026-05-03 session observed ≥80-line payloads failing at the MCP transport layer with no diagnostic. Above the cap, the call returns a typed error with a chunking instruction; chunk to ≤80 lines and pass the previous batch's last_inserted_id as the next call's parent_id to keep the hierarchy stitched together.

Truncation envelope. Every walk-shaped tool that emits JSON includes the same four fields when its 20 s walk budget fires:

{
  "truncated": true,
  "truncation_limit": 10000,
  "truncation_reason": "timeout",
  "truncation_recovery_hint": "Call build_name_index(parent_id=...) … then re-issue with use_index=true …"
}

Read truncation_reason and truncation_recovery_hint on every walk response. For name-based queries (search_nodes, find_node), use_index=true answers in O(1) from the persistent name index without burning the walk budget — populate it first with build_name_index(parent_id=<scope>). Index path is name-only; description-content matching still needs a live walk.

For large workspaces, prefer node_at_path (path of names → UUID, ~1 second on any tree size) and resolve_link (Workflowy URL + optional parent path → full node info) over search_nodes. They cost O(depth) API calls instead of O(tree).

Conventions parsed from node text:

- Tags: #inbox, #review, #urgent - Assignees: @alice, @bob - Due dates: due:2026-03-15, #due-2026-03-15, or bare 2026-03-15 (priority order)

---

Workflowy MCP Server

A Rust MCP server that gives Claude (Code, Desktop, or web) read/write access to your Workflowy graph, plus a generic template for turning that raw access into a working second brain.

There are two ways to use it:

1. Bare MCP server. Wire the binary into your MCP host and call the 41 tools directly. No templates, no opinions. 2. Second brain. Hand BOOTSTRAP.md to Claude. The assistant follows the script: builds the binary, wires the host, sets up your secondBrain directory at whatever path you choose (exposed to the server via $SECONDBRAIN_DIR), and installs the wflow skill that drives every subsequent session.

The methodology in option 2 is opinionated; the server itself is not. The repo only ships generic templates — your node IDs, drafts, and session logs live wherever $SECONDBRAIN_DIR points, never in this repo.

---