What can you do with this server?

mcp-markdown-vault is a headless MCP server for reading, writing, searching, and managing markdown vaults (Obsidian, Logseq, Dendron, Foam, or any folder of .md files) — no app or API keys required. Vault Management — Full CRUD on notes (list, read, create, update, delete, stat), plus scaffold new notes from templates with {{variable}} placeholder injection. Surgical Editing — AST-based append/prepend/replace targeting specific headings or block IDs with fuzzy matching, freeform line-range and string replacements, YAML frontmatter updates, batch edits (up to 50 operations), and dry-run diff previews. Search & Retrieval — Hybrid semantic search (vector + lexical, zero-setup local embeddings with optional Ollama), global keyword search, single-file fragment retrieval (TF-IDF + proximity), bulk read of multiple files/sections, heading-scoped section reads, note outline view, frontmatter reads, and backlinks (wikilinks + markdown links with line context) — all optionally scoped to a directory. Workflow Tracking — Petri net state machine with status checks, transition firing, history view, and reset, plus contextual LLM hints for agent workflows. System Administration — Server health/status, full vault reindexing, and structural vault overview (folder tree, file counts, modification dates). Transport & Security — Dual transport modes (stdio for single client, SSE over HTTP for multi-client/Docker), path traversal protection, atomic file writes, and safe path validation.

Which integrations are available for this server?

Provides Docker container deployment option with multi-arch support via GitHub Container Registry, enabling SSE transport mode for multi-client setups and containerized vault operations. Enables MCP server capabilities for Logseq graphs, offering markdown file operations, semantic search, fragment retrieval, and surgical editing for Logseq's knowledge base structure. Provides headless semantic MCP server functionality for Obsidian vaults, enabling direct read/write operations, surgical AST-based editing, semantic search, and workflow tracking without requiring the Obsidian app or plugins. Supports optional integration with Ollama for higher-quality embeddings in semantic search functionality, using models like nomic-embed-text for improved vector search results.

de en es ja ko ru zh

mcp-markdown-vault

by wirux

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

📁 Markdown Vault MCP Server

Headless semantic MCP server for Obsidian, Logseq, Dendron, Foam, and any folder of markdown files.

npm install and point it at a folder. Hybrid search, AST editing, zero-config embeddings. No app, no plugins, no API keys.

CI / Release PR Check npm version Docker License: MIT TypeScript Node.js Tests mcp-markdown-vault MCP server

Markdown Vault MCP Server Demo

💡 Why this server?

TL;DR — One npx command. No running app. No plugins. No vector DB. Semantic search works out of the box.

	Differentiator	Details
🚫	No app or plugins required	Most Obsidian MCP servers (mcp-obsidian, obsidian-mcp-server) need Obsidian running with the Local REST API plugin. This server reads and writes `.md` files directly — point it at a folder and go.
🧠	Built-in semantic search, zero setup	Hybrid search: cosine-similarity vectors + TF-IDF + word proximity. Local embeddings (`@huggingface/transformers`, `all-MiniLM-L6-v2`, 384d) download on first run. No API keys, no external services. Ollama optional for higher quality.
🔬	Surgical AST-based editing	`remark` AST pipeline patches specific headings or block IDs without touching the rest of the file. Freeform line-range & string replace as fallback. Levenshtein fuzzy matching handles LLM typos.
🔓	Tool-agnostic	Obsidian vaults, Logseq graphs, Dendron workspaces, Foam, or any plain folder of `.md` files. If it's markdown, it works.
📦	Single package, no infrastructure	Unlike Python alternatives that need ChromaDB or other vector stores, everything runs in one Node.js process. `npx @wirux/mcp-markdown-vault` and you're running. Docker image available.

💎 Obsidian · 📓 Logseq · 🌳 Dendron · 🫧 Foam · 📂 Any .md folder

Related MCP server: Optimike Obsidian MCP

✨ Features

	Feature	Description
