obsidian-mcp-server 3.0.0 → 3.1.1

package/CLAUDE.md

@@ -34,7 +34,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **Check `ctx.elicit`** for presence before calling — used by `obsidian_delete_note` to confirm destructive ops.
 - **All Obsidian access goes through `getObsidianService()`.** No direct `fetch()` calls to the Local REST API in tools/resources — the service centralizes auth, TLS, timeouts, and `ctx.signal` propagation.
 - **Secrets in env vars only.** `OBSIDIAN_API_KEY` is required; never hardcoded.
-- **`obsidian_execute_command` is opt-in.** Registered only when `OBSIDIAN_ENABLE_COMMANDS=true` — Obsidian commands are opaque and can be destructive.
+- **Command-palette tools are opt-in.** `obsidian_list_commands` and `obsidian_execute_command` are registered together only when `OBSIDIAN_ENABLE_COMMANDS=true` — Obsidian commands are opaque and can be destructive.
 
 ---
 
@@ -177,25 +177,33 @@ The framework also provides `ctx.state`, `ctx.sample`, and `ctx.progress`. They
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, retryable? }]` on `tool()` / `resource()` to advertise the failure surface in `tools/list` (under `_meta['mcp-ts-core/errors']`) and receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required descriptive metadata (≥ 5 words, lint-validated) — it's the single source of truth for the recovery hint that flows to the wire. Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire (the framework mirrors `data.recovery.hint` into `content[]` text). Override with explicit `{ recovery: { hint: '...' } }` when runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
 errors: [
-  { reason: 'note_missing', code: JsonRpcErrorCode.NotFound, when: 'No note matched the path' },
-  { reason: 'plugin_unreachable', code: JsonRpcErrorCode.ServiceUnavailable, when: 'Local REST API plugin is offline', retryable: true },
+  { reason: 'note_missing', code: JsonRpcErrorCode.NotFound,
+    when: 'No note matched the path',
+    recovery: 'Verify the path with obsidian_list_notes or use obsidian_search_notes to locate the note.' },
+  { reason: 'plugin_unreachable', code: JsonRpcErrorCode.ServiceUnavailable,
+    when: 'Local REST API plugin is offline', retryable: true,
+    recovery: 'Confirm Obsidian is running with the Local REST API plugin enabled.' },
 ],
 async handler(input, ctx) {
   const note = await svc.getNote(input.path, ctx);
-  if (!note) throw ctx.fail('note_missing', `Note ${input.path} not found`);
+  // Static recovery — pulled from the contract via ctx.recoveryFor.
+  if (!note) throw ctx.fail('note_missing', `Note ${input.path} not found`, {
+    ...ctx.recoveryFor('note_missing'),
+  });
   return note;
 }
 ```
 
-Services don't have `ctx.fail` — they pass `data: { reason: 'note_missing' }` to a factory so the wire shape matches what `ctx.fail` produces:
+Services that accept `ctx` use the same resolver for parity. The Obsidian service threads `ctx` into `#throwForStatus` and spreads `ctx.recoveryFor(reason)` per status branch, so service-side throws carry the calling tool's contract recovery onto the wire:
 
 ```ts
 // inside obsidian-service.ts
-throw notFound('Note not found', { reason: 'note_missing', path });
+throw notFound(`Not found: ${display}`, data('note_missing'));
+// where data(reason) does: { path, reason, ...ctx.recoveryFor(reason), upstream? }
 ```
 
 **Fallback for ad-hoc throws** (no contract entry fits, prototype tools, service-layer code without a contract): use error factories.
@@ -228,8 +236,8 @@ src/
   mcp-server/
     tools/definitions/
       _shared/schemas.ts                # Shared TargetSchema + SectionSchema reused across tools
-      index.ts                          # baseToolDefinitions[] + conditional obsidianExecuteCommand
-      obsidian-*.tool.ts                # 14 tool definitions (13 base + 1 opt-in)
+      index.ts                          # baseToolDefinitions[] + conditional commandToolDefinitions[]
+      obsidian-*.tool.ts                # 14 tool definitions (12 base + 2 opt-in command-palette pair)
     resources/definitions/
       index.ts                          # allResourceDefinitions[]
       obsidian-vault-note.resource.ts   # obsidian://vault/{+path}
