virlow-mcp 3.81.0 → 3.82.0

package/README.md

@@ -7,8 +7,8 @@ entire time.
 
 ## What it is
 
-virlow-mcp runs on your machine as a local process (`npx -y virlow-mcp`, launched by your
-AI client over stdio). It exposes 24 tools for three things:
+virlow-mcp runs on your machine as a local process (`npx -y virlow-mcp@latest`, launched by your
+AI client over stdio). It exposes tools for four things:
 
 - **Memories** — short, durable facts ("the user prefers TypeScript", "this repo's CI
   runs on self-hosted runners") that any AI tool can add, search semantically, and recall
@@ -30,6 +30,16 @@ AI client over stdio). It exposes 24 tools for three things:
   schema and values in the note's encrypted attrs, so the server sees neither. Properties
   ship in the Virlow app as of its epic 3, so what is written here is what the user sees in
   the note, the table, the board and the calendar.
+- **Attachments**: files on a note. `list_attachments`, `add_attachment`,
+  `read_attachment`, `rename_attachment`, `move_attachment`, `delete_attachment` and
+  `restore_attachment`. Files are encrypted in this process before upload, the same way the
+  app does it. `add_attachment` takes `text` or `content_base64` (up to 2 MB), or `path`, an
+  absolute path to a file on this machine (up to 35 MB). `read_attachment` returns text and
+  small files inline, and with `save_to` writes the decrypted file to disk instead; it never
+  replaces an existing file unless `overwrite` is true. `delete_attachment` moves a file to the
+  note's Recently deleted, where `restore_attachment` can bring it back for 30 days. `path` and
+  `save_to` exist only when this server runs on your machine over stdio (or `--http` on
+  loopback); the hosted connector and a non-loopback `--http` take inline content only.
 
 Everything is **end-to-end encrypted, zero-knowledge**: the encryption key is derived
 from your Virlow master password inside this local process and never leaves it. Every
@@ -44,7 +54,7 @@ through a tool call, and never seen by the AI model.
 ### This is the local server, and that distinction is the whole security model
 
 Every claim above is about **this package**, running on **your machine**. Virlow also
-offers a **hosted connector**: the same 24 tools, served from Virlow's own servers, so a
+offers a **hosted connector**: the same tools, served from Virlow's own servers, so a
 client can connect by URL with nothing installed. It is a genuinely different trust model,
 and the sentence "the key never leaves it" is the part that stops being true:
 
@@ -66,15 +76,25 @@ guarantee.
 
 ## Install / configure
 
-virlow-mcp needs no separate install — `npx -y virlow-mcp` fetches and runs it directly.
+virlow-mcp needs no separate install: `npx -y virlow-mcp@latest` fetches and runs it directly.
 Add it to your client's MCP config:
 
 ### Claude Code
 
 ```
-claude mcp add virlow -- npx -y virlow-mcp
+claude mcp add virlow -- npx -y virlow-mcp@latest
 ```
 
+On Windows, `npx` is a batch script, so wrap it in `cmd /c`:
+
+```
+claude mcp add virlow -- cmd /c npx -y virlow-mcp@latest
+```
+
+Run that from PowerShell or cmd. Git Bash rewrites `/c` into a path; there, edit
+`~/.claude.json` so the server's `"command"` is `"cmd"` and its `"args"` are
+`["/c", "npx", "-y", "virlow-mcp@latest"]`.
+
 ### Claude Desktop
 
 Add to your `claude_desktop_config.json`
@@ -86,7 +106,7 @@ Windows: `%APPDATA%\Claude\claude_desktop_config.json`):
   "mcpServers": {
     "virlow": {
       "command": "npx",
-      "args": ["-y", "virlow-mcp"]
+      "args": ["-y", "virlow-mcp@latest"]
     }
   }
 }
@@ -101,7 +121,7 @@ Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-local):
   "mcpServers": {
     "virlow": {
       "command": "npx",
-      "args": ["-y", "virlow-mcp"]
+      "args": ["-y", "virlow-mcp@latest"]
     }
   }
 }
