md-log-mcp

Append content to the end of an existing .md file using optimistic concurrency (GET current -> concat -> PUT with base_version_no). Auto-retries once on conflict, then surfaces CONFLICT.

Create a folder path, creating every missing parent segment (mkdir -p). Already-existing folders are treated as success.

Delete a folder. Requires confirm:true (otherwise VALIDATION). By default only an EMPTY folder is deleted (a non-empty one is refused); pass cascade:true to soft-delete the whole subtree — every subfolder and document under it (like `rm -r`). Documents are soft-deleted (recoverable), but prefer move_folder/move_markdown when reorganizing.

Soft-delete a .md file. Requires confirm:true (otherwise VALIDATION). Resolves the path to a document key, then DELETE /documents/{key}.

Change PART of an existing .md file by replacing exact literal strings. USE THIS, NOT update_markdown, for any partial change — a fixed line, a corrected table row, a reworded paragraph, an added section under a heading. update_markdown requires the ENTIRE new document, so using it for a small change means regenerating text you never meant to touch and risks silently rewriting the rest of the report. Read the file with get_markdown first and copy each `old_string` VERBATIM out of it, including indentation, punctuation and any blank lines. SEVERAL CHANGES TO ONE FILE? Send them together in ONE call via `edits` (an ordered list of {old_string, new_string, replace_all?}) with one commit_message: every call writes a new version AND notifies the user's devices, so one call per change floods their history and their phone. For a single change you may pass old_string/new_string directly instead of `edits` (never both). Edits apply in order, each against the text the previous ones produced. Each `old_string` must match EXACTLY ONCE — overlapping positions count, so "\n\n" inside a run of three newlines is ambiguous: zero matches, or more than once while replace_all is false, REJECTS THE WHOLE CALL and NOTHING is written (detail.edit_index names the failing edit) — extend that `old_string` with neighbouring lines until it is unique, or set replace_all:true to change every occurrence on purpose. The write is always optimistic: the version just read is the base, so a concurrent write is retried once (re-read, all edits re-applied) and then surfaces CONFLICT — there is no force mode. The file must already exist; this tool never creates one (use save_markdown for a new file). Because every edit is based on the version it just read, a file deleted out from under you is rejected rather than silently re-created.

Read a .md file's content by path. Pass `version` (a version_no from list_versions) to read an OLD immutable version instead of the current one.

List the documents (and immediate subfolders) inside a folder path. Omit path (or pass '' / '/') to list the ROOT folder.

Return the full folder tree.

List a .md file's immutable version history, newest first (version_no, commit_message, author, registered_at, size). Read an old version's content with get_markdown + `version`.

Move a folder (with its whole subtree: documents, versions, annotations) under a new parent. new_parent_path '' or omitted = move to the root. Parent folders are auto-created. Moving a folder into its own subtree is rejected by the server.

Move and/or rename a .md file: from_path -> to_path. Destination folders are auto-created (mkdir -p). The document KEEPS its identity (same document key), so its whole version history and reviewers' annotations survive the move — never re-save + delete to relocate a file. Fails if a different file already occupies to_path.

Rename a folder in place (descendant paths are rewritten automatically; documents, versions and annotations are untouched).

Roll a .md file back to an earlier version: version N's exact stored content becomes a NEW current version. History is immutable — nothing is deleted or rewound, the rollback is just another version on top, so it is itself undoable by restoring again. Use this after a bad write instead of retyping the old text through save_markdown, which would guess at the content and lose fidelity. Get version numbers from list_versions (and read one first with get_markdown + `version` if you want to check before rolling back). Restoring the version the file is already on is accepted and does nothing.

Save (create or overwrite) a .md file in md-log by path; missing folders are auto-created. Optionally upload embedded images as assets first and rewrite their refs to asset:// links. This is a force-write (last-writer-wins) — the headline agent tool. Before choosing a path, PREFER an existing folder that already holds related documents and reuse its exact spelling — do not invent a new casing or separator (e.g. don't save to 'MdLog/…' when 'md-log/…' already exists). Call list_folders / list_files first if unsure. (The server also auto-reuses a unique near-duplicate folder, but consistent spelling keeps paths clean.)

Search documents by TITLE (substring) and BODY (full-text over current versions; whole-word match, ranked, body hits carry a **bolded** snippet). Use it to find a prior report by its content or name.

Replace the ENTIRE content of an existing .md file. For a PARTIAL change — a line, a row, a paragraph — use edit_markdown instead: it replaces one exact string in place, so you never regenerate (and never accidentally rewrite) the rest of the document. Reach for this tool only when you are genuinely rewriting the whole file. Pass expected_version for optimistic concurrency (mismatch -> CONFLICT); omit it to force last-writer-wins. If you pass expected_version for a path that does not exist you get CONFLICT (detail.server_version_no is 0), not a new file — use save_markdown to create.

Upload a single image as an asset (reserve -> presigned PUT -> complete) and return an 'asset://<key>' reference you can embed in markdown image syntax: . Provide the image as EITHER `data_base64` (inline base64) OR `file_path` (a local file to read) — exactly one.