@@ -306,8 +314,6 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run format` | Auto-fix formatting (Biome) |
 | `bun run lint:mcp` | Validate MCP definitions against the linter rules |
 | `bun run test` | Run Vitest tests |
-| `bun run dev:stdio` | Dev mode (stdio, watch) |
-| `bun run dev:http` | Dev mode (HTTP, watch) |
 | `bun run start:stdio` | Production mode (stdio) — requires `bun run build` first |
 | `bun run start:http` | Production mode (HTTP) — requires `bun run build` first |
 | `bun run changelog:build` | Regenerate `CHANGELOG.md` rollup from `changelog/<minor>.x/*.md` |
@@ -359,6 +365,6 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
 - [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
-- [ ] Registered in `createApp()` arrays (directly or via barrel exports). Conditional registration (e.g. `obsidianExecuteCommand` behind `OBSIDIAN_ENABLE_COMMANDS`) happens in `src/index.ts`, not in the barrel
+- [ ] Registered in `createApp()` arrays (directly or via barrel exports). Conditional registration (e.g. `commandToolDefinitions` behind `OBSIDIAN_ENABLE_COMMANDS`) happens in `src/index.ts`, not in the barrel
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
 - [ ] `bun run devcheck` passes

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![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) [![Version](https://img.shields.io/badge/Version-3.0.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.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) [![Version](https://img.shields.io/badge/Version-3.1.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.11-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
@@ -24,9 +24,9 @@ Fourteen tools grouped by shape — readers fetch notes and metadata, writers cr
 | `obsidian_get_note` | Read a note as raw content, full structured form (content + frontmatter + tags + stat), structural document map, or a single section. |
 | `obsidian_list_notes` | List notes and subdirectories at a vault path with a recursive walk (default depth 2 — structural overview; max 20) bounded by a 1000-entry cap. Optional `extension` and `nameRegex` filters apply across the tree; regex-filtered directories are skipped without recursing into them. Returns flat `entries[]` plus a box-drawing tree in the rendered output; per-directory `truncated: true` flags where the depth limit cut off recursion. |
 | `obsidian_list_tags` | List every tag found across the vault with usage counts, including hierarchical parents. |
-| `obsidian_list_commands` | List Obsidian command-palette commands available for execution. |
+| `obsidian_list_commands` | List Obsidian command-palette commands available for execution. **Opt-in via `OBSIDIAN_ENABLE_COMMANDS=true`** (paired with `obsidian_execute_command`). |
 | `obsidian_search_notes` | Search the vault by text, Dataview DQL, or JSONLogic — capped at 100 hits with overflow indicator. |
-| `obsidian_write_note` | Create or overwrite a note, or replace a single heading/block/frontmatter section in place. |
+| `obsidian_write_note` | Create a note, replace a single section in place, or — with `overwrite: true` — clobber an existing file. Refuses whole-file writes against an existing path by default. |
 | `obsidian_append_to_note` | Append content to a note, or to a specific heading/block/frontmatter section. |
 | `obsidian_patch_note` | Surgical `append` / `prepend` / `replace` against a heading, block reference, or frontmatter field. |
 | `obsidian_replace_in_note` | Body-wide search-replace inside a single note. Literal or regex matching, with `wholeWord`, `flexibleWhitespace`, `caseSensitive`, `replaceAll`, and `$1`/`$&` capture groups. |
@@ -63,12 +63,12 @@ Results are capped at 100 hits. When the upstream returns more, an `excluded` in
 
 ### `obsidian_write_note`
 
-Idempotent create/overwrite with optional in-place section replacement.
+Create or surgically replace, with a protective default against accidental whole-file overwrites.
 
-- Without `section` — full-file `PUT`, creates the file if missing
-- With `section` — `PATCH`-with-replace against the named heading/block/frontmatter field, leaving the rest of the file untouched
+- Without `section` — full-file `PUT`. **Refuses to clobber an existing file** unless `overwrite: true` is set. The `file_exists` (`Conflict`) error suggests `obsidian_patch_note` / `obsidian_append_to_note` / `obsidian_replace_in_note` for in-place edits.
+- With `section` — `PATCH`-with-replace against the named heading/block/frontmatter field, leaving the rest of the file untouched. The `overwrite` flag is ignored in section mode.
 
-Repeated calls with the same input converge on the same result.
+The output reports `created: true` when the call brought a new file into existence; `false` when it replaced an existing one or targeted a section.
 
 ---
 
@@ -122,7 +122,7 @@ Permanently delete a note. When the client supports `elicit`, the server request
 
 Dispatch an Obsidian command-palette command by ID (discoverable via `obsidian_list_commands`). Behavior is command-dependent — some commands open UI, others delete files or close the vault.
 
-**Off by default.** Register only when the operator sets `OBSIDIAN_ENABLE_COMMANDS=true`; the tool is omitted from the surface otherwise.
+**Off by default.** Both `obsidian_execute_command` and its discovery partner `obsidian_list_commands` register only when the operator sets `OBSIDIAN_ENABLE_COMMANDS=true`; both are omitted from the surface otherwise.
 
 ---
 
@@ -155,7 +155,7 @@ Obsidian-specific:
 - Tag reconciliation across both representations: frontmatter `tags:` array and inline `#tag` syntax (skipping fenced code blocks)
 - Search across three modes: text, Dataview DQL, JSONLogic — with overflow indicator when results exceed the 100-hit cap
 - Optional human-in-the-loop confirmation for destructive deletes via `ctx.elicit`
-- Opt-in `obsidian_execute_command` for the command palette — registered only when explicitly enabled
+- Opt-in command-palette pair (`obsidian_list_commands` + `obsidian_execute_command`) — registered only when `OBSIDIAN_ENABLE_COMMANDS=true`
 - Forgiving path resolution on `obsidian_get_note` and `obsidian_open_in_ui` — silently retries case-mismatched paths against the canonical filename, throws `Conflict` on ambiguous case matches, and enriches `NotFound` with `Did you mean: …?` suggestions when only near-matches exist. `obsidian_delete_note` is deliberately excluded — a destructive op shouldn't silently rewrite the target path.
 
 ## Getting started
@@ -246,7 +246,7 @@ MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
 | `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). | `http://127.0.0.1:27123` |
 | `OBSIDIAN_VERIFY_SSL` | Verify the TLS certificate. Default `false` because the plugin uses a self-signed cert. On Node, the dispatcher's `rejectUnauthorized` option handles this without any process-wide change. On Bun, the runtime ignores that option, so the service additionally sets `NODE_TLS_REJECT_UNAUTHORIZED=0` — that fallback is scoped to Bun only. | `false` |
 | `OBSIDIAN_REQUEST_TIMEOUT_MS` | Per-request timeout in milliseconds. | `30000` |
-| `OBSIDIAN_ENABLE_COMMANDS` | Opt-in flag for `obsidian_execute_command`. Off by default — Obsidian commands are opaque and can be destructive. | `false` |
+| `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` |
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
 | `MCP_HTTP_HOST` | Host for the HTTP server. | `127.0.0.1` |
 | `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |

package/changelog/3.1.x/3.1.0.md

@@ -0,0 +1,26 @@
+---
+summary: obsidian_write_note refuses to clobber existing notes by default — opt in with overwrite:true; obsidian_list_commands moves behind OBSIDIAN_ENABLE_COMMANDS alongside obsidian_execute_command.
+breaking: false
+---
+
+# 3.1.0 — 2026-04-29
+
+A safety pass on whole-file writes plus a tighter command-palette gate. Service-layer error classification picks up the framework's `httpErrorFromResponse` for the 4xx/5xx fallback so the canonical status → code mapping (and `Retry-After` capture) replaces the hand-rolled ladder.
+
+## Added
+
+- **`obsidian_write_note` `overwrite` flag (default `false`).** Whole-file writes against an existing note now fail with `file_exists` (`Conflict`) and an actionable message pointing at `obsidian_patch_note` / `obsidian_append_to_note` / `obsidian_replace_in_note` for in-place edits, or `overwrite: true` for a deliberate full replacement. Section-targeted writes are unaffected — the flag is ignored when `section` is set.
+- **`obsidian_write_note` `created` field in the output.** `true` when the call brought a new file into existence; `false` when it replaced an existing one or targeted a section. Surfaces in both `structuredContent` and the rendered `content[]` twin.
+- **Typed error contract on `obsidian_write_note`.** Declares `file_exists` so clients can switch on `error.data.reason` instead of parsing message text.
+- **`ObsidianService.noteExists()`** — HEAD probe that returns `true` on 2xx, `false` on 404, and surfaces other statuses through the normal error classifier so a 401 doesn't masquerade as a missing file. Bypasses `withRetry` — a HEAD probe shouldn't retry on 404.
+
+## Changed
+
+- **`obsidian_list_commands` is now opt-in alongside `obsidian_execute_command`.** Both register only when `OBSIDIAN_ENABLE_COMMANDS=true`; both are hidden otherwise. Previously `obsidian_list_commands` was always-on and only execution was gated, which advertised a discovery surface for capabilities the operator had explicitly disabled. The pair now travels together as `commandToolDefinitions`.
+- **Service-layer 4xx/5xx fallback routes through `httpErrorFromResponse`.** The default branch in `ObsidianService.#throwForStatus` delegates to the framework helper for unhandled statuses so the canonical mapping (`500/501 → InternalError`, `502/503 → ServiceUnavailable`, `504 → Timeout`) and `Retry-After` capture replace the local `serviceUnavailable` ladder. The body is consumed before the helper runs, so the call passes `captureBody: false` and forwards a truncated copy via `data.body`. Wire-visible: 500s now land as `InternalError` (`-32603`) instead of `ServiceUnavailable` (`-32004`).
+- **Dependency bump:** `@cyanheads/mcp-ts-core` 0.8.1 → 0.8.2.
+- **`skills/maintenance/SKILL.md` v1.9 → v2.0.** Step 6's framework-adoption rule moved from "default adopt" to "auto-adopt every applicable site, in this pass." Documents an explicit asymmetry against third-party adoptions, a hard rule against scope/effort/marginal-benefit deferrals, and a valid-vs-invalid deferral table. Step 8's "Open decisions" section is reframed accordingly — empty is now the expected outcome of a clean framework upgrade.
+
+## Fixed
+
+- **`obsidian_list_commands` description** no longer claims it is always available — calls out the `OBSIDIAN_ENABLE_COMMANDS` gate.

package/changelog/3.1.x/3.1.1.md

@@ -0,0 +1,21 @@
+---
+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`.

package/dist/config/server-config.js

@@ -35,7 +35,7 @@ const ServerConfigSchema = z.object({
         .describe('Per-request timeout in milliseconds.'),
     enableCommands: envBoolean
         .default(false)
-        .describe('Opt-in flag for obsidian_execute_command. Off by default — Obsidian commands are opaque and can be destructive.'),
+        .describe('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.'),
 });
 let _config;
 export function getServerConfig() {

package/dist/config/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,EAAE,EAAE;IACtC,IAAI,OAAO,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IACzC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QACrC,OAAO,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC;IACvC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAEhB,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,sGAAsG,CACvG;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,wBAAwB,CAAC;SACjC,QAAQ,CACP,0QAA0Q,CAC3Q;IACH,SAAS,EAAE,UAAU;SAClB,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,qXAAqX,CACtX;IACH,gBAAgB,EAAE,CAAC,CAAC,MAAM;SACvB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CAAC,sCAAsC,CAAC;IACnD,cAAc,EAAE,UAAU;SACvB,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,iHAAiH,CAClH;CACJ,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,MAAM,EAAE,kBAAkB;QAC1B,OAAO,EAAE,mBAAmB;QAC5B,SAAS,EAAE,qBAAqB;QAChC,gBAAgB,EAAE,6BAA6B;QAC/C,cAAc,EAAE,0BAA0B;KAC3C,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,iBAAiB;IAC/B,OAAO,GAAG,SAAS,CAAC;AACtB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,EAAE,EAAE;IACtC,IAAI,OAAO,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IACzC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QACrC,OAAO,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC;IACvC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAEhB,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,sGAAsG,CACvG;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,wBAAwB,CAAC;SACjC,QAAQ,CACP,0QAA0Q,CAC3Q;IACH,SAAS,EAAE,UAAU;SAClB,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,qXAAqX,CACtX;IACH,gBAAgB,EAAE,CAAC,CAAC,MAAM;SACvB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CAAC,sCAAsC,CAAC;IACnD,cAAc,EAAE,UAAU;SACvB,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,yKAAyK,CAC1K;CACJ,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,MAAM,EAAE,kBAAkB;QAC1B,OAAO,EAAE,mBAAmB;QAC5B,SAAS,EAAE,qBAAqB;QAChC,gBAAgB,EAAE,6BAA6B;QAC/C,cAAc,EAAE,0BAA0B;KAC3C,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,iBAAiB;IAC/B,OAAO,GAAG,SAAS,CAAC;AACtB,CAAC"}

package/dist/index.js

@@ -9,11 +9,11 @@ import { createApp } from '@cyanheads/mcp-ts-core';
 import { getServerConfig } from './config/server-config.js';
 import { allPromptDefinitions } from './mcp-server/prompts/definitions/index.js';
 import { allResourceDefinitions } from './mcp-server/resources/definitions/index.js';
-import { baseToolDefinitions, obsidianExecuteCommand, } from './mcp-server/tools/definitions/index.js';
+import { baseToolDefinitions, commandToolDefinitions, } from './mcp-server/tools/definitions/index.js';
 import { initObsidianService } from './services/obsidian/obsidian-service.js';
 const config = getServerConfig();
 const tools = config.enableCommands
-    ? [...baseToolDefinitions, obsidianExecuteCommand]
+    ? [...baseToolDefinitions, ...commandToolDefinitions]
     : baseToolDefinitions;
 await createApp({
     tools,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EACL,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAE9E,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;AACjC,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc;IACjC,CAAC,CAAC,CAAC,GAAG,mBAAmB,EAAE,sBAAsB,CAAC;IAClD,CAAC,CAAC,mBAAmB,CAAC;AAExB,MAAM,SAAS,CAAC;IACd,KAAK;IACL,SAAS,EAAE,sBAAsB;IACjC,OAAO,EAAE,oBAAoB;IAC7B,KAAK;QACH,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EACL,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAE9E,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;AACjC,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc;IACjC,CAAC,CAAC,CAAC,GAAG,mBAAmB,EAAE,GAAG,sBAAsB,CAAC;IACrD,CAAC,CAAC,mBAAmB,CAAC;AAExB,MAAM,SAAS,CAAC;IACd,KAAK;IACL,SAAS,EAAE,sBAAsB;IACjC,OAAO,EAAE,oBAAoB;IAC7B,KAAK;QACH,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC,CAAC"}

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

@@ -1,10 +1,11 @@
 /**
- * @fileoverview Tool registration barrel. `obsidian_execute_command` is exported
- * separately so callers can decide whether to register it based on the
- * `OBSIDIAN_ENABLE_COMMANDS` flag — keeping this module free of eager config reads.
+ * @fileoverview Tool registration barrel. The command-palette pair
+ * (`obsidian_list_commands` + `obsidian_execute_command`) is exported
+ * separately so callers can decide whether to register them based on the
+ * `OBSIDIAN_ENABLE_COMMANDS` flag — keeping this module free of eager
+ * config reads.
  * @module mcp-server/tools/definitions/index
  */
