Skip to content
Back to search

hedgedoc-mcp

Unofficial MCP server for HedgeDoc 1.x: CAS-gated, verified edits to live notes without clobbering human editors.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/noblepayne--hedgedoc-mcp/badge.svg)](/listings/noblepayne--hedgedoc-mcp)

HTML

<a href="/listings/noblepayne--hedgedoc-mcp"><img src="/api/listings/noblepayne--hedgedoc-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Nix

nix run github:noblepayne/hedgedoc-mcp
nix profile install github:noblepayne/hedgedoc-mcp

The flake package carries Node, the compiled server, and a `hedgedoc-mcp` binary that starts the multi-note supervisor.

From source

The npm package is not published yet, so `npm install -g hedgedoc-mcp` does not work today. Build it from a clone instead:

git clone https://github.com/noblepayne/hedgedoc-mcp
cd hedgedoc-mcp
npm install
npm run build
node hedgedoc_mcp/multi.mjs

`npm run build` is `npx squint compile`, which writes `hedgedoc_mcp/*.mjs` from `src/hedgedoc_mcp/*.cljs`. The compiled output needs Node 20 or newer, and the `start` script runs the same entry point.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 435 lines
  1. # hedgedoc-mcp
  2. An MCP server that lets an agent read and edit live HedgeDoc 1.x notes without
  3. dropping a human's typing on the floor.
  4. HedgeDoc 1.x has no supported document write API. Every edit goes over its live OT socket
  5. (operational transformation, which merges concurrent edits), so an agent that
  6. reads a note, thinks for a minute, and writes the whole document back will erase
  7. whatever a person typed in between.
  8. This server sits between the agent and that socket. It gives the agent ordinary
  9. read and edit tools, and every write carries the revision it was based on
  10. (`rev`, the note's edit counter) and the content hash (`hash`, a digest of the
  11. note text). If the note moved, the write is refused and nothing is sent. By
  12. default, if it lands, the server reads the edited region back through
  13. HedgeDoc's download endpoint before reporting success.
  14. It was built for [LINUX Unplugged](https://linuxunplugged.com) show notes, where
  15. two hosts and an agent work on the same document before a show. Nothing in it is
  16. specific to that show, and it targets any HedgeDoc 1.12 note your account can
  17. edit.
  18. Unofficial client. Not affiliated with or endorsed by the HedgeDoc project.
  19. ## Status
  20. | Item | State |
  21. |---|---|
  22. | Version | `0.2.4` |
  23. | HedgeDoc 1.12 | Tested |
  24. | HedgeDoc 1.11 | Expected to work, not exercised yet |
  25. | HedgeDoc 1.10 and older | Refused at connect (they use Socket.IO 2) |
  26. | HedgeDoc 2 | Not supported |
  27. | Install | Nix is supported today; the npm package is not published yet |
  28. ## Requirements
  29. - A HedgeDoc 1.12 instance, reachable over HTTP or HTTPS. 1.11 should work
  30. but has not been exercised yet.
  31. - A registered account that can edit the target note. Use a dedicated bot
  32. account, not a person's login.
  33. - The note id, which is the last path segment of the note URL.
  34. - Node 20 or newer, or Nix.
  35. You do not need shell access to the HedgeDoc host, a server-side plugin, or a
  36. database connection.
  37. ## Install
  38. ### Nix
  39. ```bash
  40. nix run github:noblepayne/hedgedoc-mcp
  41. nix profile install github:noblepayne/hedgedoc-mcp
  42. ```
  43. The flake package carries Node, the compiled server, and a `hedgedoc-mcp`
  44. binary that starts the multi-note supervisor.
  45. ### From source
  46. The npm package is not published yet, so `npm install -g hedgedoc-mcp` does not
  47. work today. Build it from a clone instead:
  48. ```bash
  49. git clone https://github.com/noblepayne/hedgedoc-mcp
  50. cd hedgedoc-mcp
  51. npm install
  52. npm run build
  53. node hedgedoc_mcp/multi.mjs
  54. ```
  55. `npm run build` is `npx squint compile`, which writes `hedgedoc_mcp/*.mjs` from
  56. `src/hedgedoc_mcp/*.cljs`. The compiled output needs Node 20 or newer, and the
  57. `start` script runs the same entry point.
  58. ## Configure
  59. The server takes settings from the environment and nothing else. Point it at an
  60. instance and a note, then give your MCP client a stdio entry.
  61. OpenCode, in a project `opencode.json` or the global config:
  62. ```json
  63. {
  64. "mcp": {
  65. "hedgedoc": {
  66. "type": "local",
  67. "command": ["hedgedoc-mcp"],
  68. "environment": {
  69. "HEDGEDOC_URL": "https://hedgedoc.example.com",
  70. "HEDGEDOC_EMAIL": "bot@example.com",
  71. "HEDGEDOC_PASSWORD": "…",
  72. "HEDGEDOC_NOTE_ID": "<note-id>"
  73. }
  74. }
  75. }
  76. }
  77. ```
  78. Claude Desktop and other clients that use `mcpServers`:
  79. ```json
  80. {
  81. "mcpServers": {
  82. "hedgedoc": {
  83. "command": "hedgedoc-mcp",
  84. "env": {
  85. "HEDGEDOC_URL": "https://hedgedoc.example.com",
  86. "HEDGEDOC_EMAIL": "bot@example.com",
  87. "HEDGEDOC_PASSWORD": "…",
  88. "HEDGEDOC_NOTE_ID": "<note-id>"
  89. }
  90. }
  91. }
  92. }
  93. ```
  94. Restart the client after adding the entry. The tools appear under the server
  95. name you chose.
  96. `HEDGEDOC_NOTE_ID` sets a default note. You can omit it and pass `note-id` on
  97. every call instead, which is useful when the agent should not have a default
  98. target. Set `HEDGEDOC_MAX_NOTES` to cap how many notes one server process may
  99. open.
  100. ### Variables
  101. | Variable | Required | Notes |
  102. |---|---|---|
  103. | `HEDGEDOC_URL` | yes | Instance URL. A subpath such as `https://host/notes` works. |
  104. | `HEDGEDOC_NOTE_ID` | no | Default note. Required by the single-note `core.mjs`, optional in the default multi-note binary. |
  105. | `HEDGEDOC_EMAIL` / `HEDGEDOC_PASSWORD` | auth | Preferred. The server logs in and refreshes the session. `HEDGEDOC_USER` is an alias for the email. |
  106. | `HEDGEDOC_COOKIE` | auth | Full cookie pair, `connect.sid=<value>`, for when you have no password. |
  107. | `HEDGEDOC_CLIENT_MAJOR` | no | `4` (default). |
  108. | `HEDGEDOC_TRANSPORTS` | no | `websocket` (default), `polling`, or `websocket,polling`. |
  109. | `HEDGEDOC_POLL_TIMEOUT_MS` | no | Budget for confirming a write, in ms. Default 10000. |
  110. | `HEDGEDOC_POLL_MS` | no | Poll interval, in ms. Default 500. |
  111. | `HEDGEDOC_MAX_NOTES` | no | Worker cap in the multi-note binary. Default 32. |
  112. | `HEDGEDOC_IDLE_MS` | no | Presence idle threshold, in ms. Default 30000. |
  113. | `HEDGEDOC_ALLOW_GUEST_WRITES` | no | Allow writes over a guest session. Most HedgeDoc 1.12 instances still refuse the room join. |
  114. | `HEDGEDOC_ENABLE_SET_NOTE` | no | Expose the gated whole-document replace tool. |
  115. Auth is email plus password, a session cookie, or a guest session for reads.
  116. Guest writes are best effort: on 1.11 and 1.12 a guest usually cannot join the
  117. OT room, so use a registered bot account for edits.
  118. ## First edit
  119. Start the client and give the agent the note id. A useful first prompt:
  120. > Use the `hedgedoc` tools for note `<note-id>`. Call `get-status` until the rev
  121. > is no longer -1, read the section you want to change, and dry-run a line edit.
  122. > Show me the preview and do not write until I say so.
  123. The first `get-status` can return `rev: -1` and `connected: false` while the
  124. server logs in and joins the note. Call it again after a second, or pass
  125. `waitMs: 5000` to hold the call until boot lands. `waitMs` takes an integer from
  126. 0 to 15000 and defaults to 0. The wait costs wall-clock time on that call, at
  127. most the number you pass.
  128. `writable` tells you whether a write can go out now: the revision is known, the
  129. socket is connected, and the session may join the OT room. A cold or
  130. disconnected worker returns `writable: false` with a `hint` that says it is
  131. still booting. That is normal while the backend is down, not an error, and the
  132. status is still complete, with `rev: -1` before boot. `rev-known` reports the
  133. revision on its own, and `waitedMs` reports how long the wait took.
  134. A dry run returns a window of numbered lines around the edit and writes nothing.
  135. Pass `preview: "region"` to see the whole affected range, or `preview: "tail"`
  136. for its last 12 lines. `window` is the default and keeps the six-line radius.
  137. The example is abridged. The full result also carries `would-be-hash`,
  138. `preview-lines`, and `ops`, and it has no `new-rev` because nothing was emitted.
  139. ```json
  140. {
  141. "dry-run": true,
  142. "status": "dry-run",
  143. "written": false,
  144. "base-rev": 4,
  145. "base-hash": "ab23c794…",
  146. "preview": "72 | the line before\n73 | the edited line\n74 | the line after",
  147. "hint": "no write was emitted; rev and hash are the current base"
  148. }
  149. ```
  150. A dry run on the five write tools also returns `preview-mode` (the mode you
  151. asked for), `preview-lines` (`start-line` and `end-line` for the returned
  152. window), `preview-total-lines` (lines in the affected range before truncation),
  153. and `preview-truncated` (true when the mode does not show the whole range). A
  154. preview stops at 200 lines or 4000 UTF-16 units of rendered text, whichever
  155. comes first, and it keeps whole lines. These keys appear on dry runs only; an
  156. actual write keeps the success shape below.
  157. If the preview looks right, call the same tool with `dryRun: false`. A write that
  158. lands reports how the server checked it:
  159. ```json
  160. {
  161. "status": "confirmed",
  162. "verified": "download-poll",
  163. "new-rev": 5,
  164. "new-hash": "dc19bc80…"
  165. }
  166. ```
  167. The full result adds `preview`, `via`, and `op-id`.
  168. | `verified` | Meaning |
  169. |---|---|
  170. | `download-poll` | The edited region was read back from HedgeDoc's `/download` endpoint. |
  171. | `ack` | `verify: false`. The server waits up to 1.5 s for the revision to advance and its local copy of the note to hold the new content, without polling the document. |
  172. A timeout is `status: applied-but-unconfirmed`, not success: the op may have
  173. landed. Re-read the note and decide from there.
  174. ## How writes are gated
  175. ### Compare and swap (CAS) inside the server
  176. Every write takes `base-rev` and `base-hash` from a fresh read. Before emitting,
  177. the server compares both against its current view of the note. If either moved,
  178. the write is refused with the current values and nothing goes out. The wire
  179. protocol has no `base-hash`, so the comparison happens inside this server; the
  180. `/download` poll is the durability check.
  181. ### One emit per write
  182. If the poll cannot confirm the write, the tool says so and stops. A timeout is
  183. `applied-but-unconfirmed`, not proof that the first op failed, so it is not
  184. retried automatically. Retries are only for failures that happen before the op
  185. leaves the socket. Re-read and decide.
  186. ### Per-socket revisions
  187. A reconnect invalidates the local revision, and writes are refused with
  188. `rev-unknown` until a `doc` frame supplies the new one. After a resync the server
  189. rejoins; it does not guess the revision.
  190. ### Serialized writes
  191. A second write on the same note while one is running is rejected with
  192. `emit-in-flight`. Wait for the first to finish.
  193. ### One worker per note
  194. The default binary runs an isolated core process for each note, so notes do not
  195. share a socket, revision state, or in-flight write.
  196. ### Errors and retry advice
  197. A tool error carries `code`, `message`, and `data`. Five codes add a top-level
  198. `retryable` flag next to those keys:
  199. | Code | `retryable` | `retryAfterMs` |
  200. |---|---|---|
  201. | `not-connected` | true | 1000 |
  202. | `rev-unknown` | false | absent |
  203. | `stale-revision` | false | absent |
  204. | `emit-in-flight` | false | absent |
  205. | `write-needs-user` | false | absent |
  206. `download-failed` and every other error code carry no retry fields, so a client
  207. that reads `retryable` sees it absent rather than false. A `stale-revision` or
  208. `rev-unknown` write needs a fresh read and a rebuilt base, not a retry of the
  209. same one. `not-connected` is the code where a bounded retry after a second is
  210. the intended behavior.
  211. `applied-but-unconfirmed` is a result, not an error. It has `retryable: false`
  212. and stays under `status`, because the op may have landed. Re-read the note and
  213. decide; a blind re-emit can duplicate the edit.
  214. ## Tools
  215. | Tool | What it does |
  216. |---|---|
  217. | `get-status` | Reports revision, hash, headings, idle time, rev velocity, auth kind, connection state, `writable`, and worker/socket diagnostics. `waitMs` waits and triggers a throttled reconnect; `forceReconnect` disposes and reconnects now. |
  218. | `read-section` | Returns one heading's content with UTF-16 offsets. `occurrence` picks among duplicate headings, `level` narrows by heading level, and `includeSubsections` reads the whole subtree. A subtree read can be written back with the same flags. |
  219. | `read-note` | Returns the note, or a page of lines, with front matter and heading line numbers. `sections` controls the heading list. |
  220. | `apply-ops` | Writes raw ops under CAS, or replaces a section body via `new-section-text` plus `heading`. `includeSubsections` replaces the whole subtree. |
  221. | `append-to-section` | Inserts a block at the end of a section, before the next heading. `includeSubsections` appends after the last child. |
  222. | `replace-lines` | Applies batch single-line edits with an `old` match, bottom-up. |
  223. | `replace-range` | Replaces a 1-based line range with one or more lines, exact `oldText`, one CAS write. |
  224. | `insert-lines` | Inserts before a line. `total+1` appends. |
  225. | `delete-lines` | Deletes a line range, one line by default. Refuses to run past the end of the note. |
  226. | `search` | Searches lines by substring or regex, case insensitive by default. |
  227. | `presence` | Reports users and selection data, advisory only; the gate is the pre-emit overlap check inside `apply-ops`. |
  228. | `list-notes` | Lists notes with a live worker, the default note, and a `workers` array with pid, version, connected, writable, last connect, and reconnect attempts. |
  229. | `doctor` | Read-only health report in multi mode: server status, per-worker socket/rev/hash, heartbeat registry, duplicate note ids, and version mismatch. It never kills or reaps. |
  230. | `set-note` | Replaces the whole document under the gate; only with `HEDGEDOC_ENABLE_SET_NOTE`. |
  231. ### Arguments
  232. | Argument | Tools | Notes |
  233. |---|---|---|
  234. | `note-id` | Every tool except `list-notes` and `doctor`, in the multi-note binary | Selects the worker. The single-note `core.mjs` rejects it. |
  235. | `waitMs` | `get-status` | Integer 0..15000, default 0. Waits up to that many ms for boot to land and triggers a throttled reconnect while disconnected, then returns the status with `waitedMs`. |
  236. | `forceReconnect` | `get-status` | Boolean. Disposes the socket and reconnects now. Refuses with `force-reconnect-blocked` while a write is in flight. |
  237. | `level`, `includeSubsections` | `read-section`, `apply-ops`, `append-to-section` | `level` is 1..6 and filters without a fallback. `includeSubsections: true` reads or writes from after the heading line to the next heading at or above that level, or to the document end. A subtree read returns `writeRoundTrip: true` and echoes `heading`, `level`, `occurrence`, and `includeSubsections`; there is no nested anchor object. Raw ops plus either flag is `bad-args`. |
  238. | `sections` | `read-note` | `"all"` (default), `"none"`, or `"window"` for headings inside the returned slice. A boolean is rejected with a hint to use `"none"`. `get-status` still returns every heading. |
  239. | `base-rev`, `base-hash` | Every write | Taken from a fresh read. A stale base is refused. |
  240. | `startLine`, `endLine`, `oldText`, `newText` | `replace-range` | Inclusive 1-based range. `oldText` is the lines joined by `\n`, no trailing newline. `newText` may be multi-line; blank deletes the range. |
  241. | `dryRun` | Write tools | Returns a numbered preview with `status: dry-run` and `written: false`, and emits nothing. Aliases: `dry-run`, `dry_run`, `dry-run?`. |
  242. | `preview` | `apply-ops`, `append-to-section`, `replace-lines`, `replace-range`, `insert-lines`, `delete-lines` | Dry-run only: `"window"` (default, six-line radius around the target), `"region"` (the whole affected range), or `"tail"` (its last 12 lines). `set-note` does not take it. |
  243. | `verify` | Write tools | `false` skips the download poll and reports `verified: ack` once the revision has advanced and the intended content is visible locally. Alias: `verify?`. |
  244. | `regex`, `caseSensitive` | `search` | Aliases: `regex?`, `case-sensitive?`. |
  245. | `force`, `reason` | `set-note` | Required. `set-note` takes none of the flags above. |
  246. Use the camelCase names. The older spellings still parse, so clients written
  247. against 0.2.0 keep working, and a conflict between an alias and its canonical
  248. spelling is rejected as `bad-args`.
  249. Typical loop: `get-status`, then `read-note` or `read-section`, then a dry run,
  250. then the write. On `stale-revision`, read again and use the new rev and hash. On
  251. `applied-but-unconfirmed`, re-read before doing anything else.
  252. ## Reconnect and retries
  253. `retryable` and `retryAfterMs` are advisory. There is no automatic write retry.
  254. A write that emitted may have landed; a client must re-read before deciding.
  255. | Result | Safe action |
  256. |---|---|
  257. | `not-connected` | Retry after `retryAfterMs`, or call `get-status` with `waitMs` first. |
  258. | `emit-in-flight` | Read status, wait for the in-flight write to settle. Never re-emit. |
  259. | `applied-but-unconfirmed` | Re-read. If the rev did not advance, decide. Do not blind re-emit. |
  260. | `stale-revision`, `rev-unknown` | Fresh read, rebuild the edit, new op. |
  261. | `rate-limited` | Retry after `retryAfterMs`; no note was created. |
  262. | `create-unknown` | Operator checks the instance's recent notes. Never retry the POST. |
  263. `get-status` with `waitMs` triggers a throttled reconnect while disconnected.
  264. `forceReconnect: true` disposes and reconnects now, but refuses while a write is
  265. in flight so the ack cannot be orphaned.
  266. ## Troubleshooting
  267. | Result | What to do |
  268. |---|---|
  269. | `rev: -1`, `connected: false`, `writable: false` | The worker is still booting. Call `get-status` again, or pass `waitMs`. A down backend keeps `writable` false without failing the call. |
  270. | `rev-unknown` | The socket reconnected. Call `get-status` and wait for a doc frame. |
  271. | `not-connected` | The socket is down. `retryable` is true and `retryAfterMs` is 1000, so a retry after a second is expected. |
  272. | `stale-revision` | The note moved. Read again and use the new rev and hash. |
  273. | `line-mismatch` | The `old` line is not there anymore. Read the note and fix the edit. |
  274. | `applied-but-unconfirmed` | Re-read before doing anything else. Do not re-emit blindly. |
  275. | `emit-in-flight` | Another write is running. Wait for it to finish. |
  276. | `write-needs-user` | You are a guest. Use the bot account. |
  277. | `range-mismatch` | `oldText` is not the current text of those lines. Read again and rebuild it. CRLF input fails with an LF hint. |
  278. | `range-out-of-range` | `startLine`/`endLine` are inverted or outside the note. Read the line count and retry. |
  279. | 401 or `unauthorized` | Check the email, password, or cookie. |
  280. | `oversize` | The write would pass 100 KB. Split it or edit a smaller region. |
  281. | `download-failed` | Check `HEDGEDOC_URL`, the note id, the cookie, and reachability. |
  282. ## Limits
  283. - CAS runs inside this server. The wire protocol has no `base-hash`, so the gate
  284. compares against the local copy this server keeps.
  285. - A write whose result would exceed 100 KB is refused. Larger notes can still be read.
  286. - ATX headings and backtick fences are recognized. Setext headings and `~~~`
  287. fences are not. An indented ATX heading is not recognized either, so it does
  288. not end a subtree read.
  289. - A subtree append lands after the last child, so the added text reads as part
  290. of that child. That is inherent to the requested semantics; use the child
  291. heading directly if the text belongs to the parent.
  292. - `length` counts the returned lines joined by `\n`, excluding the newline that
  293. ends the last returned line. `doc-length` includes the single trailing
  294. newline. `read-section` includes that newline when the section is last.
  295. - `new-section-text` constructs one blank line after the heading, then the body
  296. with leading and trailing blank lines stripped. A body starting with `-`, `+`,
  297. text, or a fence keeps the conventional blank line. Empty text produces only
  298. that blank line, or `## H` followed by the next heading when the section is
  299. last. A read-then-restore is stable after one pass; the second restore is a
  300. `no-op`.
  301. - There is no undo. HedgeDoc's own history is the recovery path.
  302. - HedgeDoc 2 is not supported.
  303. - `search` with `regex: true` uses JavaScript's backtracking engine. A
  304. pathological pattern on a very long line can block the worker; the multi-note
  305. supervisor recycles it after 180 seconds. Prefer substrings for untrusted
  306. patterns.
  307. ## Security
  308. - Use a dedicated bot account with edit rights only on the notes it needs. Do
  309. not use a person's primary login.
  310. - Passwords are not logged. Logs carry note ids, revisions, error codes, the
  311. target URL, and the account display name.
  312. - The server speaks stdio. It does not listen on a port.
  313. - `set-note` is off unless explicitly enabled, and requires `force` and
  314. `reason`.
  315. - Rotate the bot password if it leaks.
  316. ## Development
  317. ```bash
  318. npm install
  319. npm run build
  320. npm run test:pbt
  321. node test/snapshot-gc.mjs
  322. node test/retry-safety.mjs
  323. node test/remote-op-fold.mjs
  324. node test/bin-launch.mjs
  325. node test/arg-validation.mjs
  326. npm run test:socket
  327. npm run test:diagnostics
  328. ./scripts/e2e.sh
  329. nix flake check
  330. ```
  331. [`scripts/e2e.sh`](scripts/e2e.sh) brings up a disposable HedgeDoc with
  332. `podman-compose` if `127.0.0.1:3000/status` is not already answering, registers
  333. `bot@dev.local`, and needs open registration on the instance. Set `HEDGEDOC_URL`
  334. to use an existing dev instance instead.
  335. `test/reconnect-live.mjs` restarts the dev app container and proves the worker
  336. reconnects and writes without a session restart. It is deliberately outside the
  337. default e2e path because it restarts the dev container, and it refuses to run
  338. without an explicit dev guard:
  339. ```bash
  340. HEDGEDOC_DEV=1 npm run test:reconnect-live
  341. ```
  342. `nix flake check` builds the package and runs the version check, property tests,
  343. GC, retry, remote-op, launcher, and argument validation suites from
  344. `package.nix`. It checks the current system; pass `--all-systems` only when
  345. builders for the other systems are configured.
  346. [`AGENT_SCENARIOS.md`](AGENT_SCENARIOS.md) has the scenario suite in prompt
  347. form, and `test/agent-scenarios.mjs` automates it. `CONTRIBUTING.md` covers the
  348. gate and the write-path rules; [`docs/PROTOCOL.md`](docs/PROTOCOL.md) records
  349. the wire facts.
  350. ## License
  351. MIT, see [`LICENSE`](LICENSE). HedgeDoc itself is AGPL and runs as a separate
  352. process.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.