A Model Context Protocol server for managing markdown vaults with git sync, providing tools for reading, writing, organizing, searching, and transferring notes
Strong tool definitions with comprehensive schemas and detailed descriptions. All 9 tools have explicit input schemas with typed parameters and descriptions. Tool names follow verb_noun convention (delete_notes, move_notes, read_notes, etc.). Descriptions are detailed (100-300+ chars) and explain WHAT, WHEN, and consequences. Batch operations with dry_run/prune_empty flags show sophisticated design. Key strengths: all tools documented, schemas complete, error handling guidance present. Minor gaps: some parameter descriptions could be more prescriptive about constraints; output schemas not fully documented in source; no tool annotations (readOnlyHint/destructiveHint) visible in code.
Delete notes or directories (a path is its segments root to leaf) to a recoverable trash. All-or-nothing: a missing path, the vault root, or two overlapping targets reject the whole batch and nothing is deleted. Returns each item's trash location. dry_run:true validates and returns the planned outcome (or every rejection) without deleting. prune_empty:true also removes source directories the batch left empty (reported as pruned).
List notes (and optionally directories) by directory and glob. The glob selects notes only: with include_dirs, directories are listed whether or not they match it. Returns path-sorted items with kind (note|dir), size and modified time; pass next_cursor to page.
Move or rename notes and directories; paths are segment arrays root to leaf. Each item names its target with exactly one of: into — a directory to move into keeping the basename ([] is the vault root) — or dest — the full destination path including the new basename (a note keeps .md), renaming and moving in one step. All-or-nothing: collisions (without overwrite), moving a directory into its own subtree, or in-batch duplicates/swaps reject the whole batch; an item may land inside another item's moved directory (ancestor destinations apply first). dry_run:true validates and returns the planned destinations without moving. prune_empty:true also removes source directories the batch left empty (reported as pruned). update_links:true also rewrites standard-Markdown links vault-wide so they keep pointing at the moved notes (relinked notes are reported; wikilinks untouched).
Open a byte-level HTTP surface for working on note bytes outside model context, and return a one-time ticket with ready-to-run curl commands. The note tools are how work in this vault is normally done; reach for this when a note is too large to pull through context, or a job is repetitive enough that a shell script plainly beats them — rewriting a large note with sed, processing many notes in a loop. It serves an index (path, etag, size per note) and one-note GET/PUT with If-Match; bulk work is those commands in a loop. Each PUT rides the vault's per-write auto-commit, the same as a tool write. Useless without shell access. Pass write:true to write back, and prefix to confine the grant to one directory or one note. Deleting and moving are not part of it: use delete_notes and move_notes.
Tool annotations (readOnlyHint, destructiveHint, idempotentHint) not visible in source code. Destructive tools (delete_notes, move_notes, sync_vault) should declare destructiveHint=true; read-only tools should declare readOnlyHint=true. This helps LLMs reason about safety and side effects.
Output schemas not documented in source. While input schemas are complete, return types for each tool are not explicitly defined in the code shown. LLMs need to know: does read_notes return {path, body, frontmatter} or {notes: [{path, body, frontmatter}]}? Does list_notes return {items, next_cursor, total}?
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 61 | <=2025-11-25 | v2 |
Read notes with optional body and frontmatter content. Partial-success: a failing item reports its state without sinking its siblings.
Read note outlines (heading structure). Returns one text row per heading in document order with line number, level, and title. Partial-success: a failing item reports its state without sinking its siblings.
Read note sections by heading path. Scope controls whether to return the heading's body only or body plus subsections. Partial-success: a failing item reports its state without sinking its siblings.
Search notes by content keywords (whitespace-AND), filename substring, and/or frontmatter field filters (all combined with AND). Returns path-sorted matches with a snippet and the filtered frontmatter values; pass next_cursor to page. Provide at least one of query/frontmatter/frontmatter_exists. CJK keywords match regardless of spacing and inline style, so 전역지침 finds 전역 지침 and **전역** 지침.
Synchronize the vault with its git remote: commit local changes, rebase onto the fetched upstream, and push. Returns {status, pulled, pushed, conflicts}. status:"conflict" means the rebase was aborted and the vault left unchanged — the listed paths need manual/agent resolution. Errors are reserved for git execution failures. Commit model: when auto-commit is enabled each write batch is already committed as `mcp(<tool>)` the moment it lands, so the sweep here picks up only edits made outside mcp — status:"clean" with pushed:0 right after your writes means they were committed (and possibly auto-pushed) earlier, not lost.
sync_vault has empty input schema (no parameters). Description mentions 'status', 'pulled', 'pushed', 'conflicts' in return but these are not documented as output fields. Unclear what the tool returns or how to interpret conflict resolution.
provision_transfer description is dense and assumes shell/curl knowledge. Phrases like 'byte-level HTTP surface', 'one-time ticket', 'If-Match' are technical jargon. LLMs may not understand when to call this vs standard note tools. Needs clearer guidance: 'Use this only when a note exceeds context limits or requires bulk processing outside the model.'
read_sections parameter 'occurrence' (integer) lacks description. What does it mean? Is it 1-indexed? What happens if occurrence exceeds the number of matching headings? Ambiguous parameters invite LLM errors.