obsidian-mcp-server 3.7.2 → 3.9.0

package/dist/services/obsidian/simple-search.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview The Local REST API's `POST /search/simple/` run in-server, for
+ * text searches under a read scope: plugin 5.2.0's `simpleSearch` over
+ * Obsidian 1.14.5's `prepareSimpleSearch`. The query is lower-cased and split
+ * on single spaces; a note matches when every token occurs in its lower-cased
+ * `basename + "\n\n" + body`. Each token's occurrences are found by `indexOf`,
+ * resuming one character past the end of the last, so an occurrence that
+ * touches or overlaps the previous one is skipped; the occurrences of every
+ * token are sorted and merged where they overlap or touch. A merged range
+ * inside the basename is a `filename` span whose context is the basename, one
+ * inside the body a `content` span with a `contextLength` window either side,
+ * widened one code unit rather than split a surrogate pair, and one across the
+ * two is dropped. Offsets index the lower-cased text, and windows are cut from
+ * the original, as the plugin cuts them. Hits are ordered by Obsidian's score,
+ * highest first, ties in the order notes were added (the plugin's vault order).
+ * @module services/obsidian/simple-search
+ */
+/** A span as `/search/simple/` reports it, plus where `match.start` sits in `context`. */
+export interface SimpleSearchSpan {
+    context: string;
+    contextStart: number;
+    match: {
+        end: number;
+        source: 'content' | 'filename';
+        start: number;
+    };
+}
+/** A note's `/search/simple/` hit. */
+export interface SimpleSearchHit {
+    filename: string;
+    matches: SimpleSearchSpan[];
+    score: number;
+}
+/**
+ * The query's tokens as `prepareSimpleSearch` reads them: lower-cased, split
+ * on single spaces (a tab or newline stays inside its token), empty pieces
+ * dropped. Repeats are dropped too: Obsidian scans a repeated token again, but
+ * its ranges coincide with the first scan's and merge away.
+ */
+export declare function simpleSearchTokens(query: string): string[];
+export declare const isHighSurrogate: (cu: number) => boolean;
+export declare const isLowSurrogate: (cu: number) => boolean;
+/**
+ * One text search over notes added in vault order, holding each hit's context
+ * windows. `maxResponseChars` bounds the plugin's response for those hits, its
+ * length as `JSON.stringify(hits, null, 2)` (see `HIT_FRAME`): every hit's
+ * filename and score, every span's offsets and escaped window, and the framing
+ * around each. The count grows span by span as each note is added, so the
+ * span that passes the bound fails the search with `context_length_too_large`
+ * at once, and no more spans are held than a response the plugin could send.
+ */
+export declare class SimpleSearch {
+    #private;
+    /** The distinct non-empty tokens; a note matches only when it holds every one. */
+    readonly tokens: readonly string[];
+    constructor(query: string, contextLength: number, maxResponseChars?: number);
+    /** Match one note, `body` as Obsidian's `cachedRead` gives it. */
+    add(path: string, body: string): void;
+    /** The hits, highest score first; equal scores keep the order their notes were added. */
+    hits(): SimpleSearchHit[];
+}
+//# sourceMappingURL=simple-search.d.ts.map

package/dist/services/obsidian/simple-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-search.d.ts","sourceRoot":"","sources":["../../../src/services/obsidian/simple-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,0FAA0F;AAC1F,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACvE;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAoCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAE1D;AAYD,eAAO,MAAM,eAAe,OAAQ,MAAM,YAAiC,CAAC;AAC5E,eAAO,MAAM,cAAc,OAAQ,MAAM,YAAiC,CAAC;AAkH3E;;;;;;;;GAQG;AACH,qBAAa,YAAY;;IAMvB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAEnC,YAAY,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,SAA2B,EAK5F;IAED,kEAAkE;IAClE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAiDpC;IAYD,yFAAyF;IACzF,IAAI,IAAI,eAAe,EAAE,CAExB;CACF"}

package/dist/services/obsidian/simple-search.js

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview The Local REST API's `POST /search/simple/` run in-server, for
+ * text searches under a read scope: plugin 5.2.0's `simpleSearch` over
+ * Obsidian 1.14.5's `prepareSimpleSearch`. The query is lower-cased and split
+ * on single spaces; a note matches when every token occurs in its lower-cased
+ * `basename + "\n\n" + body`. Each token's occurrences are found by `indexOf`,
+ * resuming one character past the end of the last, so an occurrence that
+ * touches or overlaps the previous one is skipped; the occurrences of every
+ * token are sorted and merged where they overlap or touch. A merged range
+ * inside the basename is a `filename` span whose context is the basename, one
+ * inside the body a `content` span with a `contextLength` window either side,
+ * widened one code unit rather than split a surrogate pair, and one across the
+ * two is dropped. Offsets index the lower-cased text, and windows are cut from
+ * the original, as the plugin cuts them. Hits are ordered by Obsidian's score,
+ * highest first, ties in the order notes were added (the plugin's vault order).
+ * @module services/obsidian/simple-search
+ */
+import { validationError } from '@cyanheads/mcp-ts-core/errors';
+/**
+ * Lengths of the fixed parts of the plugin's response, which its Express app
+ * writes with `res.json` under `json spaces` 2, so `JSON.stringify(hits,
+ * null, 2)`:
+ *
+ * ```text
+ * [
+ *   {
+ *     "filename": "Folder/Note.md",
+ *     "score": -1.2,
+ *     "matches": [
+ *       {
+ *         "match": {
+ *           "start": 12,
+ *           "end": 17,
+ *           "source": "content"
+ *         },
+ *         "context": "…"
+ *       }
+ *     ]
+ *   }
+ * ]
+ * ```
+ *
+ * A hit or a span counts its separator, line break, and indentation, and its
+ * keys and braces. Its values are counted where they are known.
+ */
+const RESPONSE_FRAME = 2;
+const HIT_FRAME = 58;
+/** A `matches` array with no span is `[]`; one with spans adds a line break and indentation before its `]`. */
+const EMPTY_MATCHES = 2;
+const MATCHES_FRAME = 6;
+const SPAN_FRAME = 128;
+/**
+ * The query's tokens as `prepareSimpleSearch` reads them: lower-cased, split
+ * on single spaces (a tab or newline stays inside its token), empty pieces
+ * dropped. Repeats are dropped too: Obsidian scans a repeated token again, but
+ * its ranges coincide with the first scan's and merge away.
+ */
+export function simpleSearchTokens(query) {
+    return [...new Set(query.toLowerCase().split(' ').filter(Boolean))];
+}
+/**
+ * Obsidian's note basename (`TFile.basename`): the file name less its last
+ * `.extension`, the whole name when its only dot leads or trails it.
+ */
+function noteBasename(path) {
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    const dot = name.lastIndexOf('.');
+    return dot <= 0 || dot === name.length - 1 ? name : name.slice(0, dot);
+}
+export const isHighSurrogate = (cu) => cu >= 0xd800 && cu <= 0xdbff;
+export const isLowSurrogate = (cu) => cu >= 0xdc00 && cu <= 0xdfff;
+/**
+ * Upstream's `widenToCodePointBoundaries`: grow `[start, end)` by at most one
+ * code unit per side so neither edge splits a surrogate pair.
+ */
+function widen(text, start, end) {
+    let from = start;
+    if (from > 0 && from < text.length && isLowSurrogate(text.charCodeAt(from)))
+        from -= 1;
+    let to = end;
+    if (to > 0 && to < text.length && isHighSurrogate(text.charCodeAt(to - 1)))
+        to += 1;
+    return [from, to];
+}
+/** Characters `JSON.stringify` writes for a whole number: its decimal digits. */
+function digits(n) {
+    let count = 1;
+    for (let power = 10; power <= n; power *= 10)
+        count++;
+    return count;
+}
+/**
+ * Characters `JSON.stringify` adds escaping `text[i]`: one for `"`, `\`, and
+ * the controls with a short escape (`\b \t \n \f \r`), five for any other
+ * control or a lone surrogate (`\uXXXX`).
+ */
+function escapeOverhead(text, i) {
+    const cu = text.charCodeAt(i);
+    if (cu === 0x22 || cu === 0x5c)
+        return 1;
+    if (cu < 0x20)
+        return cu >= 0x08 && cu <= 0x0d && cu !== 0x0b ? 1 : 5;
+    if (isHighSurrogate(cu))
+        return isLowSurrogate(text.charCodeAt(i + 1)) ? 0 : 5;
+    if (isLowSurrogate(cu))
+        return isHighSurrogate(text.charCodeAt(i - 1)) ? 0 : 5;
+    return 0;
+}
+/**
+ * Characters `JSON.stringify` adds escaping the window `text.slice(from, to)`,
+ * for windows given in note order, where neither edge moves back. Two running
+ * sums of `escapeOverhead` over the characters scanned so far, one per edge,
+ * give each window as their difference: what windows share is scanned once,
+ * and what no window covers is skipped. `escapeOverhead` reads a surrogate's
+ * partner in the note; an edge that cuts a pair the note holds whole (`widen`
+ * stops one code unit short when surrogates run three or more in a row)
+ * leaves that half lone in the window, escaped too.
+ */
+function windowEscapes(text) {
+    let left = 0;
+    let leftSum = 0;
+    let right = 0;
+    let rightSum = 0;
+    return (from, to) => {
+        if (from >= to)
+            return 0;
+        if (from >= right) {
+            left = right = from;
+            leftSum = rightSum;
+        }
+        for (; left < from; left++)
+            leftSum += escapeOverhead(text, left);
+        for (; right < to; right++)
+            rightSum += escapeOverhead(text, right);
+        let sum = rightSum - leftSum;
+        if (isLowSurrogate(text.charCodeAt(from)) && isHighSurrogate(text.charCodeAt(from - 1))) {
+            sum += 5;
+        }
+        if (isHighSurrogate(text.charCodeAt(to - 1)) && isLowSurrogate(text.charCodeAt(to)))
+            sum += 5;
+        return sum;
+    };
+}
+/**
+ * The merged ranges `prepareSimpleSearch` reports for `text`, and its score;
+ * `undefined` when some token does not occur. With no tokens every text
+ * matches, with no ranges and a score of 0.
+ */
+function prepareSimpleSearch(tokens, queryLength, text) {
+    const lower = text.toLowerCase();
+    const found = [];
+    for (const token of tokens) {
+        const before = found.length;
+        for (let at = lower.indexOf(token); at !== -1; at = lower.indexOf(token, at + token.length + 1)) {
+            found.push([at, at + token.length]);
+        }
+        if (found.length === before)
+            return;
+    }
+    // Array sort is stable, and ranges sharing a start merge alike in any order.
+    found.sort((a, b) => a[0] - b[0]);
+    const ranges = [];
+    for (const range of found) {
+        const last = ranges.at(-1);
+        if (last === undefined || last[1] < range[0])
+            ranges.push(range);
+        else if (last[1] < range[1])
+            last[1] = range[1];
+    }
+    return { ranges, score: score(ranges, queryLength, text.length) };
+}
+/** Obsidian's simple-search score, with its operations in its order so the result is bit-identical. */
+function score(ranges, queryLength, textLength) {
+    const first = ranges[0];
+    const last = ranges.at(-1);
+    if (first === undefined || last === undefined)
+        return 0;
+    let s = 0;
+    s -= Math.max(0, ranges.length - 1);
+    s -= (last[1] - first[0] + 1 - queryLength) / 100;
+    s -= first[0] / 1e3;
+    s -= textLength / 1e4;
+    return s;
+}
+/**
+ * One text search over notes added in vault order, holding each hit's context
+ * windows. `maxResponseChars` bounds the plugin's response for those hits, its
+ * length as `JSON.stringify(hits, null, 2)` (see `HIT_FRAME`): every hit's
+ * filename and score, every span's offsets and escaped window, and the framing
+ * around each. The count grows span by span as each note is added, so the
+ * span that passes the bound fails the search with `context_length_too_large`
+ * at once, and no more spans are held than a response the plugin could send.
+ */
+export class SimpleSearch {
+    #contextLength;
+    #hits = [];
+    #maxResponseChars;
+    #queryLength;
+    #responseChars = RESPONSE_FRAME;
+    /** The distinct non-empty tokens; a note matches only when it holds every one. */
+    tokens;
+    constructor(query, contextLength, maxResponseChars = Number.POSITIVE_INFINITY) {
+        this.tokens = simpleSearchTokens(query);
+        this.#queryLength = query.length;
+        this.#contextLength = contextLength;
+        this.#maxResponseChars = maxResponseChars;
+    }
+    /** Match one note, `body` as Obsidian's `cachedRead` gives it. */
+    add(path, body) {
+        const basename = noteBasename(path);
+        const prefix = `${basename}\n\n`;
+        const result = prepareSimpleSearch(this.tokens, this.#queryLength, prefix + body);
+        if (!result)
+            return;
+        this.#charge(HIT_FRAME + JSON.stringify(path).length + String(result.score).length + EMPTY_MATCHES);
+        const basenameJson = JSON.stringify(basename).length;
+        const escapes = windowEscapes(body);
+        const matches = [];
+        const chargeSpan = (start, end, source, contextJson) => this.#charge((matches.length === 0 ? MATCHES_FRAME - EMPTY_MATCHES : 0) +
+            SPAN_FRAME +
+            digits(start) +
+            digits(end) +
+            source.length +
+            2 +
+            contextJson);
+        for (const [s, e] of result.ranges) {
+            if (s < prefix.length && e <= prefix.length) {
+                const end = Math.min(e, basename.length);
+                chargeSpan(s, end, 'filename', basenameJson);
+                matches.push({
+                    context: basename,
+                    contextStart: s,
+                    match: { start: s, end, source: 'filename' },
+                });
+            }
+            else if (s >= prefix.length) {
+                const start = s - prefix.length;
+                const end = e - prefix.length;
+                const [from, widened] = widen(body, Math.max(start - this.#contextLength, 0), end + this.#contextLength);
+                const to = Math.min(widened, body.length);
+                const context = body.slice(from, to);
+                chargeSpan(start, end, 'content', 2 + context.length + escapes(from, to));
+                matches.push({
+                    context,
+                    contextStart: start - from,
+                    match: { start, end, source: 'content' },
+                });
+            }
+        }
+        this.#hits.push({ filename: path, score: result.score, matches });
+    }
+    /** Add `chars` to the response, failing the search once it passes `maxResponseChars`. */
+    #charge(chars) {
+        this.#responseChars += chars;
+        if (this.#responseChars <= this.#maxResponseChars)
+            return;
+        throw validationError(`The matches for this search (contextLength ${this.#contextLength}) would take more than ${this.#maxResponseChars.toLocaleString('en-US')} characters to send across the readable notes, more than one response can carry. Each match costs its context window plus about 150 characters of offsets and framing, so the total tracks the number of matches as well as contextLength.`, { reason: 'context_length_too_large', contextLength: this.#contextLength });
+    }
+    /** The hits, highest score first; equal scores keep the order their notes were added. */
+    hits() {
+        return this.#hits.toSorted((a, b) => b.score - a.score);
+    }
+}
+//# sourceMappingURL=simple-search.js.map

package/dist/services/obsidian/simple-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-search.js","sourceRoot":"","sources":["../../../src/services/obsidian/simple-search.ts"],"names":[],"mappings":"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"}

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.3",
   "name": "obsidian-mcp-server",
-  "version": "3.7.2",
+  "version": "3.9.0",
   "description": "Read, write, search, and surgically edit Obsidian vault notes, tags, and frontmatter via MCP. STDIO or Streamable HTTP.",
   "author": {
     "name": "cyanheads",
@@ -31,6 +31,7 @@
         "OBSIDIAN_ENABLE_COMMANDS": "${user_config.OBSIDIAN_ENABLE_COMMANDS}",
         "OBSIDIAN_READ_PATHS": "${user_config.OBSIDIAN_READ_PATHS}",
         "OBSIDIAN_WRITE_PATHS": "${user_config.OBSIDIAN_WRITE_PATHS}",
+        "OBSIDIAN_DENY_PATHS": "${user_config.OBSIDIAN_DENY_PATHS}",
         "OBSIDIAN_READ_ONLY": "${user_config.OBSIDIAN_READ_ONLY}",
         "OBSIDIAN_DELETE_ELICITATION": "${user_config.OBSIDIAN_DELETE_ELICITATION}",
         "OBSIDIAN_OMNISEARCH_URL": "${user_config.OBSIDIAN_OMNISEARCH_URL}",
@@ -68,7 +69,7 @@
     },
     "OBSIDIAN_REQUEST_TIMEOUT_MS": {
       "title": "Request Timeout (ms)",
-      "description": "Per-request timeout in milliseconds. Default: 30000.",
+      "description": "Milliseconds one request attempt may take before it fails with obsidian_timeout; GET, PUT, and DELETE retry it, and all the requests of one tool call share a 45 s budget, or this value when it is longer. Default: 30000.",
       "type": "string",
       "required": false,
       "default": ""
@@ -89,7 +90,14 @@
     },
     "OBSIDIAN_WRITE_PATHS": {
       "title": "Write Path Allowlist",
-      "description": "Comma-separated vault-relative folder allowlist for writes. Unset = full vault, or the read scope when reads are restricted. Example: 'projects/,scratch/'.",
+      "description": "Comma-separated vault-relative folder allowlist for writes. Unset = full vault, or the read scope when reads are restricted; paths in OBSIDIAN_DENY_PATHS stay denied. Example: 'projects/,scratch/'.",
+      "type": "string",
+      "required": false,
+      "default": ""
+    },
+    "OBSIDIAN_DENY_PATHS": {
+      "title": "Denied Paths",
+      "description": "Comma-separated vault-relative paths withheld from reads and writes, overriding both allowlists. Unset = nothing denied. Example: 'private/,journal/therapy/'.",
       "type": "string",
       "required": false,
       "default": ""
@@ -110,7 +118,7 @@
     },
     "OBSIDIAN_OMNISEARCH_URL": {
       "title": "Omnisearch URL",
-      "description": "Override URL for the Omnisearch plugin HTTP server (port 51361 by default). Set only if the plugin is not on the default port.",
+      "description": "Override URL for the Omnisearch plugin HTTP server (port 51361 by default). Set only if the plugin is not on the default port. Under read or deny paths it is never called and the omnisearch search mode is withheld.",
       "type": "string",
       "required": false,
       "default": ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-mcp-server",
-  "version": "3.7.2",
+  "version": "3.9.0",
   "mcpName": "io.github.cyanheads/obsidian-mcp-server",
   "description": "Read, write, search, and surgically edit Obsidian vault notes, tags, and frontmatter via MCP. STDIO or Streamable HTTP.",
   "type": "module",
@@ -83,7 +83,7 @@
   },
   "license": "Apache-2.0",
   "engines": {
-    "bun": ">=1.4.0",
+    "bun": ">=1.4.4",
     "node": ">=24.0.0"
   },
   "packageManager": "bun@1.4.4",
@@ -91,25 +91,25 @@
     "access": "public"
   },
   "dependencies": {
-    "@cyanheads/mcp-ts-core": "^0.13.18",
+    "@cyanheads/mcp-ts-core": "^0.13.22",
     "glob-to-regexp": "0.4.1",
     "js-yaml": "^5.5.0",
     "json-logic-js": "2.0.5",
     "marked": "17.0.6",
     "pino-pretty": "^13.2.0",
-    "undici": "^8.12.3",
+    "undici": "^8.12.4",
     "yaml": "^2.9.1",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.6.3",
+    "@biomejs/biome": "^2.6.6",
     "@socketsecurity/bun-security-scanner": "^1.1.3",
-    "@types/node": "^26.6.5",
-    "@vitest/coverage-istanbul": "^5.0.5",
+    "@types/node": "^26.6.6",
+    "@vitest/coverage-istanbul": "^5.1.0",
     "depcheck": "^1.4.7",
     "ignore": "^7.0.14",
-    "tsc-alias": "^1.9.9",
+    "tsc-alias": "^1.9.10",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.5"
+    "vitest": "^5.1.0"
   }
 }

package/server.json

@@ -6,14 +6,14 @@
     "url": "https://github.com/cyanheads/obsidian-mcp-server",
     "source": "github"
   },
-  "version": "3.7.2",
+  "version": "3.9.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "obsidian-mcp-server",
       "runtimeHint": "npx",
-      "version": "3.7.2",
+      "version": "3.9.0",
       "environmentVariables": [
         {
           "name": "OBSIDIAN_API_KEY",
@@ -37,7 +37,7 @@
         },
         {
           "name": "OBSIDIAN_REQUEST_TIMEOUT_MS",
-          "description": "Per-request timeout in milliseconds.",
+          "description": "Milliseconds one request attempt (headers and body) may take before it fails with obsidian_timeout. GET, PUT, and DELETE retry a timed-out attempt; all the requests of one tool call share a 45 s budget, or this value when it is longer.",
           "format": "string",
           "isRequired": false,
           "default": "30000"
@@ -51,13 +51,19 @@
         },
         {
           "name": "OBSIDIAN_READ_PATHS",
-          "description": "Optional comma-separated vault-relative folder allowlist for reads. Prefix-based with implicit recursion; case-insensitive; trailing slashes normalized. Unset = full vault. Write paths are implicitly readable. Example: 'public/,projects/'.",
+          "description": "Optional comma-separated vault-relative folder allowlist for reads. Prefix-based with implicit recursion; case-insensitive; backslashes read as slashes, repeated and trailing slashes and '.' segments dropped, and names normalized to Unicode NFC; an entry naming the vault root ('.') is rejected at startup. Unset = full vault. Write paths are implicitly readable. Example: 'public/,projects/'.",
           "format": "string",
           "isRequired": false
         },
         {
           "name": "OBSIDIAN_WRITE_PATHS",
-          "description": "Optional comma-separated vault-relative folder allowlist for writes. Same syntax as OBSIDIAN_READ_PATHS. Unset = full vault, or the read scope when reads are restricted. Example: 'projects/,scratch/'.",
+          "description": "Optional comma-separated vault-relative folder allowlist for writes. Same syntax as OBSIDIAN_READ_PATHS. Unset = full vault, or the read scope when reads are restricted; paths in OBSIDIAN_DENY_PATHS stay denied. Example: 'projects/,scratch/'.",
+          "format": "string",
+          "isRequired": false
+        },
+        {
+          "name": "OBSIDIAN_DENY_PATHS",
+          "description": "Optional comma-separated vault-relative paths withheld from reads and writes. Same syntax as OBSIDIAN_READ_PATHS. Wins over both allowlists; denied paths are left out of listings, search results, and tag counts. Unset = nothing denied. Example: 'private/,journal/therapy/'.",
           "format": "string",
           "isRequired": false
         },
@@ -77,7 +83,7 @@
         },
         {
           "name": "OBSIDIAN_OMNISEARCH_URL",
-          "description": "Override URL for the Omnisearch plugin HTTP server. Unset derives from OBSIDIAN_BASE_URL host with port 51361. Required only if the Omnisearch plugin is not on the default port.",
+          "description": "Override URL for the Omnisearch plugin HTTP server. Unset derives from OBSIDIAN_BASE_URL host with port 51361. Required only if the Omnisearch plugin is not on the default port. Under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS the URL is never called and the omnisearch search mode is withheld.",
           "format": "string",
           "isRequired": false
         },
@@ -98,7 +104,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "obsidian-mcp-server",
       "runtimeHint": "npx",
-      "version": "3.7.2",
+      "version": "3.9.0",
       "environmentVariables": [
         {
           "name": "MCP_TRANSPORT_TYPE",
@@ -128,7 +134,7 @@
         },
         {
           "name": "OBSIDIAN_REQUEST_TIMEOUT_MS",
-          "description": "Per-request timeout in milliseconds.",
+          "description": "Milliseconds one request attempt (headers and body) may take before it fails with obsidian_timeout. GET, PUT, and DELETE retry a timed-out attempt; all the requests of one tool call share a 45 s budget, or this value when it is longer.",
           "format": "string",
           "isRequired": false,
           "default": "30000"
@@ -142,13 +148,19 @@
         },
         {
           "name": "OBSIDIAN_READ_PATHS",
-          "description": "Optional comma-separated vault-relative folder allowlist for reads. Prefix-based with implicit recursion; case-insensitive; trailing slashes normalized. Unset = full vault. Write paths are implicitly readable. Example: 'public/,projects/'.",
+          "description": "Optional comma-separated vault-relative folder allowlist for reads. Prefix-based with implicit recursion; case-insensitive; backslashes read as slashes, repeated and trailing slashes and '.' segments dropped, and names normalized to Unicode NFC; an entry naming the vault root ('.') is rejected at startup. Unset = full vault. Write paths are implicitly readable. Example: 'public/,projects/'.",
           "format": "string",
           "isRequired": false
         },
         {
           "name": "OBSIDIAN_WRITE_PATHS",
-          "description": "Optional comma-separated vault-relative folder allowlist for writes. Same syntax as OBSIDIAN_READ_PATHS. Unset = full vault, or the read scope when reads are restricted. Example: 'projects/,scratch/'.",
+          "description": "Optional comma-separated vault-relative folder allowlist for writes. Same syntax as OBSIDIAN_READ_PATHS. Unset = full vault, or the read scope when reads are restricted; paths in OBSIDIAN_DENY_PATHS stay denied. Example: 'projects/,scratch/'.",
+          "format": "string",
+          "isRequired": false
+        },
+        {
+          "name": "OBSIDIAN_DENY_PATHS",
+          "description": "Optional comma-separated vault-relative paths withheld from reads and writes. Same syntax as OBSIDIAN_READ_PATHS. Wins over both allowlists; denied paths are left out of listings, search results, and tag counts. Unset = nothing denied. Example: 'private/,journal/therapy/'.",
           "format": "string",
           "isRequired": false
         },
@@ -168,7 +180,7 @@
         },
         {
           "name": "OBSIDIAN_OMNISEARCH_URL",
-          "description": "Override URL for the Omnisearch plugin HTTP server. Unset derives from OBSIDIAN_BASE_URL host with port 51361. Required only if the Omnisearch plugin is not on the default port.",
+          "description": "Override URL for the Omnisearch plugin HTTP server. Unset derives from OBSIDIAN_BASE_URL host with port 51361. Required only if the Omnisearch plugin is not on the default port. Under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS the URL is never called and the omnisearch search mode is withheld.",
           "format": "string",
           "isRequired": false
         },

package/skills/obsidian-guide/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: obsidian-guide
+description: "Gates and multi-call workflows for the obsidian_* tools: pin active and periodic targets to a path, round-trip heading sections without editing the wrong one or dropping its sub-sections, page a search to the end before editing its hits, match tags exactly, and repeat writes after a timeout or a dropped connection. Use before editing several notes, restructuring headings, writing to a periodic note, retagging, moving a note, or retrying a failed obsidian_* write."
+license: Apache-2.0
+metadata:
+  author: cyanheads
+  version: "1.0"
+---
+
+## Scope
+
+One Obsidian vault, reached through the Local REST API plugin while Obsidian runs. Each note tool reads or edits one note per call. No tool moves or renames a note, and none rewrites links in other notes. The multi-note jobs are the workflows below.
+
+## Identifiers
+
+- **Note path**: `hits[].filename` from obsidian_search_notes, `entries[].path` from obsidian_list_notes, and the `path` every note tool returns. Writes and deletes match it exactly, letter case included.
+- **Heading locator**: the full `Parent::Child` paths in obsidian_get_note's `document-map` `headings`, and the `sectionTarget` a section read or write returns.
+- **Tag**: no leading `#`. A note's own `tags` (obsidian_get_note `full`, the JSONLogic `tags` field) hold its tags as written, letter case included. Parent tags show up only in tag counts.
+
+## Gates
+
+1. **Pin `active` and `periodic` targets after the first call.** Each call resolves them again. `active` is whichever file has focus in Obsidian at that moment, and a `periodic` target with no `date` is the current period. For the rest of the task, address the note by the `path` the first call returned.
+2. **A missing periodic note can't be created through a `periodic` target.** Every tool reads the target before acting, so a write to a period with no note also fails `periodic_not_found`. Ask the user to create it in Obsidian. Or, if they agree, write it by path: read an earlier period's note (pass `date`) to learn the folder and filename pattern. A note written this way holds only what you send, without the user's periodic-note template. On Local REST API 5.0.2 and later without the periodic-notes extension, every `periodic` target fails `periodic_unsupported`, whether or not the note exists; find the note with obsidian_search_notes or obsidian_list_notes and address it by path.
+3. **Write a heading back with the `sectionTarget` the read returned, never the bare name you sent.** A bare name resolves differently on each side. A read takes the first heading with that text in document order. A write takes the top-level heading with that text when there is one. Reading `Notes` and then writing `Notes` can touch two different sections.
+4. **A heading section is its whole subtree.** obsidian_get_note `format: "section"` returns the heading line, its body, and every sub-section under it. A replace rewrites all of that, so send the sub-sections back or target the child heading instead. An append lands below the last sub-section. A prepend lands right under the heading line. Round-trip a read through obsidian_write_note with `section`, which drops the leading heading line. obsidian_patch_note `replace` keeps a leading `#` heading line, and plugin v5.0 and later refuse that with `heading_outside_section`.
+5. **Page a search to the end before editing its hits.** Without OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS, every page re-runs the search. The cursor is an offset into the new result, so edits that remove matches shift later pages and skip notes. Under a read scope, later pages come from the first page's hits for at most 5 minutes past the last page read. Collect every `filename` first, then edit.
+6. **A text hit doesn't promise a replace match.** Text mode needs each token somewhere in the filename or body, in any case. obsidian_replace_in_note needs the exact string, case-sensitive by default, and searches the body only by default. Read each note's `perReplacement[].count`: `0` is a success that wrote nothing. `useRegex` patterns run without the `m` flag, so `^` and `$` match the ends of the scoped text, not of a line. To anchor a line, use `(?<=^|\n)` and `(?=\n|$)`.
+7. **Tags match exactly.** `{"in": ["work", {"var": "tags"}]}` misses notes tagged only `Work`, or only `work/tasks`, which obsidian_list_tags still counts under `work`. To catch nested tags, use `{"some": [{"var": "tags"}, {"regexp": ["^work(/|$)", {"var": ""}]}]}`. obsidian_manage_tags `remove` is exact the same way, and its default `location: "frontmatter"` leaves inline `#tag`s in the body. Pass `location: "both"` and check the returned `tags`.
+8. **A JSONLogic hit is a note whose tree returns something truthy**, and that value is the hit's `result`. A note whose tree returns `false`, `null`, `0`, `""`, `[]`, or `{}` is left out. Return the field you need and one search reads it from every match: `{"if": [<test>, {"var": "tags"}, null]}` gives each match's tags. An empty value still drops the note.
+9. **After `obsidian_timeout` or `obsidian_unreachable` on a write, assume it may have landed.** One write call makes several requests under one shared budget (45 s at the default timeout): a read before the write, the write, and a read after. The error can arrive after the write applied, and the server never re-sends a whole-file append or a section write. Repeating is safe for obsidian_write_note, obsidian_patch_note `replace`, obsidian_manage_frontmatter, and obsidian_manage_tags. On a retry, `file_exists` (a create), `note_missing` (a delete), and `content_preexists` (a section append or prepend sent without `applyIfContentPreexists`) each mean the first attempt landed. Don't force a `content_preexists` through with `applyIfContentPreexists`. Read the note before repeating a whole-file obsidian_append_to_note, or an obsidian_replace_in_note whose `replace` still contains its `search`.
+10. **Confirm before deleting.** obsidian_delete_note deletes on the first call unless its description says it asks. Get the user's go-ahead on the exact path first.
+
+## Workflows
+
+**Capture into a periodic note.** Call obsidian_append_to_note with the `periodic` target. Add `section` to land under one of the note's headings, and `createTargetIfMissing: true` if that heading may not exist yet. On `periodic_not_found` or `periodic_unsupported`, follow gate 2. Follow-up edits use the returned `path` (gate 1).
+
+**Restructure headings.**
+
+1. Call obsidian_get_note `document-map` for every full heading path.
+2. Read each section you'll change by its full path, edit it, and write it back through obsidian_write_note `section` (gates 3–4).
+3. Rename or remove a heading line with obsidian_replace_in_note. No section write changes a heading line.
+4. To reorder or move whole sections, rewrite the note: obsidian_get_note `content`, edit, then obsidian_write_note `overwrite: true`. Compare `previousSizeInBytes` with `currentSizeInBytes`.
+5. A renamed heading breaks `[[Note#Old heading]]` links in other notes. Fix them as in *Move or rename a note*.
+
+**Find, then edit across notes.**
+
+1. Search and page to the end (gate 5). To find notes by filename anywhere in the vault, test `path` with `regexp` in jsonlogic mode, e.g. `{"regexp": ["(^|/)Meeting[^/]*\\.md$", {"var": "path"}]}`. Don't walk obsidian_list_notes for this: its `nameRegex` never enters a folder whose own name fails the pattern.
+2. When `instructions` gives a narrower Writable scope than Readable, drop hits outside the Writable scope before writing.
+3. Edit each hit and read its counts (gate 6).
+
+**Retag notes.**
+
+1. Find the notes with a tree that returns their tags (gates 7–8).
+2. For each note, call obsidian_manage_tags `add` with the new tag and `remove` with the old one, both with `location: "both"`.
+3. Confirm with obsidian_list_tags `nameRegex`. A parent tag's count includes its nested tags.
+
+**Move or rename a note.** No tool does this, and nothing updates links that point at the old name.
+
+1. Read the note with obsidian_get_note `content` and write it with obsidian_write_note at the new path. That write fails with `file_exists` rather than overwrite a note already there.
+2. Find the notes that wikilink the old name with the backlink `regexp` in obsidian_search_notes' `logic` description. Rewrite each link with obsidian_replace_in_note (gate 6).
+3. Delete the old note once the user agrees (gate 10).