Workflowy MCP Server

1# Workflowy MCP Server
2 
3A Rust MCP server that gives Claude (Code, Desktop, or web) read/write access
4to your Workflowy graph, plus a generic template for turning that raw access
5into a working second brain.
6 
7There are two ways to use it:
8 
91. **Bare MCP server.** Wire the binary into your MCP host and call the 26
10   tools directly. No templates, no opinions.
112. **Second brain.** Hand [`BOOTSTRAP.md`](BOOTSTRAP.md) to Claude. The
12   assistant follows the script: builds the binary, wires the host, sets up
13   `~/code/secondBrain/` for your specific data, and installs the wflow
14   skill that drives every subsequent session.
15 
16The methodology in option 2 is opinionated; the server itself is not. The
17repo only ships generic templates — your node IDs, drafts, and session logs
18live in `~/code/secondBrain/`, never in this repo.
19 
20---
21 
22## Quick install
23 
24```bash
25git clone https://github.com/dromologue/workflowyMCP.git ~/code/workflowy-mcp-server
26cd ~/code/workflowy-mcp-server
27cargo build --release
28echo "WORKFLOWY_API_KEY=<your-token>" > .env
29```
30 
31Wire the resulting `target/release/workflowy-mcp-server` into your MCP host:
32 
33- **Claude Code:** `claude mcp add workflowy -- $(pwd)/target/release/workflowy-mcp-server`
34- **Claude Desktop:** edit
35  `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
36  or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). See
37  [BOOTSTRAP.md](BOOTSTRAP.md) for the JSON shape.
38 
39Verify with `workflowy_status` — the host should return
40`status: "ok"`, `api_reachable: true`.
41 
42That's it for plain MCP usage.
43 
44---
45 
46## Set up the second brain (recommended)
47 
48Hand [`BOOTSTRAP.md`](BOOTSTRAP.md) to Claude. The assistant runs through
49six steps: build, wire the host, bootstrap `~/code/secondBrain/`, populate
50your structural node IDs, install the wflow skill, and (optionally)
51pre-warm the persistent name index. After bootstrap, the assistant follows
52[`templates/skills/wflow/SKILL.md`](templates/skills/wflow/SKILL.md) as the
53operating manual.
54 
55The detailed long-form walkthrough — multi-surface deployment, large-tree
56convergence, troubleshooting — lives in [`docs/SETUP.md`](docs/SETUP.md).
57 
58---
59 
60## What ships in this repo
61 
62```
63workflowyMCP/
64├── BOOTSTRAP.md              ← LLM-facing install script (hand to Claude)
65├── README.md                 ← this file
66├── docs/SETUP.md             ← long-form bootstrap notes
67├── specs/specification.md    ← authoritative behavioural spec
68├── templates/
69│   ├── secondbrain/          ← skeleton of ~/code/secondBrain/
70│   │   ├── README.md
71│   │   ├── memory/workflowy_node_links.md   (template; user fills in)
72│   │   ├── drafts/  session-logs/  briefs/
73│   └── skills/wflow/SKILL.md ← the operating manual the assistant follows
74└── src/                       ← Rust MCP server source
75```
76 
77User-specific data (node IDs, drafts, session logs, briefs) belongs in
78`~/code/secondBrain/`. The repo content stays generic so the next person
79who clones it gets a clean starting point.
80 
81---
82 
83## Tool reference
84 
85The server exposes 26 tools. `node_id` accepts any of: full UUID (with or
86without hyphens), 12-char URL-suffix short hash, or 8-char prefix.
87 
88| Category | Tools |
89|----------|-------|
90| Search & navigate | `node_at_path`, `resolve_link`, `search_nodes`, `find_node`, `get_node`, `list_children`, `tag_search`, `get_subtree`, `find_backlinks`, `path_of`, `find_by_tag_and_path` |
91| Create & edit | `create_node`, `batch_create_nodes`, `insert_content`, `smart_insert`, `convert_markdown`, `edit_node`, `move_node`, `delete_node`, `duplicate_node`, `create_from_template`, `bulk_update`, `bulk_tag`, `transaction`, `export_subtree` |
92| Todos & scheduling | `list_todos`, `list_upcoming`, `list_overdue`, `daily_review`, `since` |
93| Project management | `get_project_summary`, `get_recent_changes` |
94| Diagnostics & ops | `workflowy_status`, `health_check`, `cancel_all`, `build_name_index`, `audit_mirrors`, `review`, `get_recent_tool_calls` |
95 
96For large workspaces, prefer `node_at_path` (path of names → UUID, ~1 second
97on any tree size) and `resolve_link` (Workflowy URL + optional parent path
98→ full node info) over `search_nodes`. They cost O(depth) API calls instead
99of O(tree).
100 
101Conventions parsed from node text:
102 
103- Tags: `#inbox`, `#review`, `#urgent`
104- Assignees: `@alice`, `@bob`
105- Due dates: `due:2026-03-15`, `#due-2026-03-15`, or bare `2026-03-15`
106  (priority order)
107 
108---
109 
110## Reliability properties
111 
112Every API-touching handler runs inside a uniform `run_handler` wrapper
113that observes the server-wide cancel registry and applies a
114kind-appropriate wall-clock deadline:
115 
116| Tool kind | Budget | Examples |
117|-----------|--------|----------|
118| Read | 30 s | `get_node`, `list_children` |
119| Write | 15 s | `create_node`, `delete_node`, `edit_node` |
120| Bulk | 210 s | `insert_content`, `transaction`, `bulk_update`, `path_of`, `node_at_path` |
121| Walk | 20 s (internal) | `search_nodes`, `get_subtree`, `find_node` |
122 
123`cancel_all` interrupts any in-flight tool within ~50 ms. On budget
124expiry, bulk operations return a structured partial-success payload
125(`status: "partial"`, `created_count`, `last_inserted_id`, etc.) so the
126caller can resume — no "no result received" without diagnostic.
127 
128For the full list (transport-timeout retry, `authenticated`/`api_reachable`
129decoupling, `null` parameter handling, etc.) see
130[`specs/specification.md`](specs/specification.md). 272 lib tests pin the
131contracts, including 21 wiremock-driven failure-mode tests that run in
132under 2 seconds.
133 
134---
135 
136## CLI: `wflow-do`
137 
138A second binary exposes the same operations as a plain shell command.
139Useful as a fallback when the MCP transport drops.
140 
141```bash
142target/release/wflow-do status                              # liveness
143target/release/wflow-do search --query "concept maps"
144target/release/wflow-do --dry-run delete <uuid>             # preview
145target/release/wflow-do reindex --root <UUID> --root <UUID> # pre-warm index
146```
147 
148Subcommands: `status`, `get`, `children`, `create`, `move`, `delete`,
149`edit`, `search`, `audit-mirrors`, `review`, `index`, `reindex`. Use
150`--json` for raw output, `--dry-run` (write verbs only) to preview without
151calling the API.
152 
153---
154 
155## Development
156 
157```bash
158cargo build              # debug
159cargo build --release    # optimised
160cargo test --lib         # 272 unit tests
161cargo check              # type-check only
162```
163 
164Architectural overview: [CLAUDE.md](CLAUDE.md). Behavioural spec:
165[specs/specification.md](specs/specification.md).
166 
167---
168 
169## License
170 
171MIT
172