vault-cortex 0.10.3 → 0.10.5

package/README.md

@@ -49,9 +49,9 @@ What it does:
    - **Remote** — a VPS with [Obsidian Sync](https://obsidian.md/sync),
      reachable from any device
 2. Offers the most common optional settings — memory layer and folder,
-   daily notes folder and format, file tools, semantic search, port,
-   timezone (plus sync direction for remote) — press enter to keep the
-   defaults, or pick the ones you want to change
+   daily notes folder and format, file tools, read-only mode, semantic
+   search, port, timezone (plus sync direction for remote) — press enter
+   to keep the defaults, or pick the ones you want to change
 3. Generates a `.env` file with a securely generated `MCP_AUTH_TOKEN`
 4. Optionally starts the container and waits for the health check
 5. Prints your connection details — the MCP URL, your auth token, and how to

package/dist/env.js

@@ -58,6 +58,15 @@ MEMORY_ENABLED=true
 # Enable or disable file tools — vault_read_file and vault_list_files (default: true).
 # Set to false when Obsidian Sync has attachment syncing disabled.
 FILE_TOOLS_ENABLED=true
+# Run the server in read-only mode (default: false).
+# Set to true to hide every tool that changes the vault — clients can only
+# read and search. The memory folder is not auto-created in this mode.
+READONLY_MODE=false
+# Hide individual tools by name, comma-separated (default: none hidden).
+# Names match the README tools table: https://github.com/aliasunder/vault-cortex#tools
+# Subtractive only — it cannot re-enable a tool another setting hides; an
+# unknown tool name stops the server at startup so typos surface immediately.
+# DISABLED_TOOLS=vault_delete_note,vault_move_note
 # Memory folder name in your vault (default: About Me).
 MEMORY_DIR=About Me
 
@@ -160,6 +169,15 @@ MEMORY_ENABLED=true
 # Enable or disable file tools — vault_read_file and vault_list_files (default: true).
 # Set to false when Obsidian Sync has attachment syncing disabled.
 FILE_TOOLS_ENABLED=true
+# Run the server in read-only mode (default: false).
+# Set to true to hide every tool that changes the vault — clients can only
+# read and search. The memory folder is not auto-created in this mode.
+READONLY_MODE=false
+# Hide individual tools by name, comma-separated (default: none hidden).
+# Names match the README tools table: https://github.com/aliasunder/vault-cortex#tools
+# Subtractive only — it cannot re-enable a tool another setting hides; an
+# unknown tool name stops the server at startup so typos surface immediately.
+# DISABLED_TOOLS=vault_delete_note,vault_move_note
 # Memory folder name in your vault (default: About Me).
 MEMORY_DIR=About Me
 

package/dist/init.js

@@ -154,8 +154,9 @@ const reportWrites = (params, prompts) => {
 /**
  * Offers to start the container, walking a gate ladder where each failed
  * gate degrades to instructions instead of an error: daemon running → user
- * consents → docker run succeeds → health check passes. Returns true only
- * when the server is confirmed up.
+ * consents → docker run succeeds → health check passes. Returns "running"
+ * when the server is confirmed up, "starting" when the container launched
+ * but the health check timed out, or "not-started" when a gate failed.
  */
 const offerDockerRun = async (params, deps) => {
     const { targetDir, port, mode, vaultPath } = params;
@@ -168,11 +169,11 @@ const offerDockerRun = async (params, deps) => {
                 nextStep: `\nThen start the server with:\n  ${startHint}`,
             })
             : buildDaemonNotRunningMessage(`, then run:\n  ${startHint}`));
-        return false;
+        return "not-started";
     }
     const startNow = await prompts.confirm("Start the server now?", true);
     if (!startNow)
