Reported issues for Markdown Vault MCP
Pod holds 15 of 15 GitHub reports that passed its relevance review. This can include external user reports, maintainer-confirmed bugs, and concrete feature gaps. Treat them as evidence to inspect, not a count of distinct defects.
Back to Markdown Vault MCP.
Most discussed
[Bug]: OKF_WRITE index.md goes stale after rename/delete/move and after pulled or watched external changes
What happened?
With OKF_WRITE enabled, a folder's generated index.md reflects the folder's notes only as of the last MCP write / edit / append into that same folder. Changes that arrive any other way leave it stale until such a write happens to land there.
Observed
[verified: read src/markdown_vault_mcp/_okf_convention.py and facets/writer.py at 390d4e8b] The ConventionMaintainer is invoked from exactly three places: the writer facet's write, edit, and append.…
Read the thread · 2026-09-07 · open · 2 comments
Track upstream FastMCP fix: OIDCProxy well-known route ignores base_url subpath
Problem
FastMCP's OIDCProxy always registers /.well-known/oauth-authorization-server at the host root, regardless of any base_url subpath. This prevents shared-hostname OIDC subpath deployments where multiple OAuth services share one hostname (e.g., https://example.com/app1 and https://example.com/app2).
Tracked in our deployment docs as the "Shared-hostname limitation" in docs/deployment/oidc.md.
Context: #148, PR #151.
Root Cause
OIDCProxy.get_well_known_routes()…
Read the thread · 2026-03-13 · open · 1 comment
[Bug]: READ_ONLY=true with OKF_WRITE=true is accepted silently and undocumented
What happened?
MARKDOWN_VAULT_MCP_READ_ONLY=true together with MARKDOWN_VAULT_MCP_OKF_WRITE=true (and any OKF_VERIFY value) starts without a word: the write tools are hidden, so nothing is ever stamped or maintained, and no log line or document says that the OKF write setting is inert on this instance.
Observed
[verified: read src/markdown_vault_mcp/config_sections/content.py validate() at 2019a657; grep of src/ for any read_only/okf cross-check] The validation rules cover…
Read the thread · 2026-09-09 · open · 0 comments
[Bug]: stats.okf and config://vault do not report the OKF write state the design says they expose
What happened?
docs/design/okf.md §2 ("Detection") states that the detection result "(mode, declared version, effective read/write state) is exposed via stats and config://vault". Neither surface reports the write state: an operator cannot tell from the server whether OKF_WRITE is in effect.
Observed
[verified: read src/markdown_vault_mcp/_server_resources.py and managers/search.py okf_stats at 2019a657] config://vault carries okf_mode, okf_active and…
Read the thread · 2026-09-09 · open · 0 comments
[Bug]: the OKF instruction snippet tells the agent to update log.md/index.md while OKF_WRITE has the server regenerate them
What happened?
With OKF_WRITE=true, the server maintains each written folder's index.md and log.md itself, and at the same time its instruction snippet tells every agent, on any OKF-active vault, "For edits, update 'log.md'/'index.md'". An agent that follows the instruction edits index.md; the next note write into that folder regenerates the listing wholesale and the agent's edit is gone, with nothing reporting it.
Observed
`[verified: read…
Read the thread · 2026-09-09 · open · 0 comments
[Feature]: an operator-configured default type for untyped notes arriving by ingest, at OKF_WRITE=own
What problem does this solve?
Notes created in Obsidian carry no frontmatter unless the human inserted a template by hand (obsidian.md/help/plugins/templates, fetched 2026-09-08: templates are inserted on command, not on creation). Every such note leaves the bundle non-conformant until someone types it, and the PARA guide already recommends a placeholder type: Capture for inbox notes that are typed later.
Desired outcome
At OKF_WRITE=own only, an operator may configure a…
Read the thread · 2026-09-08 · open · 0 comments
[Feature]: the type filter accepts an absence value so untyped notes can be listed
What problem does this solve?
A note created outside the server arrives without type. okf_validate lists it under missing_type and stats.okf counts it, but an agent working from search or list_documents cannot ask for such notes: type is deliberately not an OKF filter dimension (OKF_FILTER_KEYS excludes it: "a plain indexed tag lookup with no special semantics, so the ordinary document_tags path handles it") and that equality lookup has no value that means "absent"…
Read the thread · 2026-09-08 · open · 0 comments
[Feature]: at OKF_WRITE=own, reconcile generated and verified on notes written elsewhere from git evidence
What problem does this solve?
A note whose frontmatter the server stamped and that a human then edited in another clone arrives by pull with generated describing bytes that no longer exist and verified still attesting them; the next server write of that note fixes both, and until then every other OKF consumer of the bundle reads a lie [verified: apply_okf_write_stamp runs only on the server's own write/edit path, _okf_write.py]. The sibling read-side issue makes this server's answers…
Read the thread · 2026-09-08 · open · 0 comments
Most recent
[Feature]: index.md and log.md are read-only to the client while the server maintains them
What problem does this solve?
With OKF_WRITE on, the server regenerates index.md and appends to log.md, and an agent can still write, edit, append, delete or rename onto those paths; the maintainer merely skips its own upkeep for such a write [verified: _okf_convention.py maintain() at cec05c84; no reserved-name check in managers/document.py or facets/writer.py]. The agent's version is then destroyed by the next regeneration, silently. The owner (2026-09-08): "log.md and…
Read the thread · 2026-09-08 · open · 0 comments
[Feature]: a log entry summarised from the note's cumulative daily diff when no intent is declared
What problem does this solve?
When no intent is declared for a changed note, the only honest entry text the server can produce is the file list, which says nothing a reader of the knowledge wants. The server already has a provider-neutral LLM seam (summarizer.py, OpenAI-compatible, chosen by #915) that nothing on the write or ingest path uses [verified: summarizer.py; grep of managers/ and git/]. Under the 2026-07-28 revision sampling is deprecated and "integrate directly with LLM…
Read the thread · 2026-09-08 · open · 0 comments
[Feature]: one ingest event from the reindex naming the paths the server did not write
What problem does this solve?
Changes that reach the vault by a pull or the file watcher are indexed and nothing else happens: no index.md refresh (#1392), no log entry, no provenance check, no warning (#1394). [verified: domain.py on_pull → reindex; _file_watcher.py → reindex; ConventionMaintainer is called only from the writer facet's write/edit/append] The incremental reindex is the only place that knows which paths changed on either route, and it reports a delta only in some…
Read the thread · 2026-09-08 · open · 0 comments
[Feature]: OKF ownership as three independent switches: OKF_WRITE stamps, OKF_MAINTAIN owns the reserved files, OKF_RECONCILE repairs external notes
What problem does this solve?
OKF_WRITE is a boolean that bundles three behaviours with different risk: provenance stamps on the server's own writes (cannot conflict with anyone), the okf_verify tool, and maintenance of the reserved index.md / log.md (the source of every multi-maintainer conflict in #1391–#1396). [verified: config.py okf_write help text and _okf_convention.py at cec05c84] An operator who wants stamps while another party maintains the reserved files has no…
Read the thread · 2026-09-08 · open · 0 comments
[Feature]: the conventions file is overwritable and deletable by the agent it instructs
What problem does this solve?
The per-folder conventions file (_conventions.md by default, MARKDOWN_VAULT_MCP_CONVENTIONS_FILE) is the operator's instruction to the agent: it is surfaced on get_conventions and attached to every write result so the model follows it. Nothing stops the same model from rewriting or deleting it through the ordinary write tools.
[verified: reproduced at a677cfe0 through the library facade] On a vault whose root _conventions.md carried frontmatter and…
Read the thread · 2026-09-08 · open · 0 comments
[Feature]: auto-commit subjects written by the configured LLM backend from the diff, with the mechanical subject kept as a fallback
What problem does this solve?
Every auto-commit this server makes carries a mechanical subject: write: guides/a.md, edit: guides/a.md, or the tool name for a batched call (okf_convert_links: 2,595 files) [verified: read src/markdown_vault_mcp/git/strategy.py _stage_and_commit and _commit_batch at fa94472b]. The subject says which file changed and never what changed. Three readers pay for that:
git logon the vault, where a day of agent work reads as a column ofwrite:lines.…
Read the thread · 2026-09-08 · open · 0 comments
feat: get_link_graph — subgraph exploration around seed notes
Problem
There is no way to explore the neighbourhood around a set of notes beyond one hop. get_context provides the immediate 1-hop neighborhood, but understanding the broader cluster structure requires expanding to 2+ hops.
Background
Spun out from #203. Lower priority than get_connection_path (separate issue). Useful for MOC creation and cluster visualization in Zettelkasten workflows.
Design decisions (resolved in #203 discussion):
- Python BFS from seed paths,…
Read the thread · 2026-03-15 · open · 0 comments
The remaining reports are on the project's issue tracker.