obsidian-mcp-server/changelog/3.1.x/3.1.1.md

MCP server for Obsidian vaults — read, write, search, and surgically edit notes, tags, and frontmatter via the Local REST API plugin. STDIO or Streamable HTTP.

---
summary: Adopt the mcp-ts-core 0.8.6 recovery-hint contract — every error declares a recovery, ObsidianService threads it onto the wire, and a new periodic_disabled reason distinguishes a disabled period from a missing periodic note.
breaking: false
---

# 3.1.1 — 2026-04-29

A propagation pass for the typed-error contract upgrade in `@cyanheads/mcp-ts-core` 0.8.6. Every tool's `errors[]` now declares a `recovery` hint, the Obsidian service threads `ctx` through its status classifier so service-side throws inherit the calling tool's recovery, and `obsidian_open_in_ui` / `obsidian_write_note` lift long remediation guidance out of the error message into structured `data.recovery.hint`.

## Added

- **`periodic_disabled` error reason** on every tool that resolves a `periodic` target (`obsidian_get_note`, `obsidian_patch_note`, `obsidian_replace_in_note`, `obsidian_manage_frontmatter`, `obsidian_manage_tags`, `obsidian_delete_note`). Fired when the upstream Local REST API returns a 400 with `"Specified period is not enabled"` — the requested period (`daily` / `weekly` / `monthly` / `quarterly` / `yearly`) is turned off in Obsidian's Periodic Notes plugin settings. Distinct from `periodic_not_found` (404, the period is enabled but no note exists for the requested date), so clients can suggest enabling the period rather than creating a note.

## Changed

- **Every error contract entry now carries a `recovery` hint.** Required descriptive metadata under `mcp-ts-core` 0.8.6 — lint enforces it. Recovery flows to the wire via `ctx.recoveryFor(reason)` (spread into the `ctx.fail(...)` data bag) and the framework mirrors `data.recovery.hint` into the rendered `content[]` text, so clients that render structured error data and clients that parse text both see the same actionable next step.
- **`obsidian_open_in_ui` and `obsidian_write_note` lift long remediation text into `data.recovery.hint`.** The `note_missing` and `file_exists` error messages drop the `Did you mean:` suggestions, the `failIfMissing: false` tip, and the `obsidian_patch_note` / `obsidian_append_to_note` / `obsidian_replace_in_note` referrals — those move into a structured `recovery.hint` field. Wire-visible: clients that read `error.data.recovery.hint` see a cleaner separation of "what happened" from "how to fix it."
- **`ObsidianService.#throwForStatus` threads `ctx`.** The status classifier now spreads `ctx.recoveryFor(reason)` per branch, so service-side throws (`note_missing`, `no_active_file`, `periodic_not_found`, `periodic_disabled`, `command_unknown`, `path_is_directory`, `section_target_missing`) inherit the calling tool's contract recovery instead of needing per-tool plumbing.
- **Drop `dev:stdio` / `dev:http` scripts.** `bun --watch src/index.ts` works directly without the wrapper. The CLAUDE.md commands table loses the two duplicates.
- **Dependency bump:** `@cyanheads/mcp-ts-core` 0.8.2 → 0.8.6.
- **Skills synced** with framework patterns: `add-tool`, `add-service`, `api-context`, `api-errors`, `design-mcp-server`, `field-test`.