write-frontmatter-merge

Call the obsidian-router merge_frontmatter MCP tool with arguments parsed from $ARGUMENTS.

Arguments

Required:

• path — file path relative to vault root.
• values — object map of keys/values to set.

Optional:

• vault — omit for default.
• createIfMissing — create absent keys. Default true.
• ifMatch — a contentSha256 from a prior get_file. Checked ONCE before any key is written; a mismatch throws a 409 before the first mutation. Guards against merging into a file that changed since you read it (it does not make the multi-key update atomic — see the warning below).

Argument parsing from $ARGUMENTS

• path=X k1=v1 k2=v2 k3=v3 — most natural form
• path=X values={"k1":"v1","k2":"v2"} — JSON-explicit form
• the user might phrase it conversationally: "marque le trade comme closed avec outcome=stopped" → infer values

Type inference per value

• numeric → number
• true/false → boolean
• null → null
• [...] → JSON array
• {...} → JSON object
• otherwise → string

⚠️ Not atomic on its own

Called directly, this is NOT atomic. If applying 5 updates and the 3rd fails, the first two are already applied. The tool returns a per-key status — surface that result honestly:

• N succeeded, M failed
• list the failed keys with their error

To make it all-or-nothing (v0.66.0+, borrowing C2): run it as a write_bundle step. The bundle captures the file's content before the first key is written, and treats a partial merge (failed > 0) as a failed step — so the file goes back to exactly what it was:

write_bundle({
  vault, steps: [
    { op: "merge_frontmatter", path: "wiki/<page>.md", values: { status: "closed", outcome: "tp1" } }
  ]
})

Then read outcome: applied or rolled-back, never a half-updated file. This is the intended remedy — see the write-bundle skill. The older workaround (read the frontmatter, modify it client-side, write-create-or-replace the whole file) still works but rewrites the body too.

On failure — remediate, NEVER fall back to filesystem writes

If the call fails entirely (not a per-key partial failure), do NOT silently redo it with direct-filesystem tools (Read/Edit/Write on the vault's real path):

• Connection error (ECONNREFUSED, timeout) → vault closed; list_vaults, then ask the user to open it via the openUri link and wait.
• Validation / API error (HTTP 4xx) → fix the arguments — still through the router.

Rationale + message template: the default-vault-health-check convention (canonical source).