patch_vault_file silently corrupts content when targeting headings in nested sections

[grimlor]

Summary

patch_vault_file fails silently when the target heading exists inside a parent section. Instead of raising an error, it appends a new heading at the wrong level, corrupting the document structure.

Root Cause

The tool constructs heading targets using only the leaf heading name (e.g., "Section B"), but the underlying obsidian-local-rest-api passes this to markdown-patch, which requires fully-qualified hierarchical paths (e.g., "Parent Section\x1fSection B" using the unit separator \x1f as delimiter).

When the leaf-only lookup fails, markdown-patch falls through to createTargetIfMissing: true behavior and appends a new heading instead of raising PatchFailed. The caller receives no error signal.

Related Issues

• coddingtonbear/markdown-patch#7 — replace + createTargetIfMissing causes silent corruption instead of raising PatchFailed
• coddingtonbear/obsidian-local-rest-api#221 — MCP tool constructs leaf-only targets with no way for callers to provide qualified paths

Reproduction

1. Create a vault file with nested headings:

markdown

   # Parent Section
   ## Section B
   Original content

2. Call patch_vault_file targeting "Section B" with a replacement
3. Observe: a new ## Section B is appended at the end instead of replacing the existing one; no error is raised

Expected Behavior

Either:

• Accept fully-qualified heading paths (e.g., "Parent Section\x1fSection B") so callers can precisely target nested headings, or
• Raise a clear error when the target heading is ambiguous or not found at the top level

Workaround

Use create_vault_file for full rewrites. Heading-targeted patches via patch_vault_file are unreliable for any non-top-level heading.

[istefox]

For anyone still waiting on this — it's been fixed in the community fork at https://github.com/istefox/obsidian-mcp-connector (commit 046268b, released in v0.3.0).

You can install today via BRAT by pointing to istefox/obsidian-mcp-connector, or wait for the community-store entry pending at obsidianmd/obsidian-releases#11919.

Opening from the fork side to surface the pointer — feel free to close if you're satisfied, or keep open to track the upstream decision.

[folotp]

Confirming this bug on macOS 26.x with Obsidian 1.12.7, Local REST API 3.6.1, wrapper 0.2.27.

One point of scope rectification: in my repro the silent append-EOF fires even for root-level ## headings with no parent at all — not only for nested sections as the title suggests. Minimal fixture (all ASCII, no nesting):

## Section finale

Marker.

Call:

{
  "operation": "replace",
  "targetType": "heading",
  "target": "Section finale",
  "content": "REPLACED"
}

Result: "File patched successfully"; the original ## Section finale is untouched; REPLACED is appended at EOF under a derived # Section finale (H1) line.

This lines up with the root cause described in #71 and coddingtonbear/markdown-patch#7 / coddingtonbear/obsidian-local-rest-api#221: any leaf-only lookup that markdown-patch cannot resolve falls through to createTargetIfMissing. A root-level ## is not stored under a top-level heading key either (there is no # root), so the leaf-only target "Section finale" never matches. The failure mode is identical to the nested case — only the scope is wider than the title suggests.

Minor ancillary finding during the same test session: the same silent createTargetIfMissing fallback fires on targetType: "block" when the block ^id sits inside a markdown table cell (in that case without the spurious derived heading prefix, which matches what you would expect since markdown-patch resolves ^id blocks rather than heading paths). Blocks outside tables resolve correctly and patch in place, so PR #72's Create-Target-If-Missing: false lever would also make the block path safe for callers that want an explicit error on missing targets.

[istefox]

Hi @folotp — thanks for the rigorous follow-up. Two separate things in your comment, so I'll split them:

1. Root-level ## heading silent append-EOF

This is the exact failure mode addressed by the heading-path resolution fix shipped in the community fork's v0.3.0 (istefox/obsidian-mcp-connector, stable through v0.3.5). The partial-name lookup ("Section finale") now resolves to the full hierarchical path before the PATCH is issued, so leaf-only targets at any nesting depth — including true root-level — should work. If you test it on the fork and the root ## case still misfires, that's a repro I need; otherwise this half of your report can close.

2. targetType: "block" with ^id inside a markdown table cell

Confirmed this is a new gap, not covered by the fork's current pre-processing. The heading-path resolution only kicks in when targetType === "heading" (see packages/mcp-server/src/features/local-rest-api/index.ts:419-422); block targets pass straight through to LRA. When LRA's markdown-patch can't locate a block ^id inside a table cell, the createTargetIfMissing: true default (upstream-compat) produces the same silent EOF append you described.

Two mitigations, in order of effort:

• Caller-side workaround (ready today): set createTargetIfMissing: false on the call. It's wired as a parameter on both patch_active_file and patch_vault_file since 0.3.0 and will surface an explicit HTTP 404 / error instead of silently creating the target at EOF. If you can confirm this clears the ambiguity for your block-in-table case on the fork, we have a clean narrative: "createTargetIfMissing: false for hostile inputs, everything else is safe at 0.3.0+".
• Wrapper-side client validation (if the above isn't enough): pre-validate that the resolved block/heading target exists in the file body before issuing the PATCH. This is more invasive — we'd be duplicating part of markdown-patch's logic wrapper-side — so I'd prefer to confirm the simpler mitigation suffices first.

Would you mind trying the createTargetIfMissing: false variant on the fork and reporting back? Your methodical repros make this very tractable.