obsidian-mcp-server 3.5.4 → 3.6.0

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** obsidian-mcp-server
-**Version:** 3.5.4
+**Version:** 3.6.0
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
@@ -233,11 +233,15 @@ Services that accept `ctx` use the same resolver for parity. The Obsidian servic
 ```ts
 // inside obsidian-service.ts
 throw notFound(`Not found: ${display}`, data('note_missing'), { cause });
-// where data(reason) does: { path, reason, ...ctx.recoveryFor(reason) }
+// where data(reason) does: { ...callerIdentifier(path), reason, ...ctx.recoveryFor(reason) }
+// — `path` on a note route, `commandId` on /commands/<id>/, no key on routes
+// that carry no caller input (/, /tags/, /commands/, /search/).
 // The upstream body is never spread into `data` — it rides as `cause`, which
 // is non-enumerable and so reaches the log without reaching the client.
 ```
 
+A `fetch` that rejects before any response is classified inside the attempt (`#send`), so the retry decision sees the typed error: a refused certificate throws `ConfigurationError` `certificate_rejected` on the first attempt, an unreachable plugin throws `ServiceUnavailable` `obsidian_unreachable` and keeps the GET/PUT/DELETE retries. Both carry an inline `recovery.hint` rather than `ctx.recoveryFor`, because they reach every tool and resource — including resources with no `errors[]` — and the operator, not the agent, fixes them.
+
 **Fallback for ad-hoc throws** (no contract entry fits, prototype tools, service-layer code without a contract): use error factories.
 
 ```ts
@@ -262,7 +266,9 @@ src/
   services/
     obsidian/
       obsidian-service.ts               # Local REST API client (init/accessor pattern)
-      frontmatter-ops.ts                # YAML frontmatter parse/serialize/edit helpers
+      frontmatter-ops.ts                # YAML frontmatter parse/serialize/edit helpers + inline tag reader
+      markdown-blocks.ts                # Block structure (code, HTML, math, tables) for inline tag detection
+      patch-instruction.ts              # markdown-patch 1.x headers / 2.0 instructions, format negotiation, 2.0 map flattening
       section-extractor.ts              # Heading/block/frontmatter section extraction
       types.ts                          # Domain types (NoteJson, NoteTarget, etc.)
   mcp-server/

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** obsidian-mcp-server
-**Version:** 3.5.4
+**Version:** 3.6.0
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
@@ -233,11 +233,15 @@ Services that accept `ctx` use the same resolver for parity. The Obsidian servic
 ```ts
 // inside obsidian-service.ts
 throw notFound(`Not found: ${display}`, data('note_missing'), { cause });
-// where data(reason) does: { path, reason, ...ctx.recoveryFor(reason) }
+// where data(reason) does: { ...callerIdentifier(path), reason, ...ctx.recoveryFor(reason) }
+// — `path` on a note route, `commandId` on /commands/<id>/, no key on routes
+// that carry no caller input (/, /tags/, /commands/, /search/).
 // The upstream body is never spread into `data` — it rides as `cause`, which
 // is non-enumerable and so reaches the log without reaching the client.
 ```
 
+A `fetch` that rejects before any response is classified inside the attempt (`#send`), so the retry decision sees the typed error: a refused certificate throws `ConfigurationError` `certificate_rejected` on the first attempt, an unreachable plugin throws `ServiceUnavailable` `obsidian_unreachable` and keeps the GET/PUT/DELETE retries. Both carry an inline `recovery.hint` rather than `ctx.recoveryFor`, because they reach every tool and resource — including resources with no `errors[]` — and the operator, not the agent, fixes them.
+
 **Fallback for ad-hoc throws** (no contract entry fits, prototype tools, service-layer code without a contract): use error factories.
 
 ```ts
@@ -262,7 +266,9 @@ src/
   services/
     obsidian/
       obsidian-service.ts               # Local REST API client (init/accessor pattern)
-      frontmatter-ops.ts                # YAML frontmatter parse/serialize/edit helpers
+      frontmatter-ops.ts                # YAML frontmatter parse/serialize/edit helpers + inline tag reader
+      markdown-blocks.ts                # Block structure (code, HTML, math, tables) for inline tag detection
+      patch-instruction.ts              # markdown-patch 1.x headers / 2.0 instructions, format negotiation, 2.0 map flattening
       section-extractor.ts              # Heading/block/frontmatter section extraction
       types.ts                          # Domain types (NoteJson, NoteTarget, etc.)
   mcp-server/

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-3.5.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/obsidian-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/obsidian-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/obsidian-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-3.6.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/obsidian-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/obsidian-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/obsidian-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -60,7 +60,7 @@ Vault-note and tag data are also reachable via tools — `obsidian_get_note` for
 
 - `format: "content" | "full" | "document-map" | "section"` selects the projection; `full` accepts `includeLinks: true` for outgoing wiki/markdown links (vault-internal only — external URLs are filtered)
 - Addressed by vault `path`, the `active` file, or a `periodic` note (`daily` / `weekly` / `monthly` / `quarterly` / `yearly`)
-- Heading sections use `Parent::Child` syntax; a bare leaf name matching several headings returns the first match and lists every colliding path in `candidates`
+- Heading sections use `Parent::Child` syntax and find headings the way the document map does — setext headings (underlined with `===` or `---`) count, `#` lines inside a list item, HTML block, or fence do not — so every heading path the map lists reads back as itself, over the same span a section write edits; a bare leaf name matching several headings, or a full path that repeats in the note, returns the first match and lists every colliding path in `candidates`
 - Forgiving `path` resolution: a case-mismatched path retries against the canonical filename, an ambiguous case match fails with `Conflict`, and a `NotFound` carries `Did you mean: …?` suggestions when near-matches exist
 - Typed errors include `note_missing`, `path_forbidden`, `no_active_file`, `periodic_unsupported` / `periodic_disabled`, and `path_traversal`
 
