# 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](/mcp/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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1392) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/152) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1434) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1432) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1431) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1422) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1421) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1420) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1419) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1418) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1414) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1412) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1411) · 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 log` on the vault, where a day of agent work reads as a column of `write:` lines.… [Read the thread](https://github.com/pvliesdonk/markdown-vault-mcp/issues/1405) · 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](https://github.com/pvliesdonk/markdown-vault-mcp/issues/225) · 2026-03-15 · open · 0 comments The remaining reports are on [the project's issue tracker](https://github.com/pvliesdonk/markdown-vault-mcp/issues).