-import { obsidianExecuteCommand } from './obsidian-execute-command.tool.js';
 /** Tools registered unconditionally on every server. */
 export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     target: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
@@ -23,6 +24,40 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
         }>;
         date: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>], "type">;
+    content: import("zod").ZodString;
+    section: import("zod").ZodOptional<import("zod").ZodObject<{
+        type: import("zod").ZodEnum<{
+            heading: "heading";
+            block: "block";
+            frontmatter: "frontmatter";
+        }>;
+        target: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    contentType: import("zod").ZodDefault<import("zod").ZodEnum<{
+        markdown: "markdown";
+        json: "json";
+    }>>;
+    createTargetIfMissing: import("zod").ZodDefault<import("zod").ZodBoolean>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    path: import("zod").ZodString;
+    sectionTargeted: import("zod").ZodBoolean;
+}, import("zod/v4/core").$strip>, undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    target: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+        type: import("zod").ZodLiteral<"path">;
+        path: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        type: import("zod").ZodLiteral<"active">;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        type: import("zod").ZodLiteral<"periodic">;
+        period: import("zod").ZodEnum<{
+            daily: "daily";
+            weekly: "weekly";
+            monthly: "monthly";
+            quarterly: "quarterly";
+            yearly: "yearly";
+        }>;
+        date: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>], "type">;
 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
     path: import("zod").ZodString;
     deleted: import("zod").ZodBoolean;