@@ -95,8 +95,8 @@ Vault-note and tag data are also reachable via tools — `obsidian_get_note` for
 ### `obsidian_search_notes` <sub>tool</sub>
 
 - `mode: "text" | "jsonlogic"` always; `"omnisearch"` is added to the schema only when the Omnisearch plugin's HTTP server is reachable at startup (restart to re-probe)
-- `text` — substring match with `contextLength`-sized context windows (default 100) and an optional `pathPrefix`; `jsonlogic` — a JSONLogic tree with `var` paths into `path` / `content` / `frontmatter.<key>` / `tags` / `stat.{ctime,mtime,size}`, plus `glob` / `regexp` operators taking `[PATTERN, VALUE]`; `omnisearch` — BM25-ranked, quoted phrases, `-exclusion`, `path:` / `ext:` filters, typo tolerance, PDF/OCR via Text Extractor, hard-capped at 50 upstream hits (`truncated: true` when likely hit)
-- Cursor pagination — omit `cursor` for page one, pass `nextCursor` from the prior response; text-mode hits additionally clip to `maxMatchesPerHit` (default 10), flagged with `truncated` / `totalMatches`
+- `text` — whitespace-split tokens, all required, each matched case-insensitively as a substring (quotes are literal, so there is no phrase operator), with `contextLength`-sized context windows (default 100) and an optional `pathPrefix`; tokens within 2 × `contextLength` of each other, such as a phrase's words, share one match location; `jsonlogic` — a JSONLogic tree with `var` paths into `path` / `content` / `frontmatter.<key>` / `tags` / `stat.{ctime,mtime,size}`, plus `glob` / `regexp` operators taking `[PATTERN, VALUE]`; `omnisearch` — BM25-ranked, quoted phrases, `-exclusion`, `path:` / `ext:` filters, typo tolerance, PDF/OCR via Text Extractor, hard-capped at 50 upstream hits (`truncated: true` when likely hit)
+- Cursor pagination — omit `cursor` for page one, pass `nextCursor` from the prior response; text-mode hits additionally clip to `maxMatchesPerHit` match locations (default 10), flagged with `truncated` / `totalMatches`
 - No dedicated backlinks tool — express "what links here" via `jsonlogic`: `{"regexp": ["\\[\\[Target Note(\\||#|\\]\\])", {"var": "content"}]}`
 
 ---
@@ -104,7 +104,7 @@ Vault-note and tag data are also reachable via tools — `obsidian_get_note` for
 ### `obsidian_write_note` <sub>tool</sub>
 
 - Without `section` — full-file write; refuses to clobber an existing note unless `overwrite: true` (`file_exists` conflict otherwise, naming the surgical-edit tools as the alternative)
-- With `section` — `PATCH`-with-replace against a heading/block/frontmatter target, leaving the rest of the file untouched (`overwrite` is ignored); a bare heading leaf shared by several headings fails with `ambiguous_section`
+- With `section` — `PATCH`-with-replace against a heading/block/frontmatter target, leaving the rest of the file untouched (`overwrite` is ignored); a bare heading leaf shared by several headings fails with `ambiguous_section` unless one of them has no parent heading, which the write then targets, and a full heading path that repeats in the note fails the same way
 - Output reports `created`, plus `previousSizeInBytes` / `currentSizeInBytes` on every call to spot an accidental clobber or a mistyped path
 
 ---
@@ -112,7 +112,7 @@ Vault-note and tag data are also reachable via tools — `obsidian_get_note` for
 ### `obsidian_append_to_note` <sub>tool</sub>
 
 - Without `section` — appends to an existing file, or creates it with the given content as the whole body (`created: true` flags the second case)
-- With `section` — appends to a heading/block/frontmatter target; the file must already exist, and `createTargetIfMissing: true` brings the section itself into existence
+- With `section` — appends to a heading/block/frontmatter target; the file must already exist, and `createTargetIfMissing: true` brings the section itself into existence. On plugin v5.0 and later, content appended to a heading is separated from the section's existing content by a blank line (except a list item appended to a section that ends in a list and has no sub-headings, which continues that list), and a heading in it must sit below the section's own level (`heading_outside_section` otherwise)
 - Block-reference targets concatenate with no separator — include a leading newline in `content` for one
 - `previousSizeInBytes` / `currentSizeInBytes` bracket every call for drift detection
 
@@ -120,9 +120,9 @@ Vault-note and tag data are also reachable via tools — `obsidian_get_note` for
 
 ### `obsidian_patch_note` <sub>tool</sub>
 
-- `operation: "append" | "prepend" | "replace"` against one heading, block reference, or frontmatter field per call
-- Heading targets accept the full `Parent::Child` path or an unambiguous bare leaf name; a leaf matching several headings fails with `ambiguous_section` and lists the candidates
-- `patchOptions`: `createTargetIfMissing`, `applyIfContentPreexists` (idempotency guard — otherwise `content_preexists`), `trimTargetWhitespace`
+- `operation: "append" | "prepend" | "replace"` against one heading, block reference, or frontmatter field per call; on plugin v5.0 and later, content appended or prepended to a heading is separated from the section's existing content by a blank line (except a list item appended to a section that ends in a list and has no sub-headings, or prepended to one that opens with a list, which continues that list), and a heading in it must sit below the section's own level (`heading_outside_section` otherwise)
+- Heading targets accept the full `Parent::Child` path or a bare leaf name; a leaf matching several headings fails with `ambiguous_section` and lists the candidates, unless one of them has no parent heading, which the patch then targets; a full path that repeats in the note fails with `ambiguous_section` too
+- `patchOptions`: `createTargetIfMissing`, `applyIfContentPreexists` (idempotency guard — otherwise `content_preexists`), `trimTargetWhitespace` (plugin v4.x only; v5.0 and later place the blank lines around inserted content themselves)
 
 ---
 