-        return false;
+        return "not-started";
     const containerStarted = docker.dockerRun({
         mode,
         envFilePath: join(targetDir, ".env"),
@@ -181,7 +182,7 @@ const offerDockerRun = async (params, deps) => {
     });
     if (!containerStarted) {
         prompts.error("docker run failed — see output above.");
-        return false;
+        return "not-started";
     }
     const spinner = prompts.spinner();
     spinner.start("Waiting for the server to come up (first run may take a moment)");
@@ -189,10 +190,10 @@ const offerDockerRun = async (params, deps) => {
     const healthy = await pollHealth({ url: `http://127.0.0.1:${port}/healthz`, timeoutMs }, fetchFn);
     if (!healthy) {
         spinner.stop(healthTimeoutMessage(mode, timeoutMs));
-        return false;
+        return "starting";
     }
     spinner.stop("Server is up — health check passed.");
-    return true;
+    return "running";
 };
 // Local flow: resolve vault path → resolve target dir → generate token →
 // write .env → optionally start the container → print connect instructions.
@@ -271,10 +272,16 @@ const runLocalInit = async (flags, deps) => {
         prompts.log("Generated MCP auth token (saved to .env).");
     const port = readEnvPort(join(targetDir, ".env"));
     // --yes is for scripts/CI, so it never starts Docker.
-    const started = flags.yes
-        ? false
+    const startStatus = flags.yes
+        ? "not-started"
         : await offerDockerRun({ targetDir, port, mode: "local", vaultPath }, deps);
-    prompts.print(buildLocalConnectMessage({ targetDir, token, started, port, tokenWritten }));
+    prompts.print(buildLocalConnectMessage({
+        targetDir,
+        token,
+        startStatus,
+        port,
+        tokenWritten,
+    }));
     return 0;
 };
 // Remote flow (VPS + Obsidian Sync): resolve target dir → PUBLIC_URL →
@@ -347,12 +354,12 @@ const runRemoteInit = async (flags, deps) => {
     const effectivePublicUrl = readEnvPublicUrl(join(targetDir, ".env")) ?? publicUrl;
     // Without the sync token the container can't start (init-check-auth fails
     // and s6 stops it), so only offer docker run when it was provided.
-    const started = obsidianAuthToken === ""
-        ? false
+    const startStatus = obsidianAuthToken === ""
+        ? "not-started"
         : await offerDockerRun({ targetDir, port, mode: "remote" }, deps);
     // The container check above hit localhost on this machine; the public URL
     // is the ingress path clients actually use — probe it too, informationally.
-    if (started) {
+    if (startStatus === "running") {
         await reportPublicUrlProbe(effectivePublicUrl, {
             prompts,
             fetchFn: deps.fetchFn,
@@ -362,7 +369,7 @@ const runRemoteInit = async (flags, deps) => {
         targetDir,
         token,
         publicUrl: effectivePublicUrl,
-        started,
+        startStatus,
         obsidianTokenMissing: obsidianAuthToken === "",
         tokenWritten,
     }));

package/dist/messages.js

@@ -1,4 +1,5 @@
 import { styleText } from "node:util";
+import { CONTAINER_NAME } from "./docker.js";
 // Strip styling when stdout isn't a color TTY (piped output, CI) or NO_COLOR
 // is set (any value, including empty — per the NO_COLOR spec) so
 // captured/redirected output stays plain — no stray escape codes in copied
@@ -50,11 +51,14 @@ const upgradeCommand = (targetDir) => `npx vault-cortex@latest upgrade --dir "${
 // have. `start` runs the same re-create cycle and pulls the image on demand.
 export const startCommand = (targetDir) => `npx vault-cortex@latest start --dir "${targetDir}"`;
 const startServerLine = (targetDir) => `Start the server:\n  ${startCommand(targetDir)}`;
-/** Remote start line: running, blocked on the missing sync token, or ready to start. */
+const startingInBackgroundLine = () => `The server is starting in the background — check progress:\n  docker logs ${CONTAINER_NAME}`;
+/** Remote start line: running, starting, blocked on the missing sync token, or ready to start. */
 const remoteStartLine = (params) => {
-    const { targetDir, started, obsidianTokenMissing } = params;
-    if (started)
+    const { targetDir, startStatus, obsidianTokenMissing } = params;
+    if (startStatus === "running")
         return "The server is running.";
+    if (startStatus === "starting")
+        return startingInBackgroundLine();
     if (obsidianTokenMissing) {
         return `Fill in OBSIDIAN_AUTH_TOKEN in ${targetDir}/.env, then start the server:\n  ${startCommand(targetDir)}`;
     }
@@ -99,13 +103,14 @@ const curlGuidance = (mcpUrl) => `Clients without OAuth, scripts, and curl send
 const smokeTest = (healthUrl) => `Smoke test:
   curl ${healthUrl}`;
 /**
- * Remote health-check block. Started: the CLI verified localhost on the VPS,
- * but the public URL is a different check (ingress — DNS, TLS, proxy), so the
- * command stays, reworded as the works-from-any-device check. Not started:
- * the plain smoke test to run after starting.
+ * Remote health-check block. Running or starting: the CLI verified localhost
+ * on the VPS (or the container is still coming up), but the public URL is a
+ * different check (ingress — DNS, TLS, proxy), so the command stays, reworded
+ * as the works-from-any-device check. Not started: the plain smoke test to
+ * run after starting.
  */
-const remoteHealthCheckBlock = (healthUrl, started) => {
-    if (started) {
+const remoteHealthCheckBlock = (healthUrl, startStatus) => {
+    if (startStatus === "running" || startStatus === "starting") {
         return `Health check — works from any device that can reach the URL:
   curl ${healthUrl}`;
     }
@@ -119,18 +124,20 @@ const updateGuidance = (targetDir) => `Update to the latest release:
  * actually run.
  */
 export const buildLocalConnectMessage = (params) => {
-    const { targetDir, token, started, port, tokenWritten } = params;
+    const { targetDir, token, startStatus, port, tokenWritten } = params;
     const baseUrl = `http://localhost:${port}`;
-    const startLine = started
+    const startLine = startStatus === "running"
         ? "The server is running."
-        : startServerLine(targetDir);
+        : startStatus === "starting"
+            ? startingInBackgroundLine()
+            : startServerLine(targetDir);
     const tokenLine = tokenBlock({ targetDir, token, tokenWritten });
     // Once the server is confirmed up, the smoke test is dropped — the CLI just
     // verified this exact URL, so re-printing it reads as leftover homework.
     // Assembled as a filtered list so the omission leaves no stray blank line.
     const nonOauthBlocks = [
         curlGuidance(`${baseUrl}/mcp`),
-        started ? undefined : smokeTest(`${baseUrl}/healthz`),
+        startStatus === "running" ? undefined : smokeTest(`${baseUrl}/healthz`),
     ]
         .filter(Boolean)
         .join("\n\n");
@@ -187,10 +194,10 @@ ${bottomRule()}`;
  * handling here.
  */
 export const buildRemoteConnectMessage = (params) => {
-    const { targetDir, token, publicUrl, started, obsidianTokenMissing, tokenWritten, } = params;
+    const { targetDir, token, publicUrl, startStatus, obsidianTokenMissing, tokenWritten, } = params;
     const startLine = remoteStartLine({
         targetDir,
-        started,
+        startStatus,
         obsidianTokenMissing,
     });
     const tokenLine = tokenBlock({ targetDir, token, tokenWritten });
@@ -227,7 +234,7 @@ ${sectionRule("Non-OAuth")}
 
 ${curlGuidance(`${publicUrl}/mcp`)}
 
-${remoteHealthCheckBlock(`${publicUrl}/healthz`, started)}
+${remoteHealthCheckBlock(`${publicUrl}/healthz`, startStatus)}
 
 ${sectionRule("Settings")}
 

package/dist/optional-settings.js

@@ -37,6 +37,13 @@ const OPTIONAL_SETTINGS = [
         label: "File tools",
         question: "Enable file tools (read images, PDFs, and other non-Markdown files)?",
     },
+    {
+        kind: "toggle",
+        name: "READONLY_MODE",
+        label: "Read-only mode",
+        question: "Run the server in read-only mode (hide all tools that change the vault)?",
+        defaultEnabled: false,
+    },
     {
         kind: "toggle",
         name: "EMBEDDING_ENABLED",
@@ -127,11 +134,12 @@ export const derivePublicUrlOverride = (envContent, overrides) => {
     return { ...overrides, PUBLIC_URL: `http://localhost:${newPort}` };
 };
 /**
- * The .env spellings the server reads as "off" — env-var's asBool accepts
- * 0/1 alongside true/false. An absent or unrecognized value falls to the
- * server default, which is enabled for every curated toggle.
+ * True unless the .env value is an explicit "off" spelling — env-var's asBool
+ * accepts 0/1 alongside true/false. An absent or unrecognized value falls to
+ * the server default, declared per-toggle via defaultEnabled (enabled unless
+ * stated otherwise).
  */
-const isDisabledToggleValue = (value) => ["false", "0"].includes((value ?? "").toLowerCase());
+const isEnabledToggleValue = (value) => !["false", "0"].includes((value ?? "").toLowerCase());
 /**
  * Plain digits in the TCP port range. Number() coercion is not enough:
  * it accepts "1e4"/"0x1F40"/"+9000", which readEnvPort's /^PORT=(\d+)/
@@ -222,7 +230,15 @@ const askSettingValue = async (params, prompts) => {
     const { setting, currentValue } = params;
     switch (setting.kind) {
         case "toggle": {
-            const enabled = await prompts.confirm(setting.question, !isDisabledToggleValue(currentValue));
+            // An unset or empty var means the server default applies — seed the
+            // confirm from defaultEnabled, not from the enabled-unless-"false"
+            // heuristic (wrong for default-off toggles like READONLY_MODE).
+            // Empty string matters: `READONLY_MODE=` in .env is read as unset
+            // by Compose's `${VAR:-default}` and env-var's `.default()`.
+            const currentlyEnabled = !currentValue
+                ? (setting.defaultEnabled ?? true)
+                : isEnabledToggleValue(currentValue);
+            const enabled = await prompts.confirm(setting.question, currentlyEnabled);
             return String(enabled);
         }
         case "port":
@@ -258,7 +274,7 @@ export const askOptionalSettings = async (params, prompts) => {
         const currentValue = readOptionalValue(envContent, setting.name);
         const requiredToggle = OPTIONAL_SETTINGS.find((candidate) => candidate.name === setting.requiresToggle);
         const dependencyNote = requiredToggle &&
-            isDisabledToggleValue(readOptionalValue(envContent, requiredToggle.name))
+            !isEnabledToggleValue(readOptionalValue(envContent, requiredToggle.name))
             ? ` · not used while ${requiredToggle.label} is off`
             : "";
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-cortex",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "Set up a Vault Cortex MCP server for your Obsidian vault in one command: npx vault-cortex@latest init",
   "license": "MIT",
   "type": "module",