@@ -30,18 +65,27 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
     readonly reason: "cancelled";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidRequest;
     readonly when: "User declined the deletion via interactive elicitation.";
+    readonly recovery: "Re-run the tool when the user is ready to confirm deletion.";
 }, {
     readonly reason: "note_missing";
     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 reason: "no_active_file";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `active` but no file is currently open in Obsidian.";
+    readonly recovery: "Open a note in Obsidian or pass an explicit path target instead.";
 }, {
     readonly reason: "periodic_not_found";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `periodic` but no matching periodic note exists.";
+    readonly recovery: "Pass an explicit path target — periodic notes must already exist.";
+}, {
+    readonly reason: "periodic_disabled";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Target was `periodic` but the requested period is not enabled in Obsidian's Periodic Notes plugin settings.";
+    readonly recovery: "Enable the period in Obsidian's Periodic Notes plugin settings, or pass an explicit path target instead.";
 }]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     format: import("zod").ZodEnum<{
         content: "content";
@@ -113,24 +157,28 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
     readonly reason: "section_required";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
     readonly when: "`format` is \"section\" but no `section` locator was provided.";
+    readonly recovery: "Pass `section: { type, target }` (e.g. `{ type: \"heading\", target: \"Intro\" }`), or use `format: \"full\"` / `\"document-map\"` instead.";
 }, {
     readonly reason: "note_missing";
     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 reason: "no_active_file";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `active` but no file is currently open in Obsidian.";
+    readonly recovery: "Open a note in Obsidian or pass an explicit path target instead.";
 }, {
     readonly reason: "periodic_not_found";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `periodic` but no matching periodic note exists.";
-}]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
-    commands: import("zod").ZodArray<import("zod").ZodObject<{
-        id: import("zod").ZodString;
-        name: import("zod").ZodString;
-    }, import("zod/v4/core").$strip>>;
-}, import("zod/v4/core").$strip>, undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    readonly recovery: "Create the periodic note first or pass an explicit path target.";
+}, {
+    readonly reason: "periodic_disabled";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Target was `periodic` but the requested period is not enabled in Obsidian's Periodic Notes plugin settings.";
+    readonly recovery: "Enable the period in Obsidian's Periodic Notes plugin settings, or pass an explicit path target instead.";
+}]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     path: import("zod").ZodOptional<import("zod").ZodString>;
     extension: import("zod").ZodOptional<import("zod").ZodString>;
     nameRegex: import("zod").ZodOptional<import("zod").ZodString>;