🗂️	Headless vault ops	Read, create, update, edit, delete `.md` notes with strict path traversal protection
📑	Read by heading	Read a single section by heading title — returns only content under that heading (up to the next same-level heading), saving context window space
📦	Bulk read	Read multiple files and/or heading-scoped sections in a single call — reduces MCP round-trips with per-item fault tolerance
🔬	Surgical editing	AST-based patching targets specific headings or block IDs — never overwrites the whole file
🔍	Fragment retrieval	Heading-aware chunking + TF-IDF + proximity scoring returns only relevant sections
📂	Scoped search	Optional directory filter for `global_search` and `semantic_search` — restrict results to specific folders to reduce noise
🧠	Semantic search	Hybrid vector + lexical search with background auto-indexing
⚡	Zero-setup embeddings	Built-in local embeddings via `@huggingface/transformers` — Ollama optional
🔄	Workflow tracking	Petri net state machine with contextual LLM hints
🌐	Dual transport	Stdio (single client) or SSE over HTTP (multi-client, Docker-friendly)
✏️	Freeform editing	Line-range replacement and string find/replace as AST fallback
🏷️	Frontmatter management	AST-based read and update of YAML frontmatter — safely manage tags, statuses, and metadata without corrupting file structure
👀	Dry-run / diff preview	Preview any edit operation as a unified diff without saving — set `dryRun=true` on any edit action
📝	Templating / scaffolding	Create new notes from template files with `{{variable}}` placeholder injection — refuses to overwrite existing files
🗺️	Self-orienting vault context	Assisted or manual `meta/overview.md` with host-visible `vault_scope` and live `vault://overview` context for connected agents
📦	Batch edit	Apply multiple edit operations in a single call — sequential execution, stops on first error, supports `dryRun`, max 50 ops
🔗	Backlinks index	Find all notes linking to a given path — supports wikilinks and markdown links with line numbers and context snippets
🎯	Typo resilience	Levenshtein-based fuzzy matching for edit operations

🛠️ MCP Tools

Tool	Actions	Description
📁 vault	`list` `read` `create` `update` `delete` `stat` `create_from_template`	Full CRUD for vault notes + template scaffolding
✏️ edit	`append` `prepend` `replace` `delete` `line_replace` `string_replace` `frontmatter_set` + `operations[]` batch mode	AST-based patching + freeform fallback + frontmatter update + batch edit (supports `dryRun` diff preview)
👁️ view	`search` `global_search` `semantic_search` `outline` `read` `frontmatter_get` `bulk_read` `backlinks`	Fragment retrieval, cross-vault search, hybrid semantic search, read by heading, frontmatter read, bulk read, backlinks
🔄 workflow	`status` `transition` `history` `reset`	Petri net state machine control
⚙️ system	`status` `reindex` `overview` `overview_status` `prepare_overview` `save_overview`	Server health, indexing info, vault structure overview, assisted overview rebuild

All tool responses include contextual hints based on the current workflow state.

💡 Operational Guidance

🛠️ Safe Editing

dryRun=true: Highly recommended before destructive operations like delete or replace with replaceMode="section".
Heading Disambiguation: If multiple identical headings are found, the server returns AMBIGUOUS_HEADING_TARGET with a list of candidates. Use blockId to target specific elements if headings are not unique.
AST vs Freeform: Always prefer AST operations (append, prepend, replace, delete) as they are structural. Use string_replace only as a last resort; it requires exact literal matches including whitespace and newlines.
replaceMode: replace defaults to body (preserves the heading, replaces content). Set replaceMode: "section" to replace the heading node and all its child headings.
returnContent: Set to section or file to see the results of your edit immediately in the tool response (max 8KB).

🚀 Performance & Consistency

bulk_read: Use this to read 2 or more files/sections concurrently. It is significantly faster than multiple sequential view.read calls.
Workflow State: The workflow tool manages session-specific state used for contextual hints. It does not modify vault data or search indexes.
system.reindex: Only use this for recovery or after making out-of-band file changes (e.g., via external scripts). Normal MCP edits automatically update backlinks and queue vector indexing.
view.outline: Supports a directory parameter to get a flat list of headings across multiple files in a folder.

🧪 Batch Edits

Sequential Execution: Operations in a batch are executed one by one. If one fails, the remaining are skipped.
Dry-run Asymmetry: In dryRun=false, each operation sees the file state after previous operations. In dryRun=true, the file is never written, so sequential dependent operations (e.g., editing the same line twice) may produce different results than a live run.

🚀 Quick Start

Prerequisites

Node.js >= 22
(Optional) Ollama for higher-quality embeddings

📦 Install from NPM

npm install -g @wirux/mcp-markdown-vault

Then run directly:

VAULT_PATH=/path/to/your/vault markdown-vault-mcp

🔌 MCP Client Configuration

Add to your MCP client config (e.g. Claude Desktop, Claude Code):