@@ -146,7 +146,8 @@ Vault-note and tag data are also reachable via tools — `obsidian_get_note` for
 ### `obsidian_manage_tags` <sub>tool</sub>
 
 - `operation: "add" | "remove" | "list"`; `location: "frontmatter"` (default, canonical `tags:` array) | `"inline"` (body `#tag`, `add` appends at end-of-file) | `"both"` (reconciles both)
-- Inline detection skips fenced/inline code spans, link spans (`[[...]]`, `[text](...)`, `[text][ref]`), and `\#`-escaped hashes, so a heading anchor or wikilink alias is never mistaken for a tag
+- Inline detection skips code (fenced, indented, and inline), wikilinks (`[[...]]`), images, a markdown link's destination or label (its text is read), HTML blocks and comments, and math (`$…$`, `$$…$$`), so a heading anchor or wikilink alias is never mistaken for a tag; `%% … %%` comments are still read, as Obsidian reads them
+- Inline tags follow Obsidian's grammar: a tag starts at line start, after whitespace, after another tag (`#a#b` is two tags), or right after markup such as `**`, `_…_`, `==`, `[`, a table cell's `|`, `<br>`, or a `\`-escape (`**#x**` is a tag; `(#x`, `.#x`, `a *#x`, and `\#x` are not) and runs through letters and digits in any script, emoji, `_`, `-`, and `/`, with at least one character that is not an ASCII digit (`#1990s`, `#café`, `#日本語`, and `#✅done` are tags; `#1984` is not)
 - `add` / `remove` report `applied` vs. `skipped` tags plus the full `tags` set after the change; `list` ignores the input `tags` array
 
 ---