@@ -164,10 +212,12 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
     readonly reason: "regex_invalid";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
     readonly when: "The supplied `nameRegex` is not a valid ECMAScript regex.";
+    readonly recovery: "Test the pattern (e.g. `^Project.*\\.md$`) in a JS regex tester, or omit nameRegex to disable filtering.";
 }, {
     readonly reason: "note_missing";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "The supplied `path` does not exist in the vault. Sub-directories that disappear mid-walk are silently skipped — only the root path surfaces this error.";
+    readonly recovery: "List a parent directory to find the correct casing or check the spelling.";
 }]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
     tags: import("zod").ZodArray<import("zod").ZodObject<{
         name: import("zod").ZodString;
@@ -219,18 +269,27 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
     readonly reason: "value_required";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
     readonly when: "`operation` is \"set\" but no `value` was supplied.";
+    readonly recovery: "Pass `value` as any JSON-typed value: string, number, boolean, array, or object (e.g. `\"draft\"`, `42`, `true`, `[\"a\",\"b\"]`).";
 }, {
     readonly reason: "note_missing";
     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 reason: "no_active_file";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `active` but no file is currently open in Obsidian.";
+    readonly recovery: "Open a note in Obsidian or pass an explicit path target instead.";
 }, {
     readonly reason: "periodic_not_found";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `periodic` but no matching periodic note exists.";
+    readonly recovery: "Create the periodic note first or pass an explicit path target.";
+}, {
+    readonly reason: "periodic_disabled";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Target was `periodic` but the requested period is not enabled in Obsidian's Periodic Notes plugin settings.";
+    readonly recovery: "Enable the period in Obsidian's Periodic Notes plugin settings, or pass an explicit path target instead.";
 }]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     target: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
         type: import("zod").ZodLiteral<"path">;
