obsidian-native-mcp 1.0.3 → 1.2.0

package/README.md

@@ -2,36 +2,37 @@
 
 # Obsidian Native MCP
 
-**Zero-dependency MCP server for Obsidian vaults**  
-Direct filesystem access — no Obsidian process, no REST API plugin required.
+**LLM-optimized MCP server for Obsidian vaults**
+Surgical edits, hash-based concurrency safety, no whole-file rewrites.
 
 [![Build](https://img.shields.io/github/actions/workflow/status/usrivastava92/obsidian-native-mcp/ci.yml?branch=main&label=CI&logo=github)](https://github.com/usrivastava92/obsidian-native-mcp/actions)
 [![Release](https://img.shields.io/github/v/release/usrivastava92/obsidian-native-mcp?logo=semanticrelease)](https://github.com/usrivastava92/obsidian-native-mcp/releases)
 [![npm](https://img.shields.io/npm/v/obsidian-native-mcp?logo=npm)](https://www.npmjs.com/package/obsidian-native-mcp)
-[![npm downloads](https://img.shields.io/npm/dm/obsidian-native-mcp?logo=npm)](https://www.npmjs.com/package/obsidian-native-mcp)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
 
 </div>
 
-Obsidian Native MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI assistants (Claude Desktop, etc.) direct, safe access to your Obsidian vaults.
+A [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI assistants (Claude Desktop, Cursor, Rovo Dev, etc.) direct, safe, **context-efficient** access to your Obsidian vaults.
 
 **Two ways to use it:**
 
-- **Obsidian plugin** (recommended) — 1-click install, auto-discovers vaults, settings UI, runs inside Obsidian
-- **CLI** — standalone, works without Obsidian running, configured via env var or config file
+- **Obsidian plugin** — 1-click install, auto-discovers vaults, settings UI for per-tool toggles, runs inside Obsidian over HTTP/SSE with a bearer token.
+- **CLI** — standalone Node binary, configured via env var or config file, speaks JSON-RPC over stdio with Content-Length framing.
 
-**Why Obsidian Native MCP over other solutions?**
+## Why Obsidian Native MCP
 
-| Feature            | Obsidian Native MCP                    | obsidian-mcp-tools (archived)             |
-| ------------------ | -------------------------------------- | ----------------------------------------- |
-| Obsidian required? | **Plugin: no. CLI: no.**               | Yes — must be running with Local REST API |
-| Dependencies       | **Zero** — uses only Node.js stdlib    | MCP SDK, arktype, zod, radash, turndown…  |
-| Distribution       | Obsidian plugin + npm CLI              | Bun-compiled binary                       |
-| Multi-vault        | **Built-in** — one server, many vaults | No                                        |
-| Cross-platform     | **1 codebase, runs everywhere (WORA)** | Platform-specific binaries                |
-| File patching      | Headings, blocks, frontmatter          | Via REST API                              |
-| Setup effort       | Plugin: 1 click. CLI: one command.     | Manual download + config                  |
+The defining design goal is **minimize how many bytes the LLM has to push around per edit.** Every read returns content **plus cryptographic hashes**; every write declares the precondition hash it expects. The result: most edits become tiny `str_replace`s or unified-diff patches instead of full file rewrites.
+
+| Feature                  | Obsidian Native MCP                                               | Typical Obsidian MCP server          |
+| ------------------------ | ----------------------------------------------------------------- | ------------------------------------ |
+| **Edit model**           | `str_replace`, `apply_patch`, `apply_edits` — surgical by default | Read whole file → write whole file   |
+| **Concurrency safety**   | Cryptographic preconditions (`expected_*_hash`) on every write    | None — silent clobbering             |
+| **Structural awareness** | mdast-AST: code-fenced "headings" never treated as headings       | Regex hacks that corrupt code blocks |
+| **Frontmatter**          | Real YAML parser with nested key paths                            | Hand-rolled line matching            |
+| **Atomicity**            | Multi-file `bulk.apply` with rollback                             | None                                 |
+| **Permissions**          | Read-only mode + per-tool toggle + per-vault subdir allow/deny    | All-or-nothing                       |
+| **Audit trail**          | JSONL log with content hashes before/after every mutation         | None                                 |
+| **Multi-vault**          | First-class                                                       | Usually one vault                    |
 
 ## Installation
 
@@ -39,8 +40,8 @@ Obsidian Native MCP is a [Model Context Protocol](https://modelcontextprotocol.i
 
 1. Open Obsidian → Settings → Community Plugins → Browse
 2. Search for "Obsidian Native MCP" and install
-3. Enable the plugin in Community Plugins list
-4. Go to plugin settings → toggle which vaults to expose → copy the MCP URL
+3. Enable in Community Plugins
+4. Open plugin settings: select which vaults to expose, optionally toggle per-tool permissions, copy the MCP URL
 
 ### CLI (standalone)
 
@@ -61,11 +62,11 @@ npm run build
 
 ### Plugin
 
-Plugin auto-discovers all your Obsidian vaults from Obsidian's own config. Open plugin settings to select which vaults to expose.
+Auto-discovers all your Obsidian vaults from Obsidian's own config. Pick which to expose in plugin settings. Plugin also surfaces a bearer token and the MCP URL.
 
 ### CLI
 
-Configure vault(s) via environment variable or config file.
+Either an env var or a config file.
 
 ```bash
 # Single vault
@@ -73,9 +74,6 @@ export OBSIDIAN_VAULT_PATHS=/Users/me/my-obsidian-vault
 
 # Multiple vaults (semicolons on all platforms)
 export OBSIDIAN_VAULT_PATHS=/Users/me/personal;/Users/me/work
-
-# Windows
-set OBSIDIAN_VAULT_PATHS=C:\Users\me\personal;C:\Users\me\work
 ```
 
 Config file at `~/.config/obsidian-native-mcp/vaults.json`:
@@ -89,17 +87,25 @@ Config file at `~/.config/obsidian-native-mcp/vaults.json`:
 }
 ```
 
+Optional flags:
+
+```bash
+obsidian-native-mcp --read-only            # all write tools disabled
+obsidian-native-mcp --vault notes=/path    # ad-hoc named vault
+obsidian-native-mcp --config ./my.json     # explicit config file
+```
+
 ## Usage
 
 ### Obsidian plugin
 
-After enabling the plugin, open its settings tab. You'll see a URL like `http://127.0.0.1:9789/sse`. Add it to your `claude_desktop_config.json`:
+Add the URL from plugin settings to your `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "obsidian-native-mcp": {
-      "url": "http://127.0.0.1:9789/sse"
+      "url": "http://127.0.0.1:9789/sse?token=YOUR_TOKEN"
     }
   }
 }
@@ -122,57 +128,121 @@ After enabling the plugin, open its settings tab. You'll see a URL like `http://
 
 ## Tools
 
-| Tool             | Description                                             |
-| ---------------- | ------------------------------------------------------- |
-| `list_vaults`    | List all configured vaults with paths                   |
-| `get_vault_info` | Stats per vault (file count, etc.)                      |
-| `list_files`     | List files/dirs in a vault directory                    |
-| `get_file`       | Read file content (markdown or json with frontmatter)   |
-| `create_file`    | Create or overwrite a file                              |
-| `append_to_file` | Append content to a file                                |
-| `patch_file`     | Patch by heading, block reference, or frontmatter field |
-| `delete_file`    | Delete a file                                           |
-| `search`         | Full-text search across markdown files                  |
-
-All file tools accept an optional `vault` parameter. When only one vault is configured, it's inferred automatically.
+All tools accept an optional `vault` parameter; with a single vault configured, it's inferred. Every read returns hashes used by writes as preconditions.
+
+### Read tools
+
+| Tool              | What it returns                                  | Notes                                            |
+| ----------------- | ------------------------------------------------ | ------------------------------------------------ |
+| `vault.list`      | All configured vaults                            | —                                                |
+| `vault.info`      | Stats per vault                                  | —                                                |
+| `file.list`       | Paged file listing                               | `recursive`, `pattern` (glob), `limit`, `offset` |
+| `file.find`       | Find files by name                               | exact / substring / glob / regex                 |
+| `file.read`       | Full file content + `contentHash` + `totalLines` | Use freely — guidelines/AGENTS.md/etc.           |
+| `file.read_range` | Line range + `rangeHash`                         | Cheaper for big files                            |
+| `outline`         | Heading skeleton + `sectionHash` per heading     | Sub-KB even for 5000-line files                  |
+| `heading.find`    | All matches (line, level, `sectionHash`)         | Returns all — caller disambiguates               |
+| `block.find`      | Block ref location + `blockHash`                 | Structural-type aware (list/table/paragraph)     |
+| `frontmatter.get` | Whole frontmatter or single nested key           | YAML-aware                                       |
+| `tags.list`       | Tags from frontmatter + body                     | Code-fence aware                                 |
+| `links.get`       | Outlinks, backlinks, or both                     | Typed: wiki/embed/header/block/markdown          |
+| `metadata.read`   | Frontmatter + headings + tags + links + hashes   | One-shot context dump                            |
+| `search.content`  | Paged full-text matches with per-line hashes     | DSL: `tag:`, `path:`, `\"phrase\"`, AND/OR/NOT   |
+
+### Write tools — surgical primaries
+
+| Tool          | Shape                                                        | Why                                                              |
+| ------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `str_replace` | `{file, find, replace, occurrence?, expected_content_hash?}` | The default editing verb — quote what you see                    |
+| `apply_patch` | Unified diff                                                 | Multi-hunk edits in one shot; context lines act as preconditions |
+| `apply_edits` | `[{find, replace, occurrence?}, ...]`                        | Multi-edit, atomic per file                                      |
+
+### Write tools — structural (when you have the address)
+
+| Tool                   | Notes                                                       |
+| ---------------------- | ----------------------------------------------------------- |
+| `heading.replace_body` | Requires `expected_section_hash`                            |
+| `heading.rename`       | Optionally update wiki-link references                      |
+| `block.replace`        | Requires `expected_block_hash`; preserves list/table prefix |
+| `block.rename`         | Renames a `^id` and updates references                      |
+| `frontmatter.set`      | Nested key path; YAML-safe round-trip                       |
+| `frontmatter.delete`   | Nested key path                                             |
+| `lines.replace`        | Requires `expected_range_hash`                              |
+| `lines.insert`         | Insert at line N                                            |
+
+### Write tools — whole-file & metadata
+
+| Tool           | Notes                                                                       |
+| -------------- | --------------------------------------------------------------------------- |
+| `file.create`  | Create-only — errors if file exists                                         |
+| `file.replace` | Whole-file rewrite — heavy, requires `expected_content_hash`                |
+| `file.append`  | Cheap, no read needed                                                       |
+| `file.move`    | Default `on_conflict: error`; alternatives: `overwrite`, `rename`           |
+| `file.delete`  | Defaults to `.obsidian/trash`; hard delete requires `expected_content_hash` |
+
+### Power & batch
+
+| Tool            | Notes                                                                     |
+| --------------- | ------------------------------------------------------------------------- |
+| `bulk.apply`    | Multi-file, multi-op batch. `atomic: true` → snapshot + rollback on error |
+| `regex.replace` | Two-step: server returns proposal token + diff → caller confirms          |
+| `file.diff`     | Diff between two `contentHash` versions (when cache has them)             |
 
 ### Prompts
 
-Place markdown files in a `Prompts/` folder in any vault, tagged with `mcp-tools-prompt` in frontmatter:
+Place markdown in any vault's `Prompts/` folder with `mcp-tools-prompt` in the frontmatter; Templater-style `<% tp.mcpTools.prompt(name, hint) %>` placeholders become MCP prompt arguments automatically.
+
+## Concurrency safety
 
-```markdown
----
-tags: [mcp-tools-prompt]
-description: Summarize the daily note
----
+Every read returns one or more hashes. Every write that operates on an existing range requires the matching `expected_*_hash`. If the file changed underneath you (a human edit in Obsidian, a parallel tool call, etc.), the write returns:
 
-Summarize what happened on <% tp.mcpTools.prompt("date", "Date to summarize") %>.
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "STALE_PRECONDITION",
+    "current_content_hash": "sha256:…",
+    "current_section_hash": "sha256:…"
+  }
+}
 ```
 
-Prompts appear automatically in your MCP client's prompt selector.
-
-## Roadmap
-
-- [x] Zero-dependency MCP protocol implementation
-- [x] Full vault CRUD (list, read, create, append, patch, delete)
-- [x] Full-text search across vault
-- [x] Multi-vault support
-- [x] Cross-platform (runs anywhere Node.js runs)
-- [x] Prompt templates from vault's Prompts folder
-- [x] Config file support (`~/.config/obsidian-native-mcp/vaults.json`)
-- [x] Obsidian community plugin with settings UI
-- [x] Vault auto-discovery from Obsidian config
-- [x] HTTP/SSE transport for plugin
-- [x] Two distribution methods (plugin + CLI)
-- [ ] Smart Connections-like semantic search (local embeddings)
-- [ ] Vault change watching (file system events)
-- [ ] npm publish workflow
+The model refreshes from the new hash and retries. No silent clobbering.
 
-## Security
+## Permissions
+
+- **Read-only mode** — plugin toggle or CLI `--read-only` flag disables every write tool.
+- **Per-tool toggle** — disable individual tools (e.g., turn off `file.delete` for less-trusted clients).
+- **Per-vault subdir allow/deny** — limit a client to a vault subtree.
+
+## Audit log
 
-obsidian-native-mcp runs locally on your machine. The plugin exposes vaults over localhost only. The CLI communicates over local stdio. No data is sent to external services. Only vaults you explicitly select/configure are accessible.
+Every mutating call appends one JSONL line to `<vault>/.obsidian/plugins/obsidian-native-mcp/audit.log`:
+
+```json
+{
+  "ts": "2026-05-21T13:00:00Z",
+  "tool": "str_replace",
+  "vault": "notes",
+  "file": "Daily/2026-05-21.md",
+  "args_hash": "sha256:…",
+  "before_hash": "sha256:…",
+  "after_hash": "sha256:…",
+  "dry_run": false,
+  "ok": true
+}
+```
+
+Rotates at 5 MB by default.
+
+## Security
 
-For security concerns, please open an issue or see [SECURITY.md](SECURITY.md).
+- Runs locally only — loopback (`127.0.0.1`) for HTTP, stdio for CLI.
+- HTTP transport requires a startup-generated bearer token in the SSE URL.
+- Origin header allowlist enforced; CORS is not `*`.
+- Request bodies capped at 5 MB; max-sessions and idle TTL applied.
+- Path-traversal protection on every vault-relative path.
+- Only vaults you explicitly select are accessible.
 
 ## License
 

package/dist/audit/log.js

@@ -0,0 +1,99 @@
+/**
+ * JSONL audit log for mutating tool calls.
+ *
+ *   <vault>/.obsidian/plugins/obsidian-native-mcp/audit.log
+ *
+ * Each entry contains: ts, tool, vault, file, args_hash, before_hash,
+ * after_hash, dry_run, client_id. We don't log raw args (could leak note
+ * bodies); we hash them.
+ *
+ * Rotation: when the file exceeds 10MB, rename to `audit.log.1` (keep up to
+ * 5 rotations).
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { ensureDir } from "../fs/io.js";
+const REL = ".obsidian/plugins/obsidian-native-mcp/audit.log";
+const MAX_BYTES = 10 * 1024 * 1024;
+const MAX_ROTATIONS = 5;
+export class AuditLog {
+    vaultRoot;
+    constructor(vaultRoot) {
+        this.vaultRoot = vaultRoot;
+    }
+    async append(entry) {
+        const filePath = path.join(this.vaultRoot, REL);
+        await ensureDir(path.dirname(filePath));
+        await this.rotateIfNeeded(filePath);
+        const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n";
+        await fs.appendFile(filePath, line, "utf-8");
+    }
+    async tail(n = 100) {
+        const filePath = path.join(this.vaultRoot, REL);
+        let text;
+        try {
+            text = await fs.readFile(filePath, "utf-8");
+        }
+        catch {
+            return [];
+        }
+        const lines = text.split("\n").filter((l) => l.length > 0);
+        const slice = lines.slice(-n);
+        const out = [];
+        for (const l of slice) {
+            try {
+                out.push(JSON.parse(l));
+            }
+            catch {
+                /* skip malformed line */
+            }
+        }
+        return out;
+    }
+    static hashArgs(args) {
+        const stable = stableStringify(args);
+        const h = createHash("sha256");
+        h.update(stable, "utf-8");
+        return `sha256:${h.digest("hex")}`;
+    }
+    async rotateIfNeeded(filePath) {
+        let stat;
+        try {
+            stat = await fs.stat(filePath);
+        }
+        catch {
+            return;
+        }
+        if (stat.size < MAX_BYTES)
+            return;
+        // Shift .N → .(N+1)
+        for (let i = MAX_ROTATIONS - 1; i >= 1; i--) {
+            const from = `${filePath}.${i}`;
+            const to = `${filePath}.${i + 1}`;
+            try {
+                await fs.rename(from, to);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        try {
+            await fs.rename(filePath, `${filePath}.1`);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map((v) => stableStringify(v)).join(",") + "]";
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
+}
+//# sourceMappingURL=log.js.map

package/dist/audit/log.js.map

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

package/dist/cache/file-cache.js

@@ -0,0 +1,66 @@
+/**
+ * Simple bounded LRU file cache (Design B from DESIGN_V1.md §11).
+ *
+ * Validation: an entry is reused only if both `mtimeMs` and `size` match the
+ * current `fs.stat` result. On any write the server performs, we refresh the
+ * entry inline using the post-write text in memory (avoiding a re-parse from
+ * disk).
+ */
+import * as fs from "node:fs/promises";
+import { readText } from "../fs/io.js";
+import { parseFile } from "../markdown/parse-file.js";
+import { toPosix } from "../fs/paths.js";
+import * as path from "node:path";
+export class LRUFileCache {
+    cache = new Map();
+    maxEntries;
+    constructor(maxEntries = 256) {
+        this.maxEntries = maxEntries;
+    }
+    async get(vaultRoot, absPath) {
+        const stat = await fs.stat(absPath);
+        const cached = this.cache.get(absPath);
+        if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+            this.touch(absPath);
+            return cached;
+        }
+        const rawText = await readText(absPath);
+        const relPath = toPosix(path.relative(vaultRoot, absPath));
+        const parsed = parseFile({ path: relPath, absPath, rawText, stat });
+        this.put(absPath, parsed);
+        return parsed;
+    }
+    invalidate(absPath) {
+        this.cache.delete(absPath);
+    }
+    refreshAfterWrite(vaultRoot, absPath, text, stat) {
+        const relPath = toPosix(path.relative(vaultRoot, absPath));
+        const parsed = parseFile({ path: relPath, absPath, rawText: text, stat });
+        this.put(absPath, parsed);
+        return parsed;
+    }
+    size() {
+        return this.cache.size;
+    }
+    clear() {
+        this.cache.clear();
+    }
+    touch(absPath) {
+        const v = this.cache.get(absPath);
+        if (v === undefined)
+            return;
+        this.cache.delete(absPath);
+        this.cache.set(absPath, v);
+    }
+    put(absPath, parsed) {
+        this.cache.delete(absPath);
+        this.cache.set(absPath, parsed);
+        while (this.cache.size > this.maxEntries) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey === undefined)
+                break;
+            this.cache.delete(firstKey);
+        }
+    }
+}
+//# sourceMappingURL=file-cache.js.map

package/dist/cache/file-cache.js.map

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

package/dist/cli/index.js

@@ -1,40 +1,147 @@
 #!/usr/bin/env node
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const server_1 = require("../mcp/server");
-const stdio_transport_1 = require("../mcp/stdio-transport");
-const log_1 = require("../utils/log");
-const vaults_1 = require("../utils/vaults");
-const log = (0, log_1.createLogger)("cli");
-async function main() {
-    const registry = new vaults_1.VaultRegistry();
-    if (process.argv.includes("--version") || process.argv.includes("-v")) {
-        console.log("0.2.0");
-        process.exit(0);
+/**
+ * CLI entry point: stdio MCP server using the official @modelcontextprotocol/sdk.
+ *
+ * Usage:
+ *   obsidian-native-mcp [--read-only] [--vault name=path]... [--config path]
+ *
+ * Vault resolution order: --vault flags → $OBSIDIAN_VAULT_PATHS env
+ * → ~/.config/obsidian-native-mcp/vaults.json
+ * (Obsidian auto-discovery is skipped in CLI mode — configure vaults explicitly)
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { VaultRegistry } from "../vault/registry.js";
+import { Permissions, DEFAULT_PERMISSIONS } from "../vault/permissions.js";
+import { LRUFileCache } from "../cache/file-cache.js";
+import { AuditLog } from "../audit/log.js";
+import { ToolRegistry } from "../handlers/registry.js";
+import { registerAll } from "../tools/index.js";
+import { FsPromptsProvider } from "../prompts/provider.js";
+function parseFlags(argv) {
+    const flags = { readOnly: false, initialVaults: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--read-only")
+            flags.readOnly = true;
+        else if (a === "--config")
+            flags.configPath = argv[++i];
+        else if (a === "--vault") {
+            const v = argv[++i];
+            const eq = v?.indexOf("=") ?? -1;
+            if (eq === -1) {
+                process.stderr.write(`--vault expects name=path, got: ${v}\n`);
+                process.exit(2);
+            }
+            flags.initialVaults.push({ name: v.slice(0, eq), root: path.resolve(v.slice(eq + 1)) });
+        }
+        else if (a === "--version" || a === "-V") {
+            process.stdout.write(readPkgVersion() + "\n");
+            process.exit(0);
+        }
+        else if (a === "--help" || a === "-h") {
+            process.stdout.write("obsidian-native-mcp [--read-only] [--vault name=path]... [--config path]\n");
+            process.exit(0);
+        }
     }
-    const vaults = registry.list();
-    const validation = registry.validate();
-    log.info("starting obsidian-native-mcp", {
-        transport: "stdio",
-        vaultCount: vaults.length,
-        source: registry.getSource(),
-    });
-    if (vaults.length === 0) {
-        log.warn("no vaults configured", {
-            hint: "Set OBSIDIAN_VAULT_PATHS or ~/.config/obsidian-native-mcp/vaults.json",
-        });
+    return flags;
+}
+function readPkgVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkgPath = path.resolve(here, "..", "..", "package.json");
+        const raw = readFileSync(pkgPath, "utf-8");
+        const json = JSON.parse(raw);
+        return json.version ?? "0.0.0";
     }
-    for (const vault of validation.missing) {
-        log.warn("configured vault path does not exist", { vault: vault.name, path: vault.path });
+    catch {
+        return "0.0.0";
     }
-    const server = (0, server_1.createServer)(registry);
-    const transport = new stdio_transport_1.StdioTransport();
-    transport.onRequest(async (msg) => server.handleRequest(msg));
-    transport.start();
-    log.info("stdio transport ready", { protocol: "jsonl" });
 }
-main().catch((err) => {
-    log.error("startup failed", { error: (0, log_1.formatError)(err) });
+async function main() {
+    const flags = parseFlags(process.argv.slice(2));
+    const version = readPkgVersion();
+    // CLI mode: skip Obsidian auto-discovery — user configures vaults via env/flags.
+    const registry = await VaultRegistry.discover({
+        initial: flags.initialVaults,
+        skipObsidian: true,
+    });
+    if (registry.count() === 0) {
+        process.stderr.write("error: no vaults configured\n");
+        process.stderr.write("  set OBSIDIAN_VAULT_PATHS=/path/to/vault\n");
+        process.stderr.write("  or pass --vault name=/path/to/vault\n");
+        process.exit(2);
+    }
+    const perms = new Permissions({ ...DEFAULT_PERMISSIONS, readOnly: flags.readOnly });
+    const cache = new LRUFileCache();
+    const audit = new AuditLog(registry.list()[0].root);
+    const toolReg = new ToolRegistry();
+    registerAll(toolReg);
+    const promptsProvider = new FsPromptsProvider(registry);
+    // ------------------------------------------------------------------
+    // Wire everything into the official MCP SDK Server
+    // ------------------------------------------------------------------
+    const server = new Server({ name: "obsidian-native-mcp", version }, { capabilities: { tools: {}, prompts: {} } });
+    // tools/list
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const tools = toolReg
+            .list((name) => perms.isToolEnabled(name))
+            .map((t) => ({
+            name: t.name,
+            description: t.summary,
+            inputSchema: t.schema,
+        }));
+        return { tools };
+    });
+    // tools/call
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const name = req.params.name;
+        const args = (req.params.arguments ?? {});
+        const vaultName = typeof args.vault === "string" ? args.vault : undefined;
+        let vault;
+        try {
+            vault = registry.resolve(vaultName);
+        }
+        catch (e) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: e.message }],
+            };
+        }
+        const ctx = { vault, perms, cache, audit, registry, clientId: "stdio" };
+        const result = await toolReg.invoke(name, args, ctx);
+        if (!result.ok) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: JSON.stringify(result.error) }],
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result.result) }],
+        };
+    });
+    // prompts/list
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        const prompts = await promptsProvider.list();
+        return { prompts };
+    });
+    // prompts/get
+    server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+        const out = await promptsProvider.get(req.params.name, req.params.arguments);
+        return out;
+    });
+    // ------------------------------------------------------------------
+    // Start with the official stdio transport
+    // ------------------------------------------------------------------
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    process.stderr.write(`fatal: ${e.message}\n`);
     process.exit(1);
 });
 //# sourceMappingURL=index.js.map