@@ -312,7 +313,7 @@ MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
 ### Prerequisites
 
 - [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
-- The [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin, **v4.0.0 through v5.x**, installed and enabled in your vault. Generate an API key in **Settings → Community Plugins → Local REST API** and copy it into `OBSIDIAN_API_KEY`. Plugin v6.0 removes the markdown-patch 1.x wire format this server pins for section-targeted writes and the document map.
+- The [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin, **v4.0.0 or later**, installed and enabled in your vault. Generate an API key in **Settings → Community Plugins → Local REST API** and copy it into `OBSIDIAN_API_KEY`. Section-targeted writes and the document map speak markdown-patch 2.0 to plugin v5.0 and later and the 1.x format to v4.x; the server reads the plugin version once and picks the format itself. Two table-row writes (`contentType: "json"`) that markdown-patch 2.0 cannot express go out as 1.x on v5.x too: rows written under a heading, and rows written through a block ID on its own line below the table. Plugin v6.0 removes 1.x, so on v6.0 those two shapes fail; target the table by an ID on its last row instead.
 - Periodic-note targets (`target: { "type": "periodic" }`) work across that whole range: natively on plugin **v5.0.1 and earlier**, and on **v5.0.2 and later** — which moved the `/periodic/` routes out of the plugin — once the companion [periodic-notes API extension](https://github.com/coddingtonbear/obsidian-local-rest-api-periodic-notes) is installed. Without that extension on v5.0.2+, periodic targets fail with a `periodic_unsupported` error naming it; `obsidian://status` lists the registered extensions if you want to check first. Every other target type is unaffected.
 - An MCP client that can answer an input request (elicitation). `obsidian_delete_note` always asks for confirmation before deleting, so a client without that support can read and write notes but cannot delete one.
 - This server defaults to `http://127.0.0.1:27123` for simplicity. Enable **"Non-encrypted (HTTP) Server"** in the plugin settings to use it. To use the always-on HTTPS port instead, set `OBSIDIAN_BASE_URL=https://127.0.0.1:27124`; the plugin's self-signed cert is handled by `OBSIDIAN_VERIFY_SSL=false` (the default), which relaxes verification for this server's requests to that endpoint only.
@@ -349,8 +350,8 @@ MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
 | Variable | Description | Default |
 |:---------|:------------|:--------|
 | `OBSIDIAN_API_KEY` | **Required.** Bearer token for the Obsidian Local REST API plugin. | — |
-| `OBSIDIAN_BASE_URL` | Base URL of the Local REST API plugin. Use `https://127.0.0.1:27124` for the always-on HTTPS port (self-signed cert). A trailing slash is stripped at startup. | `http://127.0.0.1:27123` |
-| `OBSIDIAN_VERIFY_SSL` | Verify the TLS certificate. Default `false` because the plugin uses a self-signed cert. The relaxation is applied per request, to an `https:` `OBSIDIAN_BASE_URL` only — every other HTTPS connection the process makes still verifies normally, on both Bun and Node. | `false` |
+| `OBSIDIAN_BASE_URL` | Base URL of the Local REST API plugin. Use `https://127.0.0.1:27124` for the always-on HTTPS port (self-signed cert). A trailing slash is stripped at startup. When nothing answers there (Obsidian closed, plugin disabled, wrong host or port), calls fail with `obsidian_unreachable` — a `GET`, `PUT`, or `DELETE` after its retries, any other request on the first attempt. | `http://127.0.0.1:27123` |
+| `OBSIDIAN_VERIFY_SSL` | Verify the TLS certificate. Default `false` because the plugin uses a self-signed cert. The relaxation is applied per request, to an `https:` `OBSIDIAN_BASE_URL` only — every other HTTPS connection the process makes still verifies normally, on both Bun and Node. With `true`, a certificate the runtime does not trust fails every call on its first attempt with `certificate_rejected`. | `false` |
 | `OBSIDIAN_REQUEST_TIMEOUT_MS` | Per-request timeout in milliseconds. | `30000` |
 | `OBSIDIAN_ENABLE_COMMANDS` | Opt-in flag for the command-palette pair (`obsidian_list_commands` + `obsidian_execute_command`). Off by default — Obsidian commands are opaque and can be destructive. | `false` |
 | `OBSIDIAN_READ_PATHS` | Comma-separated vault-relative folder allowlist for read operations. Prefix-based with implicit recursion; case-insensitive; trailing slashes normalized. Unset = full vault. Write paths are implicitly readable. | unset |

package/changelog/3.5.x/3.5.5.md

@@ -0,0 +1,20 @@
+---
+summary: "TLS certificate rejection and an unreachable Local REST API now surface as typed, actionable errors instead of a hintless InternalError, multi-word text search and inline tag matching are fixed, and a section write to a repeated heading path is rejected instead of landing on the wrong occurrence."
+breaking: false
+security: false
+---
+
+# 3.5.5 — 2026-09-22
+
+## Fixed
+
+- **A rejected TLS certificate and an unreachable Local REST API now surface as typed errors** — `certificate_rejected` names the runtime's TLS code and points at `OBSIDIAN_VERIFY_SSL` / `OBSIDIAN_BASE_URL`; `obsidian_unreachable` covers a closed port, wrong host, or disabled plugin and keeps its GET/PUT/DELETE retries. Both used to surface as a hintless `InternalError` ([#133](https://github.com/cyanheads/obsidian-mcp-server/issues/133), [#136](https://github.com/cyanheads/obsidian-mcp-server/issues/136)).
+- **Error `data` no longer carries a route string as `path`** — a command-route error now carries `commandId`, and a route with no caller input (`/`, `/tags/`, `/search/`, …) carries neither ([#130](https://github.com/cyanheads/obsidian-mcp-server/issues/130)).
+- **A multi-word `obsidian_search_notes` text query merges its per-token spans into one match location** instead of returning a near-identical context window per token ([#117](https://github.com/cyanheads/obsidian-mcp-server/issues/117)); offsets are also corrected when the context window's edge splits a surrogate pair, and a span's subject (note body or filename) is read from the plugin's `match.source` when it sends one ([#135](https://github.com/cyanheads/obsidian-mcp-server/issues/135)).
+- **`#tag` detection now follows Obsidian's own grammar** — leading-digit and non-ASCII tags are read and written, HTML comments and math spans are skipped, and the left-boundary and all-digit rules match Obsidian's readback ([#127](https://github.com/cyanheads/obsidian-mcp-server/issues/127), [#138](https://github.com/cyanheads/obsidian-mcp-server/issues/138)).
+- **Inline tag scanning stays linear in note length** — the inline-math check finds each span's closer from a single pass over the note, so a paragraph of `$` signs that never close, such as a table of prices, is not rescanned from each one ([#143](https://github.com/cyanheads/obsidian-mcp-server/issues/143)).
+- **A document-map heading locator now round-trips through `obsidian_get_note` section reads at any depth** ([#128](https://github.com/cyanheads/obsidian-mcp-server/issues/128)), and a section write against a full path that repeats in the note is rejected with `ambiguous_section` instead of silently landing on the wrong occurrence ([#137](https://github.com/cyanheads/obsidian-mcp-server/issues/137)); `SectionSchema.target` and the write-tool descriptions document both cases ([#129](https://github.com/cyanheads/obsidian-mcp-server/issues/129)).
+
+## Dependencies
+
+- `@types/node` ^26.6.1 → ^26.6.2

package/changelog/3.6.x/3.6.0.md

@@ -0,0 +1,31 @@
+---
+summary: "obsidian_patch_note, obsidian_append_to_note, obsidian_write_note, and the document map now speak markdown-patch 2.0 on Local REST API v5.x, required before plugin v6.0 removes the 1.x format they used to pin."
+breaking: false
+security: false
+---
+
+# 3.6.0 — 2026-09-23
+
+## Added
+
+- **Section-targeted writes and the document map now speak markdown-patch 2.0**, negotiated once per service from the plugin's `GET /` capability report: a JSON instruction body on Local REST API v5.0 and later, 1.x request headers on v4.x. The supported plugin range widens from v4.0–v5.x to v4.0 and later ([#102](https://github.com/cyanheads/obsidian-mcp-server/issues/102)).
+
+## Changed
+
+- **On plugin v5.x, content appended or prepended to a heading is separated from the section's existing content by a blank line**, except a list item continuing a list at the section's own edge, which stays tight instead of gaining paragraph spacing on every append ([#145](https://github.com/cyanheads/obsidian-mcp-server/issues/145)).
+- **On plugin v5.x, a heading at or above the target section's own level in written content is rejected** with the new `heading_outside_section` reason instead of silently closing the section early.
+- **A patch refusal that isn't a missing target now reports `patch_rejected`** instead of the misleading `section_target_missing`.
+- **Two table-row writes still go out as markdown-patch 1.x on v5.x** — rows written under a heading, and rows addressed through a standalone `^id` line — since 2.0 cannot express either shape.
+- **A failing `GET /` now fails the section write or document-map read with its classified error** instead of guessing a markdown-patch format.
+- **`patchOptions.trimTargetWhitespace` is honored on plugin v4.x only**; v5.0 and later place the blank lines around inserted content themselves and ignore it.
+
+## Fixed
+
+- **`obsidian_manage_tags` reads inline tags against a block-structure scan** instead of a flat regex split, so indented code, glued tags (`#a#b`), underscore boundaries (`_#t_`), table cells, narrowed link/fence/HTML-tag grammars, and HTML blocks beyond `<div>`/`<p>` all agree with Obsidian's own metadata cache ([#139](https://github.com/cyanheads/obsidian-mcp-server/issues/139), [#140](https://github.com/cyanheads/obsidian-mcp-server/issues/140), [#144](https://github.com/cyanheads/obsidian-mcp-server/issues/144)).
+- **`obsidian_get_note` `format: "section"` finds headings the way the document map does** — lexed with `marked`, so setext headings count and a `#` line inside a list item or HTML block does not — so a section read now covers exactly the span a write edits. The plugin v4.x repeated-heading check reads the same scan, and `obsidian_write_note` strips a leading setext heading that names the section as it does an ATX one ([#141](https://github.com/cyanheads/obsidian-mcp-server/issues/141)).
+- **On plugin v5.x, a heading write to a CRLF note lands at the section's edge**; the 1.x format placed it mid-line, offset by the note's line endings ([#102](https://github.com/cyanheads/obsidian-mcp-server/issues/102)).
+- **`obsidian_get_note` `format: "document-map"` lists headings in note order when a heading name is integer-like** (`## 2025` above `## 2024`), where the map listed those names first; the `candidates` of an `ambiguous_section` error follow the same order ([#102](https://github.com/cyanheads/obsidian-mcp-server/issues/102)).
+
+## Dependencies
+
+- `marked` added at `17.0.6` (pinned exact — the heading scan's tokenizer overrides read `marked`'s rule internals, and the pin matches the major the plugin's own markdown-patch lexes with)

package/dist/mcp-server/tools/definitions/_shared/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../../../src/mcp-server/tools/definitions/_shared/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,4EAA4E;AAC5E,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;2BA4BvB,CAAC;AAEH,yCAAyC;AACzC,eAAO,MAAM,aAAa;;;;;;;iBAUxB,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;kBAiBlB,CAAC;AAEd,eAAO,MAAM,iBAAiB;;;GAK3B,CAAC;AAEJ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACtD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../../../src/mcp-server/tools/definitions/_shared/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,4EAA4E;AAC5E,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;2BA4BvB,CAAC;AAEH,yCAAyC;AACzC,eAAO,MAAM,aAAa;;;;;;;iBAUxB,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;kBAmBlB,CAAC;AAEd,eAAO,MAAM,iBAAiB;;;GAK3B,CAAC;AAEJ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACtD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/_shared/schemas.js

@@ -43,7 +43,7 @@ export const SectionSchema = z.object({
     target: z
         .string()
         .min(1)
-        .describe('Heading name — either the full path (`"Parent::Child"`) or a bare leaf name that matches exactly one heading — a block reference without the leading caret (e.g. "2d9b4a", not "^2d9b4a"), or a frontmatter field name.'),
+        .describe('Heading, block, or frontmatter locator. Heading: the full `Parent::Child` path as `obsidian_get_note` `format: "document-map"` lists it, or a bare leaf name matched at any depth. A leaf shared by several headings reads the first (every full path comes back in `candidates`); a write rejects it with `ambiguous_section`, unless one of them has no parent heading, in which case the write targets that one. A full path that occurs more than once in the note reads the first; a write rejects it with `ambiguous_section`. Block: the reference ID without the caret (e.g. "2d9b4a", not "^2d9b4a"). Frontmatter: the field name.'),
 });
 export const PatchOptionsSchema = z
     .object({
@@ -58,7 +58,7 @@ export const PatchOptionsSchema = z
     trimTargetWhitespace: z
         .boolean()
         .default(false)
-        .describe('Trim whitespace from the target section before applying the operation.'),
+        .describe('Trim whitespace from the target section before applying the operation. Honored by Local REST API v4.x only; v5.0 and later place the blank lines around inserted content themselves and ignore it.'),
 })
     .optional();
 export const ContentTypeSchema = z

package/dist/mcp-server/tools/definitions/_shared/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../../../src/mcp-server/tools/definitions/_shared/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACvD,CAAC;SACE,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,iCAAiC,CAAC;QACnE,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,kEAAkE,CAAC;KAChF,CAAC;SACD,QAAQ,CAAC,4CAA4C,CAAC;IACzD,CAAC;SACE,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,8CAA8C,CAAC;KACnF,CAAC;SACD,QAAQ,CAAC,gEAAgE,CAAC;IAC7E,CAAC;SACE,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,oDAAoD,CAAC;QAC1F,MAAM,EAAE,CAAC;aACN,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;aAC3D,QAAQ,CAAC,4BAA4B,CAAC;QACzC,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,KAAK,CAAC,qBAAqB,CAAC;aAC5B,QAAQ,EAAE;aACV,QAAQ,CAAC,mDAAmD,CAAC;KACjE,CAAC;SACD,QAAQ,CAAC,6CAA6C,CAAC;CAC3D,CAAC,CAAC;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;SACzC,QAAQ,CAAC,mEAAmE,CAAC;IAChF,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,yNAAyN,CAC1N;CACJ,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,qBAAqB,EAAE,CAAC;SACrB,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,yEAAyE,CAAC;IACtF,uBAAuB,EAAE,CAAC;SACvB,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,iOAAiO,CAClO;IACH,oBAAoB,EAAE,CAAC;SACpB,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,wEAAwE,CAAC;CACtF,CAAC;KACD,QAAQ,EAAE,CAAC;AAEd,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,IAAI,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;KAC1B,OAAO,CAAC,UAAU,CAAC;KACnB,QAAQ,CACP,qPAAqP,CACtP,CAAC"}
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../../../src/mcp-server/tools/definitions/_shared/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACvD,CAAC;SACE,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,iCAAiC,CAAC;QACnE,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,kEAAkE,CAAC;KAChF,CAAC;SACD,QAAQ,CAAC,4CAA4C,CAAC;IACzD,CAAC;SACE,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,8CAA8C,CAAC;KACnF,CAAC;SACD,QAAQ,CAAC,gEAAgE,CAAC;IAC7E,CAAC;SACE,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,oDAAoD,CAAC;QAC1F,MAAM,EAAE,CAAC;aACN,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;aAC3D,QAAQ,CAAC,4BAA4B,CAAC;QACzC,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,KAAK,CAAC,qBAAqB,CAAC;aAC5B,QAAQ,EAAE;aACV,QAAQ,CAAC,mDAAmD,CAAC;KACjE,CAAC;SACD,QAAQ,CAAC,6CAA6C,CAAC;CAC3D,CAAC,CAAC;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;SACzC,QAAQ,CAAC,mEAAmE,CAAC;IAChF,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,6mBAA6mB,CAC9mB;CACJ,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,qBAAqB,EAAE,CAAC;SACrB,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,yEAAyE,CAAC;IACtF,uBAAuB,EAAE,CAAC;SACvB,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,iOAAiO,CAClO;IACH,oBAAoB,EAAE,CAAC;SACpB,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,oMAAoM,CACrM;CACJ,CAAC;KACD,QAAQ,EAAE,CAAC;AAEd,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,IAAI,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;KAC1B,OAAO,CAAC,UAAU,CAAC;KACnB,QAAQ,CACP,qPAAqP,CACtP,CAAC"}

package/dist/mcp-server/tools/definitions/index.d.ts

@@ -311,44 +311,25 @@ export declare const writeToolDefinitions: (import("@cyanheads/mcp-ts-core").Too
         }>;
         date: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>], "type">;
-    section: import("zod").ZodObject<{
+    content: import("zod").ZodString;
+    section: import("zod").ZodOptional<import("zod").ZodObject<{
         type: import("zod").ZodEnum<{
             block: "block";
             frontmatter: "frontmatter";
             heading: "heading";
         }>;
         target: import("zod").ZodString;
-    }, import("zod/v4/core").$strip>;
-    operation: import("zod").ZodEnum<{
-        append: "append";
-        prepend: "prepend";
-        replace: "replace";
-    }>;
-    content: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
     contentType: import("zod").ZodDefault<import("zod").ZodEnum<{
         json: "json";
         markdown: "markdown";
     }>>;
-    patchOptions: import("zod").ZodOptional<import("zod").ZodObject<{
-        createTargetIfMissing: import("zod").ZodDefault<import("zod").ZodBoolean>;
-        applyIfContentPreexists: import("zod").ZodDefault<import("zod").ZodBoolean>;
-        trimTargetWhitespace: import("zod").ZodDefault<import("zod").ZodBoolean>;
-    }, import("zod/v4/core").$strip>>;
+    createTargetIfMissing: import("zod").ZodDefault<import("zod").ZodBoolean>;
 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
     path: import("zod").ZodString;
-    section: import("zod").ZodObject<{
-        type: import("zod").ZodEnum<{
-            block: "block";
-            frontmatter: "frontmatter";
-            heading: "heading";
-        }>;
-        target: import("zod").ZodString;
-    }, import("zod/v4/core").$strip>;
-    operation: import("zod").ZodEnum<{
-        append: "append";
-        prepend: "prepend";
-        replace: "replace";
-    }>;
+    sectionTargeted: import("zod").ZodBoolean;
+    sectionTarget: import("zod").ZodOptional<import("zod").ZodString>;
+    created: import("zod").ZodBoolean;
     previousSizeInBytes: import("zod").ZodNumber;
     currentSizeInBytes: import("zod").ZodNumber;
 }, import("zod/v4/core").$strip>, readonly [{
@@ -361,8 +342,8 @@ export declare const writeToolDefinitions: (import("@cyanheads/mcp-ts-core").Too
     readonly reason: "note_missing";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
-    readonly when: "The vault path does not resolve to an existing note.";
-    readonly recovery: "Verify the path with obsidian_list_notes or use obsidian_search_notes to locate the note.";
+    readonly when: "Section append targets a path that does not resolve to an existing note (PATCH requires the file to exist).";
+    readonly recovery: "Verify the path with obsidian_list_notes, or omit `section` to fall back to whole-file append (which creates the note if missing).";
 }, {
     readonly reason: "no_active_file";
     readonly thrownBy: "service";
@@ -391,20 +372,32 @@ export declare const writeToolDefinitions: (import("@cyanheads/mcp-ts-core").Too
     readonly reason: "section_target_missing";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "The named heading/block/frontmatter field does not exist in the note. Use `obsidian_get_note` with `format: \"document-map\"` to discover available targets.";
-    readonly recovery: "Call obsidian_get_note with format document-map to discover the available targets.";
+    readonly when: "`section` was provided but the named heading/block/frontmatter field does not exist in the note.";
+    readonly recovery: "Call obsidian_get_note with format document-map to discover available targets, or pass createTargetIfMissing: true to bring it into existence.";
 }, {
     readonly reason: "ambiguous_section";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Conflict;
-    readonly when: "A bare heading leaf name matches more than one heading in the note, so the write target is undetermined.";
-    readonly recovery: "Retry with one of the full Parent::Child heading paths listed in `candidates` on the error data.";
+    readonly when: "A bare heading leaf name matches more than one heading in the note, or the resolved full heading path occurs more than once, so the append target is undetermined.";
+    readonly recovery: "Retry with a distinct full Parent::Child heading path from `candidates` on the error data; when every candidate is the same path, rename the repeated headings first.";
 }, {
     readonly reason: "content_preexists";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "The supplied content already appears at the target — the patch was rejected to keep retries idempotent (the default).";
-    readonly recovery: "Pass `patchOptions.applyIfContentPreexists: true` to force-apply over preexisting content, or change the content to something not already present.";
+    readonly when: "Section append where the supplied content already appears at the target — rejected to keep retries idempotent (the default for the section path).";
+    readonly recovery: "Change the content to something not already present at the target, or use obsidian_patch_note with `patchOptions.applyIfContentPreexists: true` if a duplicate is intended.";
+}, {
+    readonly reason: "heading_outside_section";
+    readonly thrownBy: "service";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "On Local REST API v5.0 and later, content appended to a heading carries a heading at or above that section’s own level, which would have to sit outside the section.";
+    readonly recovery: "Append the heading at the parent section or at the end of the note (no `section`), or write it one level below the target section or deeper.";
+}, {
+    readonly reason: "patch_rejected";
+    readonly thrownBy: "service";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "The section exists but the plugin refused the content for it — table rows for a block that is not a table, a row with the wrong cell count, a frontmatter value that cannot merge, or content of the wrong shape.";
+    readonly recovery: "Read the target with obsidian_get_note format section, then send content that fits it — rows matching the table columns, or a value of the field’s own type.";
 }, {
     readonly reason: "path_is_directory";
     readonly thrownBy: "service";
@@ -434,33 +427,47 @@ export declare const writeToolDefinitions: (import("@cyanheads/mcp-ts-core").Too
         }>;
         date: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>], "type">;
-    content: import("zod").ZodString;
-    section: import("zod").ZodOptional<import("zod").ZodObject<{
+    section: import("zod").ZodObject<{
         type: import("zod").ZodEnum<{
             block: "block";
             frontmatter: "frontmatter";
             heading: "heading";
         }>;
         target: import("zod").ZodString;
-    }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>;
+    operation: import("zod").ZodEnum<{
+        append: "append";
+        prepend: "prepend";
+        replace: "replace";
+    }>;
+    content: import("zod").ZodString;
     contentType: import("zod").ZodDefault<import("zod").ZodEnum<{
         json: "json";
         markdown: "markdown";
     }>>;
-    overwrite: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    patchOptions: import("zod").ZodOptional<import("zod").ZodObject<{
+        createTargetIfMissing: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        applyIfContentPreexists: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        trimTargetWhitespace: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$strip>>;
 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
     path: import("zod").ZodString;
-    sectionTargeted: import("zod").ZodBoolean;
-    sectionTarget: import("zod").ZodOptional<import("zod").ZodString>;
-    created: import("zod").ZodBoolean;
+    section: import("zod").ZodObject<{
+        type: import("zod").ZodEnum<{
+            block: "block";
+            frontmatter: "frontmatter";
+            heading: "heading";
+        }>;
+        target: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>;
+    operation: import("zod").ZodEnum<{
+        append: "append";
+        prepend: "prepend";
+        replace: "replace";
+    }>;
     previousSizeInBytes: import("zod").ZodNumber;
     currentSizeInBytes: import("zod").ZodNumber;
 }, import("zod/v4/core").$strip>, readonly [{
-    readonly reason: "file_exists";
-    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Conflict;
-    readonly when: "Whole-file write was attempted against an existing note and `overwrite` was not set to `true`.";
-    readonly recovery: "Retry with overwrite true or use obsidian_patch_note for in-place edits.";
-}, {
     readonly reason: "path_forbidden";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Forbidden;
@@ -470,8 +477,8 @@ export declare const writeToolDefinitions: (import("@cyanheads/mcp-ts-core").Too
     readonly reason: "note_missing";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
-    readonly when: "Section replace targets a path that does not resolve to an existing note (PATCH requires the file to exist).";
-    readonly recovery: "Verify the path with obsidian_list_notes, or omit `section` to fall back to whole-file write (which creates the note when it is absent).";
+    readonly when: "The vault path does not resolve to an existing note.";
+    readonly recovery: "Verify the path with obsidian_list_notes or use obsidian_search_notes to locate the note.";
 }, {
     readonly reason: "no_active_file";
     readonly thrownBy: "service";
@@ -500,14 +507,32 @@ export declare const writeToolDefinitions: (import("@cyanheads/mcp-ts-core").Too
     readonly reason: "section_target_missing";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "`section` was provided but the named heading/block/frontmatter field does not exist in the note.";
-    readonly recovery: "Call obsidian_get_note with format document-map to discover available targets.";
+    readonly when: "The named heading/block/frontmatter field does not exist in the note. Use `obsidian_get_note` with `format: \"document-map\"` to discover available targets.";
+    readonly recovery: "Call obsidian_get_note with format document-map to discover the available targets.";
 }, {
     readonly reason: "ambiguous_section";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Conflict;
-    readonly when: "A bare heading leaf name matches more than one heading in the note, so the replacement target is undetermined.";
-    readonly recovery: "Retry with one of the full Parent::Child heading paths listed in `candidates` on the error data.";
+    readonly when: "A bare heading leaf name matches more than one heading in the note, or the resolved full heading path occurs more than once, so the write target is undetermined.";
+    readonly recovery: "Retry with a distinct full Parent::Child heading path from `candidates` on the error data; when every candidate is the same path, rename the repeated headings first.";
+}, {
+    readonly reason: "content_preexists";
+    readonly thrownBy: "service";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "The supplied content already appears at the target — the patch was rejected to keep retries idempotent (the default).";
+    readonly recovery: "Pass `patchOptions.applyIfContentPreexists: true` to force-apply over preexisting content, or change the content to something not already present.";
+}, {
+    readonly reason: "heading_outside_section";
+    readonly thrownBy: "service";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "On Local REST API v5.0 and later, the content of a heading write carries a heading at or above the target section’s own level, which would have to sit outside the section.";
+    readonly recovery: "Append the heading at the parent section or at the end of the note with obsidian_append_to_note, or write it one level below the target section or deeper.";
+}, {
+    readonly reason: "patch_rejected";
+    readonly thrownBy: "service";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "The target exists but the plugin refused the content for it — table rows for a block that is not a table, a row with the wrong cell count, a frontmatter value that cannot merge, or content of the wrong shape.";
+    readonly recovery: "Read the target with obsidian_get_note format section, then send content that fits it — rows matching the table columns, or a value of the field’s own type.";
 }, {
     readonly reason: "path_is_directory";
     readonly thrownBy: "service";
@@ -550,7 +575,7 @@ export declare const writeToolDefinitions: (import("@cyanheads/mcp-ts-core").Too
         json: "json";
         markdown: "markdown";
     }>>;
-    createTargetIfMissing: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    overwrite: import("zod").ZodDefault<import("zod").ZodBoolean>;
 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
     path: import("zod").ZodString;
     sectionTargeted: import("zod").ZodBoolean;
@@ -559,6 +584,11 @@ export declare const writeToolDefinitions: (import("@cyanheads/mcp-ts-core").Too
     previousSizeInBytes: import("zod").ZodNumber;
     currentSizeInBytes: import("zod").ZodNumber;
 }, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "file_exists";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Conflict;
+    readonly when: "Whole-file write was attempted against an existing note and `overwrite` was not set to `true`.";
+    readonly recovery: "Retry with overwrite true or use obsidian_patch_note for in-place edits.";
+}, {
     readonly reason: "path_forbidden";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Forbidden;
@@ -568,8 +598,8 @@ export declare const writeToolDefinitions: (import("@cyanheads/mcp-ts-core").Too
     readonly reason: "note_missing";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
-    readonly when: "Section append targets a path that does not resolve to an existing note (PATCH requires the file to exist).";
-    readonly recovery: "Verify the path with obsidian_list_notes, or omit `section` to fall back to whole-file append (which creates the note if missing).";
+    readonly when: "Section replace targets a path that does not resolve to an existing note (PATCH requires the file to exist).";
+    readonly recovery: "Verify the path with obsidian_list_notes, or omit `section` to fall back to whole-file write (which creates the note when it is absent).";
 }, {
     readonly reason: "no_active_file";
     readonly thrownBy: "service";
@@ -599,19 +629,25 @@ export declare const writeToolDefinitions: (import("@cyanheads/mcp-ts-core").Too
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
     readonly when: "`section` was provided but the named heading/block/frontmatter field does not exist in the note.";
-    readonly recovery: "Call obsidian_get_note with format document-map to discover available targets, or pass createTargetIfMissing: true to bring it into existence.";
+    readonly recovery: "Call obsidian_get_note with format document-map to discover available targets.";
 }, {
     readonly reason: "ambiguous_section";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Conflict;
-    readonly when: "A bare heading leaf name matches more than one heading in the note, so the append target is undetermined.";
-    readonly recovery: "Retry with one of the full Parent::Child heading paths listed in `candidates` on the error data.";
+    readonly when: "A bare heading leaf name matches more than one heading in the note, or the resolved full heading path occurs more than once, so the replacement target is undetermined.";
+    readonly recovery: "Retry with a distinct full Parent::Child heading path from `candidates` on the error data; when every candidate is the same path, rename the repeated headings first.";
 }, {
-    readonly reason: "content_preexists";
+    readonly reason: "heading_outside_section";
     readonly thrownBy: "service";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "Section append where the supplied content already appears at the target — rejected to keep retries idempotent (the default for the section path).";
-    readonly recovery: "Change the content to something not already present at the target, or use obsidian_patch_note with `patchOptions.applyIfContentPreexists: true` if a duplicate is intended.";
+    readonly when: "On Local REST API v5.0 and later, the new body of a heading section carries a heading at or above that section’s own level, which would have to sit outside the section.";
+    readonly recovery: "Append the heading at the parent section or at the end of the note with obsidian_append_to_note, or write it one level below the target section or deeper.";
+}, {
+    readonly reason: "patch_rejected";
+    readonly thrownBy: "service";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "The section exists but the plugin refused the new content for it — table rows for a block that is not a table, a row with the wrong cell count, or content of the wrong shape.";
+    readonly recovery: "Read the target with obsidian_get_note format section, then send content that fits it — rows matching the table columns, or a value of the field’s own type.";
 }, {
     readonly reason: "path_is_directory";
     readonly thrownBy: "service";

package/dist/mcp-server/tools/definitions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgBH,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK/B,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQhC,CAAC;AAEF,mHAAmH;AACnH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAiD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgBH,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK/B,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQhC,CAAC;AAEF,mHAAmH;AACnH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAiD,CAAC"}

package/dist/mcp-server/tools/definitions/obsidian-append-to-note.tool.d.ts

@@ -92,14 +92,26 @@ export declare const obsidianAppendToNote: import("@cyanheads/mcp-ts-core").Tool
     readonly reason: "ambiguous_section";
     readonly thrownBy: "service";
     readonly code: JsonRpcErrorCode.Conflict;
-    readonly when: "A bare heading leaf name matches more than one heading in the note, so the append target is undetermined.";
-    readonly recovery: "Retry with one of the full Parent::Child heading paths listed in `candidates` on the error data.";
+    readonly when: "A bare heading leaf name matches more than one heading in the note, or the resolved full heading path occurs more than once, so the append target is undetermined.";
+    readonly recovery: "Retry with a distinct full Parent::Child heading path from `candidates` on the error data; when every candidate is the same path, rename the repeated headings first.";
 }, {
     readonly reason: "content_preexists";
     readonly thrownBy: "service";
     readonly code: JsonRpcErrorCode.ValidationError;
     readonly when: "Section append where the supplied content already appears at the target — rejected to keep retries idempotent (the default for the section path).";
     readonly recovery: "Change the content to something not already present at the target, or use obsidian_patch_note with `patchOptions.applyIfContentPreexists: true` if a duplicate is intended.";
+}, {
+    readonly reason: "heading_outside_section";
+    readonly thrownBy: "service";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "On Local REST API v5.0 and later, content appended to a heading carries a heading at or above that section’s own level, which would have to sit outside the section.";
+    readonly recovery: "Append the heading at the parent section or at the end of the note (no `section`), or write it one level below the target section or deeper.";
+}, {
+    readonly reason: "patch_rejected";
+    readonly thrownBy: "service";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The section exists but the plugin refused the content for it — table rows for a block that is not a table, a row with the wrong cell count, a frontmatter value that cannot merge, or content of the wrong shape.";
+    readonly recovery: "Read the target with obsidian_get_note format section, then send content that fits it — rows matching the table columns, or a value of the field’s own type.";
 }, {
     readonly reason: "path_is_directory";
     readonly thrownBy: "service";

package/dist/mcp-server/tools/definitions/obsidian-append-to-note.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"obsidian-append-to-note.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/obsidian-append-to-note.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmM/B,CAAC"}
+{"version":3,"file":"obsidian-append-to-note.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/obsidian-append-to-note.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkN/B,CAAC"}