@@ -285,18 +344,27 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
     readonly reason: "tags_required";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
     readonly when: "`operation` is \"add\" or \"remove\" but `tags` was empty or omitted.";
+    readonly recovery: "Pass a non-empty `tags` array (without `#`), e.g. `[\"draft\", \"wip\"]`.";
 }, {
     readonly reason: "note_missing";
     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 reason: "no_active_file";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `active` but no file is currently open in Obsidian.";
+    readonly recovery: "Open a note in Obsidian or pass an explicit path target instead.";
 }, {
     readonly reason: "periodic_not_found";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `periodic` but no matching periodic note exists.";
+    readonly recovery: "Create the periodic note first or pass an explicit path target.";
+}, {
+    readonly reason: "periodic_disabled";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Target was `periodic` but the requested period is not enabled in Obsidian's Periodic Notes plugin settings.";
+    readonly recovery: "Enable the period in Obsidian's Periodic Notes plugin settings, or pass an explicit path target instead.";
 }]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     path: import("zod").ZodString;
     failIfMissing: import("zod").ZodDefault<import("zod").ZodBoolean>;
@@ -309,6 +377,7 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
     readonly reason: "note_missing";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "`failIfMissing: true` (default) and the path does not exist in the vault. Pass `failIfMissing: false` to allow Obsidian to create the file on open.";
