obsidian-mcp-server 3.7.2 → 3.9.0

package/dist/mcp-server/tools/definitions/obsidian-search-notes.tool.d.ts

@@ -1,23 +1,39 @@
 /**
  * @fileoverview obsidian_search_notes — text/jsonlogic/omnisearch search with
- * MCP-spec cursor pagination. The `omnisearch` mode is added conditionally by
- * the entry point only when the Omnisearch plugin's HTTP server is reachable
- * at startup. Text-mode hits carry match locations (the service merges a
- * multi-token query's per-token spans) and additionally clip per file via
- * `maxMatchesPerHit` so a single match-heavy note can't blow the response
- * budget — clipped hits carry `truncated: true` and `totalMatches`.
+ * MCP-spec cursor pagination. The `omnisearch` mode is offered only with reads
+ * unscoped and the Omnisearch plugin's HTTP server answering at startup
+ * (`omnisearchAvailability`). Text-mode hits carry match locations (the
+ * service merges a multi-token query's per-token spans) and additionally clip
+ * per file via `maxMatchesPerHit` so a single match-heavy note can't blow the
+ * response budget — clipped hits carry `truncated: true` and `totalMatches`.
  * @module mcp-server/tools/definitions/obsidian-search-notes.tool
  */
 import { z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { type ObsidianService } from '../../../services/obsidian/obsidian-service.js';
+/**
+ * Whether `obsidian_search_notes` offers `omnisearch` mode: `offered` when
+ * reads are unscoped and the plugin answered the startup probe,
+ * `unreachable` when it did not answer, and `withheld` under
+ * OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS, where the plugin is never
+ * called. Omnisearch ranks and selects its results over the whole vault, so
+ * every one of them depends on notes outside a read scope.
+ */
+export type OmnisearchAvailability = 'offered' | 'unreachable' | 'withheld';
+/**
+ * Decide {@link OmnisearchAvailability} once, at startup. Under a read scope
+ * it is `withheld` with no request, the probe included; otherwise the probe
+ * decides.
+ */
+export declare function omnisearchAvailability(svc: ObsidianService): Promise<OmnisearchAvailability>;
 /**
  * Build the `obsidian_search_notes` tool. The `omnisearch` mode is included
- * in the input/output schemas only when `omnisearchReachable` is true so the
- * LLM never sees it as an option on a deployment where it can't run. Re-probe
- * requires a server restart.
+ * in the input/output schemas and the description only when `omnisearch` is
+ * `offered`, so the LLM never sees it as an option on a deployment where it
+ * can't run or is withheld. Re-probe requires a server restart.
  */
-export declare function buildSearchNotesTool({ omnisearchReachable }: {
-    omnisearchReachable: boolean;
+export declare function buildSearchNotesTool({ omnisearch }: {
+    omnisearch: OmnisearchAvailability;
 }): import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
     mode: z.ZodEnum<{
         jsonlogic: "jsonlogic";
@@ -99,6 +115,10 @@ export declare function buildSearchNotesTool({ omnisearchReachable }: {
         totalCount: z.ZodNumber;
         nextCursor: z.ZodOptional<z.ZodString>;
         truncated: z.ZodBoolean;
+        truncatedReason: z.ZodOptional<z.ZodEnum<{
+            cap_reached: "cap_reached";
+            filtered_after_cap: "filtered_after_cap";
+        }>>;
     }, z.core.$strip>], "mode">;
 }, z.core.$strip>, readonly [{
     readonly reason: 'path_prefix_invalid_mode';
@@ -108,14 +128,14 @@ export declare function buildSearchNotesTool({ omnisearchReachable }: {
 }, {
     readonly reason: 'query_required';
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: '`query` is missing for `text` or `omnisearch` mode (required for both).';
-    readonly recovery: 'Pass `query` — whitespace-separated tokens, all required, for text mode, or BM25 query syntax (quoted phrases, `-exclusion`, `path:` / `ext:` filters) for omnisearch.';
+    readonly when: '`query` is missing in a mode that requires it: every mode but `jsonlogic`.';
+    readonly recovery: "Pass `query` as space-separated tokens, all of which a note must contain." | "Pass `query` — space-separated tokens, all required, for text mode, or BM25 query syntax (quoted phrases, `-exclusion`, `path:` / `ext:` filters) for omnisearch.";
 }, {
     readonly reason: 'context_length_too_large';
     readonly thrownBy: 'service';
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: 'The Local REST API exhausted its string capacity building one context window per match, so the whole text search failed.';
-    readonly recovery: 'Lower `contextLength`, or narrow the query so fewer notes match. The ceiling is the product of the two, so a broad query fails at a much smaller window than a narrow one does.';
+    readonly when: "The matches would make a response longer than one can be, so the whole text search failed: the Local REST API runs out of string capacity serializing them, or, under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS, the readable notes' matches alone would pass the same ceiling. Each match costs its context window plus about 150 characters of offsets and framing.";
+    readonly recovery: 'Narrow the query so fewer notes match, and drop very common tokens: every occurrence of each token in a matching note is a match costing about 150 characters beside its window, so a token like `the` can fail even at `contextLength` 0. Lowering `contextLength` helps only while the windows, about twice `contextLength` each, dominate that cost.';
 }, {
     readonly reason: 'logic_required';
     readonly code: JsonRpcErrorCode.ValidationError;
@@ -131,32 +151,95 @@ export declare function buildSearchNotesTool({ omnisearchReachable }: {
     readonly reason: 'logic_too_costly';
     readonly thrownBy: 'service';
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: "With OBSIDIAN_READ_PATHS set, the server evaluates the JSONLogic tree itself, and the tree passed a bound: nesting deeper than 1,000 levels, more than a work budget, or more than 10 s of evaluation. One work budget is per note — the size of values built by `merge`, `cat`, `map`, and array literals while evaluating that note, up to the note's own size plus 10,000,000 units — and one is per search: 10,000,000 units across every note for returned results, where a result whose JSON is at most 1,024 characters is free and a larger one pays for what it holds beyond its own note.";
+    readonly when: "With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the server evaluates the JSONLogic tree itself, and the tree passed a bound: nesting deeper than 1,000 levels, more than a work budget, more than 10 s of evaluation, or more than 45 s for the whole search, reading the readable notes included. One work budget is per note — the size of values built by `merge`, `cat`, `map`, and array literals while evaluating that note, up to the note's own size plus 10,000,000 units — and one is per search: 10,000,000 units across every note for returned results, where a result whose JSON is at most 1,024 characters is free and a larger one pays for what it holds beyond its own note.";
     readonly recovery: "Simplify the tree: nest fewer levels, avoid building arrays or strings many times a note's size with `merge`, `cat`, `map`, or `reduce`, return values drawn from the note rather than large built values or constants, and prefer a simpler `regexp` pattern.";
+}, {
+    readonly reason: 'text_search_too_costly';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the server runs text mode itself, reading every readable note whose path or body holds each token, and reading and matching them took more than 45 s.';
+    readonly recovery: 'Add rarer tokens, which every candidate note must contain, so fewer readable notes are read, or ask the operator to narrow OBSIDIAN_READ_PATHS or extend OBSIDIAN_DENY_PATHS.';
+}, {
+    readonly reason: 'link_fields_unavailable';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the JSONLogic tree names `links`, `backlinks`, or `unresolvedLinks` by a fixed `var`, `missing`, or `missing_some` key. Scoped searches leave these fields out, since Obsidian resolves each link across the whole vault, notes outside the scope included; a computed key reads them as null.';
+    readonly recovery: 'Find backlinks by body text: `{"regexp": ["\\\\[\\\\[Target Note(\\\\\\\\?\\\\||#|\\\\]\\\\])", {"var": "content"}]}` matches every readable note that wikilinks or embeds `Target Note`. For a note\'s outgoing links, call `obsidian_get_note` with `includeLinks: true`.';
 }, {
     readonly reason: 'note_too_deep';
     readonly thrownBy: 'service';
     readonly code: JsonRpcErrorCode.SerializationError;
-    readonly when: 'With OBSIDIAN_READ_PATHS set, a readable note holds data, usually a frontmatter value, nested deeper than the server can hand to its evaluator (about 3,500 levels under Node, more under Bun).';
-    readonly recovery: 'Flatten the deeply nested value, usually a frontmatter field, in the note the message names, or ask the operator to leave that note out of OBSIDIAN_READ_PATHS; no scoped jsonlogic search runs while it is readable.';
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, a readable note holds data, usually a frontmatter value, nested deeper than the server can hand to its evaluator (about 3,500 levels under Node, more under Bun).';
+    readonly recovery: 'Flatten the deeply nested value, usually a frontmatter field, in the note the message names, or ask the operator to leave that note out of OBSIDIAN_READ_PATHS or add it to OBSIDIAN_DENY_PATHS; no scoped jsonlogic search runs while it is readable.';
 }, {
     readonly reason: 'omnisearch_unreachable';
     readonly thrownBy: 'service';
     readonly code: JsonRpcErrorCode.ServiceUnavailable;
-    readonly when: 'Omnisearch was reachable at startup but is now unreachable (Obsidian quit, plugin disabled, or mobile session).';
+    readonly when: 'Omnisearch was reachable at startup but did not answer: it is unreachable (Obsidian quit, plugin disabled, or mobile session), answered with a non-2xx status, or took longer than OBSIDIAN_REQUEST_TIMEOUT_MS. One attempt, never retried.';
     readonly retryable: true;
-    readonly recovery: 'Restart Obsidian with the Omnisearch plugin enabled, then restart this MCP server so it re-probes the plugin URL.';
-}], {
+    readonly recovery: 'Confirm Obsidian is running with the Omnisearch plugin enabled and retry, or narrow the query if it was slow. If Omnisearch stays down, restart Obsidian, then restart this MCP server so it re-probes the plugin URL.';
+}] | readonly [{
+    readonly reason: 'path_prefix_invalid_mode';
+    readonly code: 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: JsonRpcErrorCode.ValidationError;
+    readonly when: '`query` is missing in a mode that requires it: every mode but `jsonlogic`.';
+    readonly recovery: "Pass `query` as space-separated tokens, all of which a note must contain." | "Pass `query` — space-separated tokens, all required, for text mode, or BM25 query syntax (quoted phrases, `-exclusion`, `path:` / `ext:` filters) for omnisearch.";
+}, {
+    readonly reason: 'context_length_too_large';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The matches would make a response longer than one can be, so the whole text search failed: the Local REST API runs out of string capacity serializing them, or, under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS, the readable notes' matches alone would pass the same ceiling. Each match costs its context window plus about 150 characters of offsets and framing.";
+    readonly recovery: 'Narrow the query so fewer notes match, and drop very common tokens: every occurrence of each token in a matching note is a match costing about 150 characters beside its window, so a token like `the` can fail even at `contextLength` 0. Lowering `contextLength` helps only while the windows, about twice `contextLength` each, dominate that cost.';
+}, {
+    readonly reason: 'logic_required';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: '`logic` is missing for `jsonlogic` mode.';
+    readonly recovery: 'Pass a JSONLogic tree as `logic`. `glob` and `regexp` take `[PATTERN, VALUE]` — pattern first, e.g. `{"glob": ["Projects/*.md", {"var": "path"}]}`.';
+}, {
+    readonly reason: 'logic_invalid';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: 'The JSONLogic tree failed to evaluate against a note — an unrecognized operator, or an operand that could not be evaluated (an uncompilable `regexp` pattern). A mis-arity operator is not rejected: it evaluates to false and the search returns zero hits.';
+    readonly recovery: 'Check the operator names and arity. `glob` and `regexp` take `[PATTERN, VALUE]` — pattern first, e.g. `{"regexp": ["^Inbox/", {"var": "path"}]}`; the reverse order compiles the note field as the pattern.';
+}, {
+    readonly reason: 'logic_too_costly';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the server evaluates the JSONLogic tree itself, and the tree passed a bound: nesting deeper than 1,000 levels, more than a work budget, more than 10 s of evaluation, or more than 45 s for the whole search, reading the readable notes included. One work budget is per note — the size of values built by `merge`, `cat`, `map`, and array literals while evaluating that note, up to the note's own size plus 10,000,000 units — and one is per search: 10,000,000 units across every note for returned results, where a result whose JSON is at most 1,024 characters is free and a larger one pays for what it holds beyond its own note.";
+    readonly recovery: "Simplify the tree: nest fewer levels, avoid building arrays or strings many times a note's size with `merge`, `cat`, `map`, or `reduce`, return values drawn from the note rather than large built values or constants, and prefer a simpler `regexp` pattern.";
+}, {
+    readonly reason: 'text_search_too_costly';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the server runs text mode itself, reading every readable note whose path or body holds each token, and reading and matching them took more than 45 s.';
+    readonly recovery: 'Add rarer tokens, which every candidate note must contain, so fewer readable notes are read, or ask the operator to narrow OBSIDIAN_READ_PATHS or extend OBSIDIAN_DENY_PATHS.';
+}, {
+    readonly reason: 'link_fields_unavailable';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the JSONLogic tree names `links`, `backlinks`, or `unresolvedLinks` by a fixed `var`, `missing`, or `missing_some` key. Scoped searches leave these fields out, since Obsidian resolves each link across the whole vault, notes outside the scope included; a computed key reads them as null.';
+    readonly recovery: 'Find backlinks by body text: `{"regexp": ["\\\\[\\\\[Target Note(\\\\\\\\?\\\\||#|\\\\]\\\\])", {"var": "content"}]}` matches every readable note that wikilinks or embeds `Target Note`. For a note\'s outgoing links, call `obsidian_get_note` with `includeLinks: true`.';
+}, {
+    readonly reason: 'note_too_deep';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.SerializationError;
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, a readable note holds data, usually a frontmatter value, nested deeper than the server can hand to its evaluator (about 3,500 levels under Node, more under Bun).';
+    readonly recovery: 'Flatten the deeply nested value, usually a frontmatter field, in the note the message names, or ask the operator to leave that note out of OBSIDIAN_READ_PATHS or add it to OBSIDIAN_DENY_PATHS; no scoped jsonlogic search runs while it is readable.';
+}, ...never[]], {
     readonly effectiveQuery: z.ZodOptional<z.ZodString>;
     readonly notice: z.ZodOptional<z.ZodString>;
 }>;
 /**
  * Static specimen for the MCP definition linter (which duck-types tool
  * exports out of each `.tool.ts` file) and for existing tests that import
- * the tool directly. Defaults to `omnisearchReachable: false` — the safe
- * baseline that doesn't assume the optional plugin is installed. The entry
- * point (`src/index.ts`) builds the live tool via `buildSearchNotesTool`
- * with the actual probe result; this export is not the registered tool.
+ * the tool directly. Built without the `omnisearch` mode — the safe baseline
+ * that doesn't assume the optional plugin is installed. The entry point
+ * (`src/index.ts`) builds the live tool via `buildSearchNotesTool` with the
+ * startup `omnisearchAvailability`; this export is not the registered tool.
  * The omnisearch-enabled variant is exercised by tests rather than the
  * linter (two exports under the same tool name would collide on
  * `name-unique`).
@@ -242,6 +325,10 @@ export declare const obsidianSearchNotes: import("@cyanheads/mcp-ts-core").ToolD
         totalCount: z.ZodNumber;
         nextCursor: z.ZodOptional<z.ZodString>;
         truncated: z.ZodBoolean;
+        truncatedReason: z.ZodOptional<z.ZodEnum<{
+            cap_reached: "cap_reached";
+            filtered_after_cap: "filtered_after_cap";
+        }>>;
     }, z.core.$strip>], "mode">;
 }, z.core.$strip>, readonly [{
     readonly reason: 'path_prefix_invalid_mode';
@@ -251,14 +338,14 @@ export declare const obsidianSearchNotes: import("@cyanheads/mcp-ts-core").ToolD
 }, {
     readonly reason: 'query_required';
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: '`query` is missing for `text` or `omnisearch` mode (required for both).';
-    readonly recovery: 'Pass `query` — whitespace-separated tokens, all required, for text mode, or BM25 query syntax (quoted phrases, `-exclusion`, `path:` / `ext:` filters) for omnisearch.';
+    readonly when: '`query` is missing in a mode that requires it: every mode but `jsonlogic`.';
+    readonly recovery: "Pass `query` as space-separated tokens, all of which a note must contain." | "Pass `query` — space-separated tokens, all required, for text mode, or BM25 query syntax (quoted phrases, `-exclusion`, `path:` / `ext:` filters) for omnisearch.";
 }, {
     readonly reason: 'context_length_too_large';
     readonly thrownBy: 'service';
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: 'The Local REST API exhausted its string capacity building one context window per match, so the whole text search failed.';
-    readonly recovery: 'Lower `contextLength`, or narrow the query so fewer notes match. The ceiling is the product of the two, so a broad query fails at a much smaller window than a narrow one does.';
+    readonly when: "The matches would make a response longer than one can be, so the whole text search failed: the Local REST API runs out of string capacity serializing them, or, under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS, the readable notes' matches alone would pass the same ceiling. Each match costs its context window plus about 150 characters of offsets and framing.";
+    readonly recovery: 'Narrow the query so fewer notes match, and drop very common tokens: every occurrence of each token in a matching note is a match costing about 150 characters beside its window, so a token like `the` can fail even at `contextLength` 0. Lowering `contextLength` helps only while the windows, about twice `contextLength` each, dominate that cost.';
 }, {
     readonly reason: 'logic_required';
     readonly code: JsonRpcErrorCode.ValidationError;
@@ -274,22 +361,85 @@ export declare const obsidianSearchNotes: import("@cyanheads/mcp-ts-core").ToolD
     readonly reason: 'logic_too_costly';
     readonly thrownBy: 'service';
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: "With OBSIDIAN_READ_PATHS set, the server evaluates the JSONLogic tree itself, and the tree passed a bound: nesting deeper than 1,000 levels, more than a work budget, or more than 10 s of evaluation. One work budget is per note — the size of values built by `merge`, `cat`, `map`, and array literals while evaluating that note, up to the note's own size plus 10,000,000 units — and one is per search: 10,000,000 units across every note for returned results, where a result whose JSON is at most 1,024 characters is free and a larger one pays for what it holds beyond its own note.";
+    readonly when: "With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the server evaluates the JSONLogic tree itself, and the tree passed a bound: nesting deeper than 1,000 levels, more than a work budget, more than 10 s of evaluation, or more than 45 s for the whole search, reading the readable notes included. One work budget is per note — the size of values built by `merge`, `cat`, `map`, and array literals while evaluating that note, up to the note's own size plus 10,000,000 units — and one is per search: 10,000,000 units across every note for returned results, where a result whose JSON is at most 1,024 characters is free and a larger one pays for what it holds beyond its own note.";
     readonly recovery: "Simplify the tree: nest fewer levels, avoid building arrays or strings many times a note's size with `merge`, `cat`, `map`, or `reduce`, return values drawn from the note rather than large built values or constants, and prefer a simpler `regexp` pattern.";
+}, {
+    readonly reason: 'text_search_too_costly';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the server runs text mode itself, reading every readable note whose path or body holds each token, and reading and matching them took more than 45 s.';
+    readonly recovery: 'Add rarer tokens, which every candidate note must contain, so fewer readable notes are read, or ask the operator to narrow OBSIDIAN_READ_PATHS or extend OBSIDIAN_DENY_PATHS.';
+}, {
+    readonly reason: 'link_fields_unavailable';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the JSONLogic tree names `links`, `backlinks`, or `unresolvedLinks` by a fixed `var`, `missing`, or `missing_some` key. Scoped searches leave these fields out, since Obsidian resolves each link across the whole vault, notes outside the scope included; a computed key reads them as null.';
+    readonly recovery: 'Find backlinks by body text: `{"regexp": ["\\\\[\\\\[Target Note(\\\\\\\\?\\\\||#|\\\\]\\\\])", {"var": "content"}]}` matches every readable note that wikilinks or embeds `Target Note`. For a note\'s outgoing links, call `obsidian_get_note` with `includeLinks: true`.';
 }, {
     readonly reason: 'note_too_deep';
     readonly thrownBy: 'service';
     readonly code: JsonRpcErrorCode.SerializationError;
-    readonly when: 'With OBSIDIAN_READ_PATHS set, a readable note holds data, usually a frontmatter value, nested deeper than the server can hand to its evaluator (about 3,500 levels under Node, more under Bun).';
-    readonly recovery: 'Flatten the deeply nested value, usually a frontmatter field, in the note the message names, or ask the operator to leave that note out of OBSIDIAN_READ_PATHS; no scoped jsonlogic search runs while it is readable.';
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, a readable note holds data, usually a frontmatter value, nested deeper than the server can hand to its evaluator (about 3,500 levels under Node, more under Bun).';
+    readonly recovery: 'Flatten the deeply nested value, usually a frontmatter field, in the note the message names, or ask the operator to leave that note out of OBSIDIAN_READ_PATHS or add it to OBSIDIAN_DENY_PATHS; no scoped jsonlogic search runs while it is readable.';
 }, {
     readonly reason: 'omnisearch_unreachable';
     readonly thrownBy: 'service';
     readonly code: JsonRpcErrorCode.ServiceUnavailable;
-    readonly when: 'Omnisearch was reachable at startup but is now unreachable (Obsidian quit, plugin disabled, or mobile session).';
+    readonly when: 'Omnisearch was reachable at startup but did not answer: it is unreachable (Obsidian quit, plugin disabled, or mobile session), answered with a non-2xx status, or took longer than OBSIDIAN_REQUEST_TIMEOUT_MS. One attempt, never retried.';
     readonly retryable: true;
-    readonly recovery: 'Restart Obsidian with the Omnisearch plugin enabled, then restart this MCP server so it re-probes the plugin URL.';
-}], {
+    readonly recovery: 'Confirm Obsidian is running with the Omnisearch plugin enabled and retry, or narrow the query if it was slow. If Omnisearch stays down, restart Obsidian, then restart this MCP server so it re-probes the plugin URL.';
+}] | readonly [{
+    readonly reason: 'path_prefix_invalid_mode';
+    readonly code: 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: JsonRpcErrorCode.ValidationError;
+    readonly when: '`query` is missing in a mode that requires it: every mode but `jsonlogic`.';
+    readonly recovery: "Pass `query` as space-separated tokens, all of which a note must contain." | "Pass `query` — space-separated tokens, all required, for text mode, or BM25 query syntax (quoted phrases, `-exclusion`, `path:` / `ext:` filters) for omnisearch.";
+}, {
+    readonly reason: 'context_length_too_large';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The matches would make a response longer than one can be, so the whole text search failed: the Local REST API runs out of string capacity serializing them, or, under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS, the readable notes' matches alone would pass the same ceiling. Each match costs its context window plus about 150 characters of offsets and framing.";
+    readonly recovery: 'Narrow the query so fewer notes match, and drop very common tokens: every occurrence of each token in a matching note is a match costing about 150 characters beside its window, so a token like `the` can fail even at `contextLength` 0. Lowering `contextLength` helps only while the windows, about twice `contextLength` each, dominate that cost.';
+}, {
+    readonly reason: 'logic_required';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: '`logic` is missing for `jsonlogic` mode.';
+    readonly recovery: 'Pass a JSONLogic tree as `logic`. `glob` and `regexp` take `[PATTERN, VALUE]` — pattern first, e.g. `{"glob": ["Projects/*.md", {"var": "path"}]}`.';
+}, {
+    readonly reason: 'logic_invalid';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: 'The JSONLogic tree failed to evaluate against a note — an unrecognized operator, or an operand that could not be evaluated (an uncompilable `regexp` pattern). A mis-arity operator is not rejected: it evaluates to false and the search returns zero hits.';
+    readonly recovery: 'Check the operator names and arity. `glob` and `regexp` take `[PATTERN, VALUE]` — pattern first, e.g. `{"regexp": ["^Inbox/", {"var": "path"}]}`; the reverse order compiles the note field as the pattern.';
+}, {
+    readonly reason: 'logic_too_costly';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the server evaluates the JSONLogic tree itself, and the tree passed a bound: nesting deeper than 1,000 levels, more than a work budget, more than 10 s of evaluation, or more than 45 s for the whole search, reading the readable notes included. One work budget is per note — the size of values built by `merge`, `cat`, `map`, and array literals while evaluating that note, up to the note's own size plus 10,000,000 units — and one is per search: 10,000,000 units across every note for returned results, where a result whose JSON is at most 1,024 characters is free and a larger one pays for what it holds beyond its own note.";
+    readonly recovery: "Simplify the tree: nest fewer levels, avoid building arrays or strings many times a note's size with `merge`, `cat`, `map`, or `reduce`, return values drawn from the note rather than large built values or constants, and prefer a simpler `regexp` pattern.";
+}, {
+    readonly reason: 'text_search_too_costly';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the server runs text mode itself, reading every readable note whose path or body holds each token, and reading and matching them took more than 45 s.';
+    readonly recovery: 'Add rarer tokens, which every candidate note must contain, so fewer readable notes are read, or ask the operator to narrow OBSIDIAN_READ_PATHS or extend OBSIDIAN_DENY_PATHS.';
+}, {
+    readonly reason: 'link_fields_unavailable';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, the JSONLogic tree names `links`, `backlinks`, or `unresolvedLinks` by a fixed `var`, `missing`, or `missing_some` key. Scoped searches leave these fields out, since Obsidian resolves each link across the whole vault, notes outside the scope included; a computed key reads them as null.';
+    readonly recovery: 'Find backlinks by body text: `{"regexp": ["\\\\[\\\\[Target Note(\\\\\\\\?\\\\||#|\\\\]\\\\])", {"var": "content"}]}` matches every readable note that wikilinks or embeds `Target Note`. For a note\'s outgoing links, call `obsidian_get_note` with `includeLinks: true`.';
+}, {
+    readonly reason: 'note_too_deep';
+    readonly thrownBy: 'service';
+    readonly code: JsonRpcErrorCode.SerializationError;
+    readonly when: 'With OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, a readable note holds data, usually a frontmatter value, nested deeper than the server can hand to its evaluator (about 3,500 levels under Node, more under Bun).';
+    readonly recovery: 'Flatten the deeply nested value, usually a frontmatter field, in the note the message names, or ask the operator to leave that note out of OBSIDIAN_READ_PATHS or add it to OBSIDIAN_DENY_PATHS; no scoped jsonlogic search runs while it is readable.';
+}, ...never[]], {
     readonly effectiveQuery: z.ZodOptional<z.ZodString>;
     readonly notice: z.ZodOptional<z.ZodString>;
 }>;

package/dist/mcp-server/tools/definitions/obsidian-search-notes.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"obsidian-search-notes.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/obsidian-search-notes.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA+GjE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,mBAAmB,EAAE,EAAE;IAAE,mBAAmB,EAAE,OAAO,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAwIhF,0BAA0B;;mBAE5B,uFAAuF;uBACnF,8DAA8D;;qBAGhE,gBAAgB;;mBAElB,yEAAyE;uBAE7E,wKAAwK;;qBAGlK,0BAA0B;uBACxB,SAAS;;mBAEb,0HAA0H;uBAE9H,iLAAiL;;qBAG3K,gBAAgB;;mBAElB,0CAA0C;uBAE9C,qJAAqJ;;qBAG/I,eAAe;uBACb,SAAS;;mBAEb,8PAA8P;uBAElQ,6MAA6M;;qBAGvM,kBAAkB;uBAChB,SAAS;;mBAEb,qkBAAqkB;uBAEzkB,gQAAgQ;;qBAG1P,eAAe;uBACb,SAAS;;mBAEb,iMAAiM;uBAErM,uNAAuN;;qBAGjN,wBAAwB;uBACtB,SAAS;;mBAEb,iHAAiH;;uBAGrH,mHAAmH;;;;GAqK1H;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA5OlB,0BAA0B;;mBAE5B,uFAAuF;uBACnF,8DAA8D;;qBAGhE,gBAAgB;;mBAElB,yEAAyE;uBAE7E,wKAAwK;;qBAGlK,0BAA0B;uBACxB,SAAS;;mBAEb,0HAA0H;uBAE9H,iLAAiL;;qBAG3K,gBAAgB;;mBAElB,0CAA0C;uBAE9C,qJAAqJ;;qBAG/I,eAAe;uBACb,SAAS;;mBAEb,8PAA8P;uBAElQ,6MAA6M;;qBAGvM,kBAAkB;uBAChB,SAAS;;mBAEb,qkBAAqkB;uBAEzkB,gQAAgQ;;qBAG1P,eAAe;uBACb,SAAS;;mBAEb,iMAAiM;uBAErM,uNAAuN;;qBAGjN,wBAAwB;uBACtB,SAAS;;mBAEb,iHAAiH;;uBAGrH,mHAAmH;;;;EAkLpC,CAAC"}
+{"version":3,"file":"obsidian-search-notes.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/obsidian-search-notes.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AASjE,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAiBnG;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAE5E;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,sBAAsB,CAAC,CAGjC;AAqGD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,UAAU,EAAE,EAAE;IAAE,UAAU,EAAE,sBAAsB,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA4J7E,0BAA0B;;mBAE5B,uFAAuF;uBACnF,8DAA8D;;qBAGhE,gBAAgB;;mBAElB,4EAA4E;;;qBAM1E,0BAA0B;uBACxB,SAAS;;mBAEb,wWAAwW;uBAE5W,yVAAyV;;qBAGnV,gBAAgB;;mBAElB,0CAA0C;uBAE9C,qJAAqJ;;qBAG/I,eAAe;uBACb,SAAS;;mBAEb,8PAA8P;uBAElQ,6MAA6M;;qBAGvM,kBAAkB;uBAChB,SAAS;;mBAEb,sqBAAsqB;uBAE1qB,gQAAgQ;;qBAG1P,wBAAwB;uBACtB,SAAS;;mBAEb,4MAA4M;uBAEhN,+KAA+K;;qBAGzK,yBAAyB;uBACvB,SAAS;;mBAEb,qVAAqV;uBAEzV,6QAA6Q;;qBAGvQ,eAAe;uBACb,SAAS;;mBAEb,wNAAwN;uBAE5N,wPAAwP;;qBAnFlP,wBAAwB;uBACtB,SAAS;;mBAEb,6OAA6O;;uBAGjP,wNAAwN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6O/N;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA/OlB,0BAA0B;;mBAE5B,uFAAuF;uBACnF,8DAA8D;;qBAGhE,gBAAgB;;mBAElB,4EAA4E;;;qBAM1E,0BAA0B;uBACxB,SAAS;;mBAEb,wWAAwW;uBAE5W,yVAAyV;;qBAGnV,gBAAgB;;mBAElB,0CAA0C;uBAE9C,qJAAqJ;;qBAG/I,eAAe;uBACb,SAAS;;mBAEb,8PAA8P;uBAElQ,6MAA6M;;qBAGvM,kBAAkB;uBAChB,SAAS;;mBAEb,sqBAAsqB;uBAE1qB,gQAAgQ;;qBAG1P,wBAAwB;uBACtB,SAAS;;mBAEb,4MAA4M;uBAEhN,+KAA+K;;qBAGzK,yBAAyB;uBACvB,SAAS;;mBAEb,qVAAqV;uBAEzV,6QAA6Q;;qBAGvQ,eAAe;uBACb,SAAS;;mBAEb,wNAAwN;uBAE5N,wPAAwP;;qBAnFlP,wBAAwB;uBACtB,SAAS;;mBAEb,6OAA6O;;uBAGjP,wNAAwN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0P1I,CAAC"}