Find documents matching a query using full-text or semantic search.

Search the vault. Omit 'mode' for the best mode this vault can serve — hybrid when embeddings are configured, keyword when they are not. Pass mode="keyword" for exact terms, operators, or filenames, where FTS5/BM25 beats fusion. Use mode="semantic" for pure vector similarity.

The 'content' field in each result is a snippet by default, not the full document. Use read(path, section=heading) to retrieve the full text of a specific section.

Read the full content of a document or attachment by path.

For .md documents: returns content (the full raw file including frontmatter), plus the parsed frontmatter, title, and folder. For attachments (pdf, png, etc.): returns base64-encoded binary content and MIME type. Use 'list_documents(include_attachments=True)' to discover attachment paths. Use 'stats' to see allowed extensions.

Do not guess paths — look them up first via 'search' or 'list_documents'.

To recover the full text of a specific section returned by 'search', pass section=heading (the value from the result's 'heading' field).

Context cost: every byte returned counts against the LLM's context budget. Reads above MARKDOWN_VAULT_MCP_MAX_NOTE_READ_BYTES (default 256 KB for .md) or MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MB (default 1 MB for binaries) raise ValueError. For partial markdown reads, pass section=heading (use the heading field from a search() result).

List documents (and optionally attachments) in the vault.

Use this to enumerate documents when you need a complete listing, not ranked search results. For finding documents by content, use 'search'. Does NOT include body content — call 'read' for full text.

List all folder paths that contain documents.

Call this to discover valid folder names before filtering 'search' or 'list_documents' by folder. The root folder (top-level documents) is represented as an empty string "".

List all distinct values for a frontmatter field across the vault.

Use this to discover valid filter values before calling 'search' with the 'filters' argument. Only fields listed in indexed_frontmatter_fields (see 'stats') are indexed — querying other fields returns an empty list.

Get an overview of the vault's size, capabilities, and configuration.

Call this at the start of a session to understand what the vault contains and what search modes are available. The 'semantic_search_available' field tells you whether mode="semantic" or mode="hybrid" can be used in 'search'.

Find notes most semantically similar to the given document.

Uses stored embedding vectors — no re-embedding needed. The reference document is excluded from results. Requires semantic search to be configured (check 'stats' for semantic_search_available). Returns an empty list if embeddings are not configured (check 'embeddings_status') or the document has no stored vectors (call 'build_embeddings' to embed missing chunks).

Heading outline for a single note or a whole folder subtree.

If 'path' ends in '.md' it is a note: returns a flat ordered list of {heading, level} (the title as a synthetic H1). Otherwise 'path' is a folder: returns {path, notes, truncated} where 'notes' is an ordered list of {path, title, headings} aggregating every note under the subtree. Mirrors the 'toc://vault/{path}' resource, adding the max_level / max_notes controls below.

Get the most recently modified notes in the vault.

Returns notes ordered by file modification time (most recent first). Useful for surfacing recently changed content without a search query — for example to summarize recent activity or resume work on recently edited notes.

Get a consolidated context dossier for a document.

Replaces separate calls to 'get_backlinks', 'get_outlinks', and 'get_similar' when you need more than one.

Returns everything useful about a note in one call: its metadata, backlinks (documents that link to it), outlinks (documents it links to), semantically similar notes, other notes in the same folder, and indexed frontmatter tags. Use this instead of making 4-5 separate tool calls when you need a full picture of a note's place in the vault.

Get the user's authoring conventions that apply to a note or folder.

Vaults may carry per-folder convention files (by default '_conventions.md') describing how notes in that folder should be authored — for example "reference material: keep notes self-contained; do not link out to project or journal notes". Conventions accumulate down the tree: a vault-root file applies everywhere and nested files add to it, so entries are returned root-first with the most specific guidance last.

Call this before creating, restructuring, or linking notes so the result follows the vault owner's rules. The write/edit tools also echo applicable conventions in their responses for a post-write compliance check. Reads directly from disk — works even while the search index is still building.

Audit the vault's OKF (Open Knowledge Format) conformance.

Reports conformance as degrees, not a verdict — during a migration this is the progress meter. Reads the vault from disk (works before the index is built and before the vault declares 'okf_version'), and skips paths matching the vault's effective exclude patterns.

Findings come in three severities. Conformance (spec violations): notes missing a non-empty 'type', notes with unparseable frontmatter, and 'okf_version' declared outside the root index.md. Advisory (tolerated but worth fixing): 'status' values outside draft/stable/deprecated, log.md files whose '##' headings are not YYYY-MM-DD dates, and a missing root index.md. Informational (not deviations): notes containing wikilinks (relevant only when exporting; internal links resolve fine either way) and notes lacking the recommended 'title'/'description'. Reserved files (index.md, log.md) are exempt from the 'type' rule.

Returns: Report dict: 'mode', 'declared_version', 'active' (detection state); 'total_notes' and 'conformant_notes' (the progress ratio); per-rule findings each carrying 'count' and up to 20 'examples' paths ('missing_type', 'unparseable_frontmatter', 'misplaced_okf_version', 'unknown_status', 'log_heading_shape', 'wikilink_files', 'missing_recommended'); and 'root_index_missing' (bool).

Find all documents that link TO the given document (backlinks).

Use this to discover which notes reference a particular document. For a full picture of a note's place in the vault (backlinks, outlinks, similar notes, folder peers), use 'get_context' instead of calling this separately. Call 'get_backlinks' directly when you only need the inbound link list. Backlinks reveal implicit relationships that search alone cannot surface — they show what other authors considered relevant to this document.

Find all links FROM the given document to other documents (outlinks).

Use this to see what a document references. For a full picture of a note's place in the vault, use 'get_context' instead of calling this separately. Call 'get_outlinks' directly when you only need the outbound link list. Each result includes an 'exists' flag — False means the link is broken (the target is missing from the vault).

Find all links that point to non-existent documents (broken links).

Use this to audit link health across the vault. Call this when 'stats' shows broken_link_count > 0, or after a 'rename' that did not use update_links=True, to see what links were left pointing to the old path. A broken link means the target path does not match any indexed document — the referenced note may have been deleted, renamed, or never created.

Return all notes with no inbound or outbound links.

WARNING: returns ALL orphans with no limit — check 'stats' for orphan_count before calling on large vaults.

An orphan note has no backlinks (no other note links to it) and no outlinks (it links to nothing). Call this when 'stats' shows orphan_count > 0. Useful for finding isolated notes that may need to be connected to the rest of the vault or removed.

Return the documents with the most inbound links, ranked by backlink count.

Useful for discovering hub notes — frequently-referenced notes that are likely key concepts in the vault. For the specific documents that link to a particular note, use 'get_backlinks' instead.

Find the shortest connection path between two notes in the link graph.

Treats links as undirected — a link from A to B or B to A both count as a connection. Uses BFS; max_depth is clamped to [1, 10].

Useful for discovering how two seemingly unrelated notes are connected through the vault's link structure (the "six degrees of separation" for your notes).

Check the embedding provider configuration and vector index status.

Use this to diagnose why semantic search is unavailable. Embeddings are built automatically on startup when configured, so chunk_count should normally match the FTS chunk count from 'stats'. If it is lower, call 'build_embeddings' (without force) to embed the missing chunks. Use 'build_embeddings' with force=True only to rebuild from scratch after changing the embedding model.

Returns: Dict with the following fields:

- available (bool): True if semantic search can be used in 'search'.
- provider (str | None): Provider class name when configured
  (e.g. "OllamaProvider"), or null if not configured.
- chunk_count (int): Number of chunks currently in the vector index.
- path (str | None): Vector index file path when persisted, or null.

Return background-build state of the FTS index.

Use this when initialize returned but bucket-3/4 calls block longer than expected or surface IndexUnavailableError — the status field distinguishes "still building" from "build failed," and the error field carries the exception message from the last background-build attempt that captured one. error may be populated when status is "queryable" (a successful build followed by a later failed rebuild leaves the captured diagnostic in place until the next successful build clears it) and is always None when status is "building".

Returns: Dict with the following fields:

- status (str): ``"queryable"``, ``"building"``, or
  ``"failed"``.
- documents_indexed (int): Count of documents committed to
  the FTS index right now (rises during ``"building"``).
  ``0`` both for an empty index and when the count could not
  be read — see ``documents_indexed_error`` to tell them apart.
- documents_indexed_error (str | None): ``None`` on a normal
  read; the SQLite error message when the document count
  could not be read (e.g. a locked or closed database), in
  which case ``documents_indexed`` is ``0``.
- error (str | None): ``None`` unless the background build
  raised.
- skipped_files (list[dict]): Files dropped from the index for a
  surfaced deterministic reason. Each entry is
  ``{"path", "category", "detail"}`` where ``category`` is one of
  ``"parse_error"``, ``"encoding_error"``,
  ``"missing_frontmatter"``, or ``"internal_error"`` (an
  unexpected indexer error, vs a content problem). Empty when
  nothing was skipped.
  Distinguishes a parse-dropped note from an unsynced one without
  reading container logs. Exclude-pattern and transient-I/O skips
  are intentionally not listed.

Create or overwrite a document or attachment.

For .md documents: uses 'content' (markdown body) and optional 'frontmatter'. WARNING: replaces the entire file — use 'edit' for targeted changes. The search index is updated immediately; do not call 'reindex' afterward.

For attachments (pdf, png, etc.): uses 'content_base64' (base64- encoded binary). 'content' and 'frontmatter' are ignored. Parent directories are created automatically for both.

Make a targeted text replacement in an existing .md note (not supported for attachments).

Three edit modes:

• Exact match (old_text only): pass a portion of the file as old_text — must appear exactly once. Frontmatter can be edited.

• Line-range (line_start + line_end, no old_text): replace the specified lines with new_text. Lines are 1-based (matching 'read' output). Recommended: pass if_match for safety.

• Scoped match (old_text + line_start/line_end): search for old_text within the line range only — useful when old_text appears multiple times in the file.

When exact match fails, a normalized comparison is attempted (Unicode NFC, dash/quote normalization, whitespace collapsing). If a unique normalized match is found, it is used and match_type='normalized' is returned.

Always call 'read' first to get the current text and line numbers. The search index is updated immediately; do not call 'reindex'.

Append text to the end of an existing .md note without reading it.

The cheapest way to add content at the end of a note (log entries, journal additions, checklist items): unlike 'edit', no prior 'read' is needed, so the existing note content never enters the context. Prefer this over 'edit' whenever the change is purely additive at the end of the note.

A newline is inserted between the existing content and the appended text when the file does not already end with one, so the appended text starts on its own line. Include leading blank lines or heading markers in 'content' yourself if you want a separating paragraph or section. The search index is updated immediately; do not call 'reindex' afterward.

Permanently delete a document or attachment.

For .md documents: removes the file and immediately updates all search indices — do not call 'reindex' afterward. For attachments: only the file is deleted (no index to update). IRREVERSIBLE unless git history exists. Confirm the path with the user before calling.

Rename or move a document or attachment. When renaming a .md note, always pass update_links=True to rewrite links in other documents that point to the old path — omitting this leaves those links broken.

For .md documents: the file and its search index entries are updated immediately — do not call 'reindex' afterward. For attachments: only the file is moved (no index update needed). Parent directories for new_path are created automatically.

Move an entire folder subtree to a new location in one call, rewriting every link across the vault that points into the moved subtree — the folder-level analogue of 'rename'.

Moves all files under old_dir (.md notes, attachments, and any other files) to the matching path under new_dir, preserving structure. Links between documents inside the subtree and backlinks from outside are all rewritten. The search index is updated immediately — do not call 'reindex' afterward.

The move is atomic at the gate: if any destination file already exists, the call fails before moving anything. Link rewrites are best-effort — a source that cannot be rewritten is reported in failed_links rather than aborting the move. Note: an OS error during the move phase itself (permission error, full disk, concurrent file removal) can leave the subtree partially moved with the index unchanged; call 'reindex' to reconcile the index with the on-disk state.

Download a file from a URL and save it to the vault.

Fetches content from an HTTP/HTTPS URL and writes it as a note or attachment. Designed for MCP-to-MCP file transfer when content is too large to pass through the LLM context window.

Context cost: zero for the bytes themselves — the file is downloaded server-side and saved to the vault. After a successful fetch, reference the file by its path (call read(path) only for small results, otherwise pass the path to other tools).

For .md paths: the response is decoded as UTF-8 text and saved as a markdown note with optional frontmatter. The search index is updated immediately.

For other paths: the response is saved as a binary attachment. The existing attachment size limit applies.

Rewrite wikilinks as OKF bundle-root-absolute markdown links.

A migration transform (Open Knowledge Format): converts every resolvable [[wikilink]] in the vault (or one folder) into [text](/path/note.md), OKF's recommended link style. Only links whose target is indexed are converted, so the link graph is preserved exactly — a converted link points at the same note the wikilink resolved to. Unresolvable wikilinks are left untouched and counted as skipped. Each changed note is written through the normal write path (git commit if configured). Re-running is safe: already- converted links are plain markdown and are not touched again.

Generate a reserved OKF index.md listing from the table of contents.

A migration transform (Open Knowledge Format): writes (or overwrites) the folder's index.md as a progressive-disclosure listing — - [title](/path.md) - description per note, description drawn from frontmatter. Existing frontmatter is preserved, so regenerating the bundle-root index.md keeps its okf_version declaration. Reserved files (index.md, log.md) are omitted from the listing.

Seed a reserved OKF log.md change history from git history.

A migration transform (Open Knowledge Format): writes a log.md with newest-first ## YYYY-MM-DD sections built from the vault's git commit history (one bullet per commit). folder both chooses where log.md is written and scopes its content: a folder seeds only the commits that touched that subtree, while the bundle root seeds the whole vault's history. Refuses to overwrite an existing log.md — a change history is hand-maintained after seeding, so it is never clobbered. Requires the vault to be git-backed; with no git history the log is written empty.

List commits that touched a note, folder, or the whole vault.

Only available for git-backed vaults. Use 'stats' to check whether git is configured, or call this and handle the error.

Return the diff of a note between a reference point and HEAD.

Only available for git-backed vaults. Exactly one of 'since_sha' or 'since_timestamp' must be provided. Use 'get_history' first to find commit SHAs.

Open a visual vault explorer UI for the user — not for reading vault content.

Displays an interactive visual panel (MCP Apps) to the user so they can browse the file tree, explore the link graph, or view a note's relationships. Do NOT call this to retrieve or inspect vault content programmatically — use search to find notes, read for note content, list_documents to enumerate files, and get_context for a note's relationships instead.

Only call this when the user explicitly asks to open the visual vault browser or explorer (e.g. "show me the vault browser", "open the graph view").

Open a visual context card UI for the user — not for reading note relationships.

Displays an interactive context panel (MCP Apps) to the user showing a note's backlinks, outlinks, similar notes, tags, and frontmatter visually. Do NOT call this to retrieve note relationship data programmatically — use get_context instead, which returns the full structured data.

Only call this when the user explicitly asks to open the visual context card or explorer (e.g. "show me the context card for this note").

Report wrapper and upstream version info for markdown-vault-mcp. Returns server_name, server_version, core_version (fastmcp-pvl-core), and (when configured) an upstream version block. Useful for verifying a deployment matches the expected build.

Run an incremental reindex on the writer thread.

Only needed when files are modified outside this server — for example, by a text editor, a sync tool, or another process writing directly to the vault directory. Do NOT call this after using 'write', 'edit', 'delete', or 'rename' — those tools update the index immediately as part of the operation.

Change detection is hash-based, so an unchanged file is never re-parsed. Use force=True to drop the index and re-parse every file regardless of hashes — the repair for index content that no longer matches what the current server would extract. A version upgrade that changes extraction does this by itself on the next start (#1124), so force=True is a manual escape hatch, not routine maintenance. When semantic search is configured, follow a force=True run with 'build_embeddings' (without force) so the vector index converges to the rebuilt chunk set; an ordinary reindex re-embeds as it goes.

To rebuild all embeddings from scratch (e.g. after changing the embedding model), use 'build_embeddings' with force=True.

A fast reindex (the common case — work scales with the drift, not the vault) returns its result inline. A reindex still running at the server's soft deadline continues in the background and returns {"status": "working", "job_id": ...} immediately — fetch the outcome with get_job_result. get_index_status remains the observability view of the index (it also covers boot-time builds and file-watcher reindexes no client call initiated).

Rebuild vector embeddings for semantic and hybrid search.

Embeddings are built automatically on startup, so this is normally not needed. Use force=True to rebuild from scratch after changing the embedding model. Without force, the vector index converges to the FTS chunk set: missing or changed documents are embedded, orphaned vectors are removed, unchanged chunks are untouched.

A fast convergence (small drift) returns its result inline. A build still running at the server's soft deadline — typical for a force=True rebuild of a large vault — continues in the background and returns {"status": "working", "job_id": ...} immediately; fetch the outcome with get_job_result. embeddings_status remains the observability view of the vector index.

Retrieve the outcome of a background job started by a long-running tool on this server. When such a tool answers with status "working" and a job_id, call this tool with that job_id every few seconds until the status is terminal. Job records expire after a while — fetch results soon after completion. On this server, background jobs come from slow summarize, reindex, and build_embeddings calls.