+    readonly recovery: "Verify the path with obsidian_list_notes or pass failIfMissing false to create on open.";
 }]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     target: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
         type: import("zod").ZodLiteral<"path">;
@@ -368,18 +437,27 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
     readonly reason: "note_missing";
     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 reason: "no_active_file";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `active` but no file is currently open in Obsidian.";
+    readonly recovery: "Open a note in Obsidian or pass an explicit path target instead.";
 }, {
     readonly reason: "periodic_not_found";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `periodic` but no matching periodic note exists.";
+    readonly recovery: "Create the periodic note first or pass an explicit path target.";
+}, {
+    readonly reason: "periodic_disabled";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Target was `periodic` but the requested period is not enabled in Obsidian's Periodic Notes plugin settings.";
+    readonly recovery: "Enable the period in Obsidian's Periodic Notes plugin settings, or pass an explicit path target instead.";
 }, {
     readonly reason: "section_target_missing";
     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.";
 }]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     target: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
         type: import("zod").ZodLiteral<"path">;
@@ -417,18 +495,27 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
     readonly reason: "regex_invalid";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
     readonly when: "A `useRegex: true` replacement supplied a `search` pattern that is not a valid ECMAScript regex.";
+    readonly recovery: "Test the pattern in a JS regex tester, or set useRegex to false to match `search` as a literal string.";
 }, {
     readonly reason: "note_missing";
     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 reason: "no_active_file";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `active` but no file is currently open in Obsidian.";
+    readonly recovery: "Open a note in Obsidian or pass an explicit path target instead.";
 }, {
     readonly reason: "periodic_not_found";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
     readonly when: "Target was `periodic` but no matching periodic note exists.";
+    readonly recovery: "Create the periodic note first or pass an explicit path target.";
+}, {
+    readonly reason: "periodic_disabled";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Target was `periodic` but the requested period is not enabled in Obsidian's Periodic Notes plugin settings.";
+    readonly recovery: "Enable the period in Obsidian's Periodic Notes plugin settings, or pass an explicit path target instead.";
 }]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     mode: import("zod").ZodEnum<{
         text: "text";
@@ -485,14 +572,17 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
     readonly reason: "path_prefix_invalid_mode";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
     readonly when: "`pathPrefix` was provided in a non-text mode (only `text` supports prefix filtering).";
+    readonly recovery: "Drop pathPrefix or switch mode to text for prefix filtering.";
 }, {
     readonly reason: "query_required";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
     readonly when: "`query` is missing for `text` or `dataview` mode (required for both).";
+    readonly recovery: "Pass `query` — search terms for text mode (e.g. \"TODO\"), or DQL like \"TABLE WHERE file.mtime > date(today)\" for dataview mode.";
 }, {
     readonly reason: "logic_required";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
     readonly when: "`logic` is missing for `jsonlogic` mode.";
+    readonly recovery: "Pass a JSONLogic tree as `logic`, e.g. `{\"glob\": [{\"var\": \"path\"}, \"Projects/*.md\"]}`.";
 }]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     target: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
         type: import("zod").ZodLiteral<"path">;