{
  "mcpServers": {
    "markdown-vault": {
      "command": "npx",
      "args": ["-y", "@wirux/mcp-markdown-vault"],
      "env": {
        "VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

npx -y auto-installs the package if not already present — no global install needed.

Try it in the browser: You can test this server directly at Glama Inspector — no local install required.

🐳 Docker

Pull the pre-built multi-arch image from GitHub Container Registry:

docker pull ghcr.io/wirux/mcp-markdown-vault:latest

Or use Docker Compose:

docker compose up

Edit docker-compose.yml to point at your markdown vault directory. The default compose file uses SSE transport on port 3000.

🛠️ Development (from source)

git clone https://github.com/wirux/mcp-markdown-vault.git
cd mcp-markdown-vault
npm install
npm run build
VAULT_PATH=/path/to/your/vault node dist/index.js

🌐 Transport Modes

Mode	Use case	How it works
📡 `stdio` (default)	Single-client desktop apps (Claude Desktop)	Reads/writes stdin/stdout; 1:1 connection
🌊 `sse`	Multi-client setups (Docker, Claude Code)	HTTP server with SSE streams; one connection per client

SSE starts an HTTP server on PORT (default 3000):

GET /sse — establishes an SSE stream (one per client)
POST /messages?sessionId=... — receives JSON-RPC messages

MCP_TRANSPORT_TYPE=sse PORT=3000 VAULT_PATH=/path/to/vault npx @wirux/mcp-markdown-vault

Each SSE client gets its own workflow state. Shared resources (vault, vector index, embedder) are reused across all connections.

🧠 Embedding Providers

The server selects an embedding provider automatically:

`OLLAMA_URL` set?	Ollama reachable?	Provider used
❌ No	—	🏠 Local (`@huggingface/transformers`, `all-MiniLM-L6-v2`, 384d)
✅ Yes	✅ Yes	🦙 Ollama (`nomic-embed-text`, 768d)
✅ Yes	❌ No	🏠 Local (fallback with warning)

No configuration needed for local embeddings — the model downloads on first use and is cached automatically.

⚙️ Configuration

Variable	Default	Description
`VAULT_PATH`	`/vault`	Markdown vault directory
`VAULT_CONTEXT_MODE`	`assisted`	Vault orientation mode: `assisted` (host LLM/agent calls `prepare_overview` to gather evidence, then generates prose and calls `save_overview`) or `manual` (you author `meta/overview.md` yourself and the server does not overwrite it). `auto` is a deprecated alias for `assisted`.
`VAULT_CONTEXT`	(deprecated)	Deprecated and ignored. Use `VAULT_CONTEXT_MODE` instead.
`MCP_TRANSPORT_TYPE`	`stdio`	`stdio` (single client) or `sse` (multi-client HTTP)
`PORT`	`3000`	HTTP port (SSE mode only)
`OLLAMA_URL`	(unset)	Set to enable Ollama embeddings
`OLLAMA_MODEL`	`nomic-embed-text`	Ollama embedding model name
`OLLAMA_DIMENSIONS`	`768`	Ollama embedding vector dimensions
`VECTOR_STORE_URL`	(unset)	Set to use Qdrant (e.g. `http://localhost:6333`). If unset, local persisted flat store is used.
`VECTOR_STORE_COLLECTION`	`markdown_vault`	Qdrant collection name when `VECTOR_STORE_URL` is set.
`VECTOR_STORE_RESET`	`false`	Set to `true` to auto-delete a mismatched vector index on startup and rebuild from scratch.
`MCP_AUTH_TOKEN`	(unset)	Bearer token for SSE transport auth. If set, all SSE endpoints require `Authorization: Bearer <token>`.
`HOST_BIND_ADDRESS`	`127.0.0.1`	Bind address for the SSE HTTP server.
`BODY_LIMIT_BYTES`	`1mb`	Max JSON request body size for SSE `POST /messages`.

Note: When using the default local vector store, a .markdown_vault_mcp directory will be created in your vault. It's recommended to add this directory to your .gitignore.

Use assisted mode when you want the connected host LLM/agent to generate and refresh vault context from server-provided evidence. Use manual mode when you want to write and maintain meta/overview.md yourself; in manual mode, the server creates the file if missing but does not overwrite it.

🏗️ Architecture

Clean Architecture with strict layer separation:

src/
├── domain/           🔷 Errors, interfaces (ports), value objects
├── use-cases/        🔶 Business logic (AST, chunking, search, workflow)
├── infrastructure/   🟢 Adapters (file system, Ollama, vector store)
└── presentation/     🟣 MCP tool bindings, transport layer (stdio/SSE)

See CLAUDE.md for detailed architecture docs and CHANGELOG.md for implementation history.

🗺️ Self-Orienting Context Layer

Connected agents automatically discover when to query this vault and how to use its tools — no explicit user instructions needed.

Quick start: Run the rebuild-overview MCP prompt after adding notes to your vault. This generates context that helps agents route queries to the right vault.

How it works

The server delivers vault context through multiple mechanisms (graceful degradation across clients):

Mechanism	When	What the agent sees
`instructions` field	MCP handshake	`vault_scope` + tool summary
MCP Resources	On-demand	`vault://overview` (stats + overview + conventions)
First-call priming	First tool call per session	`vault_scope` + hint to read `vault://overview`
Tool descriptions	Tool listing	`vault_scope` string for routing

Modes

Mode	How overview is managed
`assisted` (default)	Host agent calls `system.prepare_overview` → generates prose → calls `system.save_overview`
`manual`	You author `meta/overview.md` yourself; server creates stub but never overwrites

To rebuild in assisted mode: invoke the rebuild-overview MCP prompt, or ask your agent to call system.prepare_overview then system.save_overview.

Vault meta files

On first startup, the server creates two files in <VAULT_PATH>/meta/:

File	Purpose	Managed by
`meta/overview.md`	Vault description + `vault_scope` routing hint	Host agent (assisted) or you (manual)
`meta/contract.md`	Tool usage conventions (frontmatter schema, search hints, naming)	Created once, never overwritten

Tip: Keep vault_scope short and specific — it tells MCP hosts what information this vault can answer.

🚢 CI/CD & Release

Fully automated via GitHub Actions and Semantic Release:

Workflow	Trigger	What it does
PR Check	Pull request to `main`	Lint → Build → Test
Release	Push to `main`	Lint → Test → Semantic Release (NPM + GitHub Release) → Docker build & push to `ghcr.io`

Versioning follows Conventional Commits — feat: = minor, fix: = patch, feat!: / BREAKING CHANGE: = major
Docker images are built for linux/amd64 and linux/arm64 via QEMU
NPM package published as @wirux/mcp-markdown-vault
Docker image available at ghcr.io/wirux/mcp-markdown-vault

🧪 Testing

568 tests across 49 files, written test-first (TDD).

npm test                                          # Run all tests
npx vitest run src/use-cases/ast-patcher.test.ts  # Single file
npm run test:watch                                # Watch mode
npm run test:coverage                             # Coverage report

Tests use real temp directories for file system operations and in-memory MCP transport for integration tests. No external services required.

🔒 Security

🛡️ All file paths validated through SafePath value object before any I/O
🚫 Blocks path traversal: ../, URL-encoded (%2e%2e), double-encoded (%252e), backslash, null bytes
✍️ Atomic file writes (temp file + rename) prevent partial writes
👤 Docker container runs as non-root user

📄 License

MIT

Available Tools

5 tools

editEditA

Edit notes safely. Vault scope: general markdown notes vault. Supports AST edits by heading/block ID, freeform line/string replacement, frontmatter_set metadata merges, batch operations (max 50), and dryRun=true unified diff previews. Read vault://overview for editing strategy and conventions.

ParametersJSON Schema

Name	Required	Description
`path`	No	Note path (required for single edit).
`operation`	No	Edit operation (required for single edit).
`content`	No	Content to apply (required for single edit).
`heading`	No
`headingDepth`	No
`blockId`	No
`startLine`	No
`endLine`	No
`searchText`	No
`replaceAll`	No
`dryRun`	No	If true, returns a preview of changes as a unified diff without saving to disk.
`operations`	No	For batch mode: array of edit operations (max 50). Executed sequentially, stops on first error.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses safety intent, batch sequential execution stops on first error, dryRun returns preview without saving. Does not cover reversibility or permissions, but key behaviors are transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single dense paragraph, front-loaded purpose, every sentence adds value. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 12 parameters, batch mode, and no output schema, description provides a good overview but lacks details on parameter formats and interpretation. References vault://overview for strategy, but standalone completeness is moderate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is low (42%). Description adds context for overall tool functionality and mentions key patterns (heading/block ID, line/string replace, frontmatter_set), but many parameters like startLine, endLine, searchText, replaceAll lack explanation. Partially compensates but could do more.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it edits notes in a general markdown notes vault, with specific operations (AST, line/string replacement, frontmatter_set, batch, dryRun). Differentiates from sibling tools (system, vault, view, workflow) which are not editing-focused.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes supported edit modes (by heading, block ID, line/string, frontmatter) and features like batch limits (max 50) and dryRun. Implicitly limits usage to this vault scope. Could explicitly state when not to use or mention alternatives, but provides operational guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

systemSystemA

System administration for this vault (general markdown notes vault). Actions: status (indexing/backlinks/workflow health), reindex (async rebuild), overview (folder tree), overview_status (meta/overview.md state), prepare_overview (gather evidence), save_overview (persist host-written overview).

ParametersJSON Schema

Name	Required	Description
`action`	Yes
`maxDepth`	No	Maximum folder depth for overview (default 3).
`overview`	No	Overview text to save (required for save_overview action).
`scope`	No	One-line vault routing hint, max 200 chars (required for save_overview action). Should describe what information agents can find here.

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden. It reveals some behavioral traits (e.g., reindex is 'async rebuild', save_overview persists host-written overview) but does not disclose safety, permissions, or consequences of misuse. Some behaviors are hinted but not comprehensively.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the core purpose and lists actions concisely. Every word adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple actions, some writing), the description lacks details on return values or side effects. No output schema exists, so it would benefit from mentioning what each action returns. It covers the main actions adequately but leaves gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 3 of 4 parameters with descriptions (75% coverage). The tool description adds meaning by explaining the action enum values (e.g., 'status' linked to indexing/backlinks health), which the schema does not describe. This compensates for the missing action description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'System administration for this vault' and enumerates specific actions with brief explanations (e.g., 'status (indexing/backlinks/workflow health)'). This distinguishes it well from sibling tools like edit, vault, view, and workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for system-level tasks via the listed actions but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. Usage is implied but not fully explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vaultVaultB

Manage vault notes. Vault scope: general markdown notes vault. Actions: list (browse notes), read (full note), create/update/delete (whole-file writes), stat (metadata), create_from_template (scaffold from template). For search strategy and conventions, read vault://overview.

ParametersJSON Schema

Name	Required	Description
`action`	Yes
`path`	No
`directory`	No
`content`	No
`templatePath`	No	Source template file path (for create_from_template).
`variables`	No	Key-value variables to inject into template placeholders (for create_from_template).

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions 'whole-file writes' for create/update/delete, providing some behavioral context. Since no annotations are provided, more detail on auth, rate limits, or side effects would be needed for a higher score.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff. The first sentence states the purpose, the second enumerates actions with brief comments. It is concise but could be better structured with bullet points.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (6 parameters, multiple actions) and lack of output schema/annotations, the description does not cover return values, errors, or permissions. It references an external overview doc, but is not self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to the action parameter by specifying each action's purpose (e.g., 'list (browse notes)', 'create_from_template (scaffold from template)'). This adds value beyond the schema descriptions for parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it manages vault notes and lists all actions. It distinguishes the vault as a general markdown notes vault, but does not explicitly differentiate from sibling tools like 'view' or 'edit'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. It only hints at reading a separate overview document for search strategy and conventions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

viewViewB

Read and search markdown notes. Vault scope: general markdown notes vault. Actions: search (heading-aware fragment retrieval with TF-IDF + proximity), semantic_search (vector + lexical hybrid for conceptual queries), global_search (cross-vault exact-match grep), outline (file or directory structure tree), read (full file or single section by heading), frontmatter_get (parse YAML frontmatter), bulk_read (read multiple files/headings in one call), backlinks (find all notes linking to a given path).

ParametersJSON Schema

Name	Required	Description
`action`	Yes
`path`	No
`query`	No
`maxChunks`	No
`heading`	No
`headingDepth`	No
`directory`	No	Filter search results to a specific directory or path prefix. Example: 'projects/active/'
`items`	No	For bulk_read: array of files to read, each with optional heading to extract.

TDQS

B3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It conveys vault scope and action-specific behaviors (e.g., heading-aware retrieval, hybrid search), but does not cover all actions' details, rate limits, or output format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a clear purpose, but the action list is dense and could be more concise. It is not overly long, but some redundancy exists (e.g., 'search' vs 'semantic_search' both mention retrieval).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and low schema coverage (25%), the description fails to explain return values, edge cases, or behavioral details for many parameters. The tool is multi-action and moderately complex, so more completeness is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25%, yet the description does not describe any parameters beyond the actions. Parameters like maxChunks, heading, headingDepth, directory, and items remain unexplained, requiring the agent to infer from schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Read and search markdown notes' which clearly identifies the verb and resource. The list of actions further clarifies capabilities, but sibling tools (edit, system, vault, workflow) are not explicitly contrasted.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides brief explanations for each action (e.g., 'search uses TF-IDF'), giving some guidance on when to use each. However, it does not explicitly state when to prefer this tool over siblings or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

workflowWorkflowC

Manage optional agent workflow state for this vault (general markdown notes vault): status, transition, history, reset. Typical flow: search → open_note → save → done; read vault://overview for usage guidance.

ParametersJSON Schema

Name	Required	Description	Default
`action`	Yes
`transition`	No

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully disclose behavior. It lists actions but does not explain side effects, required permissions, or what happens on transition/reset. The referral to an external document for usage guidance leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively short and front-loaded with the main purpose. However, it packs multiple concepts (actions, flow, external reference) into one sentence, which may reduce clarity. It could be restructured for better readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, no annotations, and 0% schema coverage, the description is insufficient. It fails to explain return values, edge cases, or how to correctly use the transition parameter. The tool is too complex for such sparse documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must add meaning. It mentions actions but does not clarify the 'transition' parameter beyond its type. No detail on expected values or behavior, leaving the agent without needed context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool manages agent workflow state for a vault, listing specific actions (status, transition, history, reset). It provides a typical flow and references external guidance, making the purpose discernible and distinct from sibling tools like edit or view.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a typical flow (search → open_note → save → done) and suggests reading vault://overview for usage. However, it does not explicitly state when to use this tool versus siblings like system or vault, nor does it mention when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0

Disambiguation4/5

Tools have distinct purposes overall, but there is some overlap between 'edit' and 'vault' (both modify notes) and between 'vault' and 'view' (both read notes). Descriptions help clarify boundaries, but slight ambiguity remains.

Naming Consistency2/5

Tool names are single words and lowercase, but they do not follow a consistent verb_noun pattern. Names like 'edit', 'system', 'vault', 'view', 'workflow' are more categorical than action-oriented, deviating from common MCP naming conventions.

Tool Count5/5

With 5 tools, the server is well-scoped for a markdown vault. Each tool covers a distinct area (editing, administration, CRUD, reading/searching, workflow), and none seem extraneous.

Completeness4/5

The tool set covers CRUD operations, advanced editing, searching, system management, and workflow state. Minor gaps like renaming or moving notes exist, but core functionality is solidly addressed.

Maintenance

ActivityInactive

ResponsivenessWithin a week

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

hjarni AOAuth
com.hjarni
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Note Taking Workplace & Productivity
3
Mirror Memory MCP Server
io.github.Tr1ckyMag1ca1
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Knowledge & Memory Search Note Taking
2
DocsMint
io.github.HiAi-gg
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
Documentation Access RAG Systems Knowledge & Memory
171
trip2g A
io.github.trip2g
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
RAG Systems Note Taking Search
11237

Related MCP Servers

Obsidian MCP (pgvector +
Note Taking Knowledge & Memory Search
maxkuminov
A
license
A
quality
A
maintenance
Self-hosted MCP server for Obsidian with semantic + full-text search over PostgreSQL/pgvector, wikilink graph traversal, atomic note CRUD, OAuth 2.0, and a self-describing vault guide.
Updated 5 days ago (2026-08-30 01:44 UTC)
25
11
MIT
Optimike Obsidian MCP
Note Taking Knowledge & Memory Search
optimikelabs
A
license
Not graded
quality
A
maintenance
MCP server for Obsidian that exposes tools for reading/writing notes, managing frontmatter and tags, querying Tasks, semantic search, and interacting with Obsidian Bases, with shared local caching and support for various runtime modes.
Updated 6 hours ago (2026-09-03 13:35 UTC)
39
Apache 2.0
obsidian-modified-mcp-server
Note Taking Knowledge & Memory Search
marwansaab
A
license
A
quality
D
maintenance
TypeScript MCP server for Obsidian with core vault operations, graph analytics, and semantic search.
Updated 4 months ago (2026-05-02 15:59 UTC)
32
17
MIT
obsidian-brain
Note Taking Knowledge & Memory Search
sweir1
A
license
A
quality
D
maintenance
A standalone Node MCP server that provides semantic search, knowledge graph, and vault editing over an Obsidian vault. It runs locally as a single stdio process without requiring an Obsidian plugin for core functionality.
Updated 22 days ago (2026-08-12 20:32 UTC)
18
192
10
Apache 2.0

Appeared in Searches

GitHub repository for litopys-dev/litopys project

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wirux/mcp-markdown-vault'

If you have feedback or need assistance with the MCP directory API, please join our Discord server