@@ -114,7 +134,7 @@ Codex's MCP config is TOML, not JSON. Add to `~/.codex/config.toml`:
 ```toml
 [mcp_servers.virlow]
 command = "npx"
-args = ["-y", "virlow-mcp"]
+args = ["-y", "virlow-mcp@latest"]
 ```
 
 ### Self-hosting Virlow
@@ -128,7 +148,7 @@ Claude Desktop / Cursor:
   "mcpServers": {
     "virlow": {
       "command": "npx",
-      "args": ["-y", "virlow-mcp"],
+      "args": ["-y", "virlow-mcp@latest"],
       "env": { "VIRLOW_API_URL": "https://api.your-domain.com" }
     }
   }
@@ -147,7 +167,7 @@ only spawn a command use this package as a pipe:
   "mcpServers": {
     "virlow": {
       "command": "npx",
-      "args": ["-y", "virlow-mcp", "--connect", "http://127.0.0.1:47821/mcp",
+      "args": ["-y", "virlow-mcp@latest", "--connect", "http://127.0.0.1:47821/mcp",
                "--token-file", "<path the app shows you>"]
     }
   }
@@ -156,6 +176,20 @@ only spawn a command use this package as a pipe:
 
 In this mode nothing is decrypted in this process. It forwards to the app and back.
 
+### Staying up to date
+
+With `virlow-mcp@latest` in the command, your client gets the newest release each time it
+starts the server, so restarting the client (or opening a new session) is the whole update.
+Without `@latest`, `npx` can keep running a copy it downloaded earlier; add `@latest` to an
+existing config to fix that. Pin an exact version (`virlow-mcp@3.81.0`) only if you want
+updates to wait for you. The desktop app updates itself and its built-in server, and the
+hosted connector is updated on Virlow's side.
+
+The server checks npm once at startup, and the `status` tool and the unlock page say when a
+newer version exists. The request tells npm only that someone at your IP checked
+virlow-mcp's version; it carries no account data. Turn it off with
+`VIRLOW_MCP_NO_UPDATE_CHECK=1`.
+
 ## First use
 
 1. Ask your AI client to run the **`unlock`** tool. This opens a browser window pointed
@@ -206,13 +240,13 @@ just give you two versions to keep in sync.
 ## Reaching your vault from a session that is not on this machine
 
 By default `virlow-mcp` speaks stdio, so your AI client spawns it as a child
-process and everything stays on one machine. `--http` serves the same 24 tools
+process and everything stays on one machine. `--http` serves the same tools
 over HTTP instead, so a client that cannot spawn a local process — a cloud
 coding session, another laptop — can reach this vault:
 
 ```bash
-npx -y virlow-mcp --http                 # loopback, random port
-npx -y virlow-mcp --http --port 8787     # pick the port
+npx -y virlow-mcp@latest --http                 # loopback, random port
+npx -y virlow-mcp@latest --http --port 8787     # pick the port
 ```
 
 It prints the URL and the path to a bearer token, generated on first run and
@@ -295,12 +329,12 @@ account cannot be reached, the tools refuse rather than assume consent.
 unregistered, so they do not appear in `tools/list` at all:
 
 ```bash
-npx -y virlow-mcp --no-memories
+npx -y virlow-mcp@latest --no-memories
 ```
 
 Use it when you want a connector that structurally cannot touch memories,
 regardless of the account setting. Notes tools, `unlock`, `lock`, and `status`
-are unaffected either way (18 tools instead of 23).
+are unaffected either way.
 
 ## Suggested agent rules
 

package/dist/cli.js

@@ -3859,7 +3859,8 @@ function buildServer(opts) {
   server.registerTool("status", {
     description: "Report whether the vault is currently locked or unlocked, and which account it's unlocked as. Call this after unlock to confirm the user finished the browser form, and before any memory/notes tool if you are unsure of the current lock state."
   }, wrap(async () => {
-    return textResult(JSON.stringify(vault.status()));
+    const notice = opts.updateNotice?.() ?? null;
+    return textResult(JSON.stringify(notice === null ? vault.status() : { ...vault.status(), update: notice }));
   }));
   const requireMemories = async () => {
     if (!vault.isUnlocked())
@@ -4518,8 +4519,9 @@ async function performUnlock(api, vault, creds) {
     vault.touch();
   };
 }
-function renderForm(nonce, error) {
+function renderForm(nonce, error, updateNotice) {
   const errorHtml = error ? `<p class="error">${escapeHtml(error)}</p>` : "";
+  const updateHtml = updateNotice ? `<p class="update">${escapeHtml(updateNotice)}</p>` : "";
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -4528,6 +4530,7 @@ function renderForm(nonce, error) {
 <style>
   body { font-family: system-ui, sans-serif; max-width: 420px; margin: 48px auto; padding: 0 16px; color: #1a1a1a; }
   h1 { font-size: 1.4rem; }
+  p.update { color: #555; font-size: 0.9rem; }
   label { display: block; margin-top: 12px; font-weight: 600; }
   input { width: 100%; padding: 8px; margin-top: 4px; box-sizing: border-box; font-size: 1rem; }
   button { margin-top: 20px; padding: 10px 16px; font-size: 1rem; cursor: pointer; }
@@ -4542,6 +4545,7 @@ function renderForm(nonce, error) {
   Virlow API. They are never seen by any AI model or logged.
 </p>
 ${errorHtml}
+${updateHtml}
 <form method="POST" action="/unlock?nonce=${encodeURIComponent(nonce)}" autocomplete="off">
   <label for="email">Email</label>
   <input type="email" id="email" name="email" autocomplete="off" required />
@@ -4686,7 +4690,7 @@ function startUnlockServer(api, vault, opts = {}) {
         harden(res);
         res.statusCode = 200;
         res.setHeader("content-type", "text/html; charset=utf-8");
-        res.end(renderForm(nonce));
+        res.end(renderForm(nonce, void 0, opts.updateNotice?.() ?? null));
         return;
       }
       if (req.method === "POST") {
@@ -4710,7 +4714,7 @@ function startUnlockServer(api, vault, opts = {}) {
           harden(res);
           res.statusCode = 200;
           res.setHeader("content-type", "text/html; charset=utf-8");
-          res.end(renderForm(nonce, message));
+          res.end(renderForm(nonce, message, opts.updateNotice?.() ?? null));
         }
         return;
       }
@@ -4742,25 +4746,30 @@ function startUnlockServer(api, vault, opts = {}) {
 }
 
 // src/version.ts
-var VERSION = true ? "3.81.0" : "dev";
+var VERSION = true ? "3.82.0" : "dev";
 
 // src/server.ts
 function defaultEmbeddingCacheDir() {
   return path3.join(os.homedir(), ".virlow-mcp", "cache");
 }
-var localBrowserUnlock = {
-  description: "Open a local browser window where the USER signs in and enters their Virlow master password. This tool returns immediately once the browser is opened \u2014 it does NOT wait for the user to finish. Call the status tool afterward to confirm the vault unlocked. Never ask the user for their password or account credentials yourself, and never relay a password through this tool or any other \u2014 credentials are entered only in the browser form and never seen by any AI model.",
-  async begin({ api, vault }) {
-    const { url } = await startUnlockServer(api, vault, { openBrowser: true });
-    return `Browser opened at ${url}. Complete the unlock form there, then run status to confirm.`;
-  }
-};
+function localBrowserUnlock(updateNotice) {
+  return {
+    description: "Open a local browser window where the USER signs in and enters their Virlow master password. This tool returns immediately once the browser is opened \u2014 it does NOT wait for the user to finish. Call the status tool afterward to confirm the vault unlocked. Never ask the user for their password or account credentials yourself, and never relay a password through this tool or any other \u2014 credentials are entered only in the browser form and never seen by any AI model.",
+    async begin({ api, vault }) {
+      const { url } = await startUnlockServer(api, vault, {
+        openBrowser: true,
+        ...updateNotice ? { updateNotice } : {}
+      });
+      return `Browser opened at ${url}. Complete the unlock form there, then run status to confirm.`;
+    }
+  };
+}
 function withLocalDefaults(opts) {
   const { embeddingCacheDir, ...rest } = opts;
   return {
     ...rest,
     serverInfo: { name: "virlow-mcp", version: VERSION },
-    unlock: localBrowserUnlock,
+    unlock: localBrowserUnlock(opts.updateNotice),
     createEmbeddingCache: (userId) => new EmbeddingCache({
       dir: embeddingCacheDir ?? defaultEmbeddingCacheDir(),
       userId,
@@ -4828,6 +4837,63 @@ async function runConnectBridge(opts) {
   };
 }
 
+// src/update-check.ts
+var REGISTRY_URL = "https://registry.npmjs.org/virlow-mcp/latest";
+var TIMEOUT_MS = 3e3;
+var OPT_OUT_ENV = "VIRLOW_MCP_NO_UPDATE_CHECK";
+function parseVersion(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function isNewer(candidate, current) {
+  const a = parseVersion(candidate);
+  const b = parseVersion(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}
+function optedOut(env) {
+  const v = env[OPT_OUT_ENV];
+  return v === "1" || v === "true";
+}
+function updateCheckApplies(argv, env) {
+  if (optedOut(env)) return false;
+  if (argv.includes("--version") || argv.includes("-v")) return false;
+  if (argv.some((a) => a === "--connect" || a.startsWith("--connect="))) return false;
+  return true;
+}
+function startUpdateCheck(opts) {
+  const env = opts.env ?? process.env;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const log = opts.log ?? ((line) => process.stderr.write(`${line}
+`));
+  let text = null;
+  if (optedOut(env)) return { notice: () => null, done: Promise.resolve() };
+  const done = (async () => {
+    try {
+      const res = await fetchImpl(REGISTRY_URL, {
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+        headers: { accept: "application/json" }
+      });
+      if (!res.ok) return;
+      const body = await res.json();
+      const latest = body.version;
+      if (typeof latest === "string" && isNewer(latest, opts.current)) {
+        text = `virlow-mcp ${latest} is available (you are running ${opts.current}). Restart your AI client to update. If your MCP config runs plain virlow-mcp, change it to virlow-mcp@latest.`;
+      }
+    } catch (err) {
+      const why = err instanceof Error ? err.message : String(err);
+      try {
+        log(`virlow-mcp: update check skipped: ${why.replace(/\s+/g, " ")}`);
+      } catch {
+      }
+    }
+  })();
+  return { notice: () => text, done };
+}
+
 // src/cli.ts
 function flagValue(name) {
   const prefix = `--${name}=`;
@@ -4860,7 +4926,15 @@ async function main() {
   const http2 = process.argv.includes("--http");
   const host = flagValue("host") ?? "127.0.0.1";
   const fileAccess = localFileAccess({ http: http2, host });
-  const serverOpts = { apiUrl, modelCacheDir, embeddingCacheDir, memoriesEnabled, fileAccess };
+  const updates = updateCheckApplies(process.argv, process.env) ? startUpdateCheck({ current: VERSION }) : null;
+  const serverOpts = {
+    apiUrl,
+    modelCacheDir,
+    embeddingCacheDir,
+    memoriesEnabled,
+    fileAccess,
+    ...updates ? { updateNotice: () => updates.notice() } : {}
+  };
   const services = createServices2(serverOpts);
   const { server } = buildServer2({ ...serverOpts, services });
   if (http2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virlow-mcp",
-  "version": "3.81.0",
+  "version": "3.82.0",
   "description": "Local MCP server for Virlow Secure Notes: end-to-end-encrypted AI memories and notes for Cursor, Claude, Codex, and any MCP client.",
   "license": "UNLICENSED",
   "type": "module",
@@ -34,9 +34,9 @@
     "esbuild": "^0.25.0",
     "typescript": "^5.8.0",
     "vitest": "^3.0.0",
-    "@batalabs/virlow-crypto": "3.81.0",
-    "@batalabs/virlow-mcp-core": "3.81.0",
-    "@batalabs/virlow-memory": "3.81.0"
+    "@batalabs/virlow-crypto": "3.82.0",
+    "@batalabs/virlow-memory": "3.82.0",
+    "@batalabs/virlow-mcp-core": "3.82.0"
   },
   "scripts": {
     "build": "node build.mjs",