@@ -523,9 +613,32 @@ export declare const baseToolDefinitions: (import("@cyanheads/mcp-ts-core").Tool
         markdown: "markdown";
         json: "json";
     }>>;
+    overwrite: import("zod").ZodDefault<import("zod").ZodBoolean>;
 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
     path: import("zod").ZodString;
     sectionTargeted: import("zod").ZodBoolean;
+    created: import("zod").ZodBoolean;
+}, 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.";
+}]>)[];
+/** Command-palette tools — registered only when `OBSIDIAN_ENABLE_COMMANDS=true`. */
+export declare const commandToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    commandId: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    commandId: import("zod").ZodString;
+    executed: import("zod").ZodBoolean;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "command_unknown";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "The supplied `commandId` is not registered in Obsidian. Use `obsidian_list_commands` to discover valid IDs.";
+    readonly recovery: "Call obsidian_list_commands to discover the registered command IDs.";
+}]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    commands: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        name: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
 }, import("zod/v4/core").$strip>, undefined>)[];
-export { obsidianExecuteCommand };
 //# sourceMappingURL=index.d.ts.map

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;;;;;GAKG;AAIH,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAa5E,wDAAwD;AACxD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+CAc/B,CAAC;AAEF,OAAO,EAAE,sBAAsB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH,wDAAwD;AACxD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAa/B,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;+CAAiD,CAAC"}

package/dist/mcp-server/tools/definitions/index.js

@@ -1,7 +1,9 @@
 /**
- * @fileoverview Tool registration barrel. `obsidian_execute_command` is exported
- * separately so callers can decide whether to register it based on the
- * `OBSIDIAN_ENABLE_COMMANDS` flag — keeping this module free of eager config reads.
+ * @fileoverview Tool registration barrel. The command-palette pair
+ * (`obsidian_list_commands` + `obsidian_execute_command`) is exported
+ * separately so callers can decide whether to register them based on the
+ * `OBSIDIAN_ENABLE_COMMANDS` flag — keeping this module free of eager
+ * config reads.
  * @module mcp-server/tools/definitions/index
  */
 import { obsidianAppendToNote } from './obsidian-append-to-note.tool.js';
@@ -23,7 +25,6 @@ export const baseToolDefinitions = [
     obsidianGetNote,
     obsidianListNotes,
     obsidianListTags,
-    obsidianListCommands,
     obsidianSearchNotes,
     obsidianWriteNote,
     obsidianAppendToNote,
@@ -34,5 +35,6 @@ export const baseToolDefinitions = [
     obsidianDeleteNote,
     obsidianOpenInUi,
 ];
-export { obsidianExecuteCommand };
+/** Command-palette tools — registered only when `OBSIDIAN_ENABLE_COMMANDS=true`. */
+export const commandToolDefinitions = [obsidianListCommands, obsidianExecuteCommand];
 //# sourceMappingURL=index.js.map

package/dist/mcp-server/tools/definitions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE,wDAAwD;AACxD,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,eAAe;IACf,iBAAiB;IACjB,gBAAgB;IAChB,oBAAoB;IACpB,mBAAmB;IACnB,iBAAiB;IACjB,oBAAoB;IACpB,iBAAiB;IACjB,qBAAqB;IACrB,yBAAyB;IACzB,kBAAkB;IAClB,kBAAkB;IAClB,gBAAgB;CACjB,CAAC;AAEF,OAAO,EAAE,sBAAsB,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE,wDAAwD;AACxD,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,eAAe;IACf,iBAAiB;IACjB,gBAAgB;IAChB,mBAAmB;IACnB,iBAAiB;IACjB,oBAAoB;IACpB,iBAAiB;IACjB,qBAAqB;IACrB,yBAAyB;IACzB,kBAAkB;IAClB,kBAAkB;IAClB,gBAAgB;CACjB,CAAC;AAEF,oFAAoF;AACpF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,oBAAoB,EAAE,sBAAsB,CAAC,CAAC"}