filamental-mcp 0.2.1 → 0.2.3

package/README.md

@@ -23,7 +23,7 @@ The easiest way to connect is through the app:
 2. Click **Connect to Claude Desktop**
 3. Restart Claude Desktop
 
-Filamental resolves all paths automatically and writes the correct entry to `claude_desktop_config.json`.
+Filamental resolves all paths automatically. The MCP follows whichever vault you have open — no restart needed when you switch worlds.
 
 ---
 
@@ -47,16 +47,14 @@ Then add to your `claude_desktop_config.json`:
       "command": "node",
       "args": [
         "--no-warnings",
-        "/absolute/path/to/node_modules/filamental-mcp/dist/index.js",
-        "--vault",
-        "/absolute/path/to/your/vault"
+        "/absolute/path/to/node_modules/filamental-mcp/dist/index.js"
       ]
     }
   }
 }
 ```
 
-> Vault path must be absolute. Claude Desktop launches the server from a varying working directory, so relative paths are not reliable.
+No `--vault` argument needed. The server reads the active vault from Filamental automatically and reconnects when you switch worlds. To pin to a specific vault (e.g. for testing), pass `--vault <absolute-path>` explicitly.
 
 ### Claude Code
 
@@ -122,10 +120,19 @@ This server opens that SQLite index read-write. Read tools query it directly. Wr
 
 ---
 
+## Compatibility
+
+| filamental-mcp | Filamental app | DB schema |
+|---|---|---|
+| 0.2.x | 0.2.x | v5 |
+
+If the versions are mismatched the server exits immediately with a clear message telling you which side to update.
+
+---
+
 ## Known limitations
 
 - The pre-built binary (`better-sqlite3`) is Windows x64 only. Other platforms require building from source.
-- The server must be restarted if you change the active vault in Filamental.
 - Auto-config via Filamental Settings has been tested on Windows. macOS path resolution is included but untested.
 
 ---

package/dist/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // Filamental MCP Server — index.ts
-// Entry point: parse CLI args, resolve vault DB path, open DB, connect transport.
-import { existsSync } from 'fs';
+// Entry point: resolve vault path (from --vault arg or active-vault file),
+// open DB, connect transport. Re-connects automatically when vault changes.
+import { existsSync, readFileSync, watchFile } from 'fs';
 import { homedir } from 'os';
 import { join, resolve } from 'path';
 import Database from 'better-sqlite3';
@@ -13,12 +14,32 @@ function parseArgs(argv) {
     for (let i = 0; i < argv.length - 1; i++) {
         if (argv[i].startsWith('--')) {
             result[argv[i].slice(2)] = argv[i + 1];
-            i++; // consume the value
+            i++;
         }
     }
     return result;
 }
-// ── Vault hash (mirrors Rust vault_hash fn — FNV-1a 32-bit) ──────────────────
+// ── App config dir (mirrors Tauri's app_config_dir for "com.filamental.app") ──
+function appConfigDir() {
+    if (process.platform === 'win32') {
+        return join(process.env['APPDATA'] ?? homedir(), 'com.filamental.app');
+    }
+    else if (process.platform === 'darwin') {
+        return join(homedir(), 'Library', 'Application Support', 'com.filamental.app');
+    }
+    else {
+        return join(process.env['XDG_CONFIG_HOME'] ?? join(homedir(), '.config'), 'com.filamental.app');
+    }
+}
+// ── Read the active vault path written by Filamental on every vault open ──────
+function readActiveVault() {
+    const filePath = join(appConfigDir(), 'active-vault');
+    if (!existsSync(filePath))
+        return null;
+    const content = readFileSync(filePath, 'utf-8').trim();
+    return content.length > 0 ? content : null;
+}
+// ── Vault hash (FNV-1a 32-bit — mirrors Rust vault_hash fn) ──────────────────
 function vaultHash(vaultPath) {
     let hash = 2_166_136_261;
     const bytes = Buffer.from(vaultPath, 'utf-8');
@@ -29,61 +50,105 @@ function vaultHash(vaultPath) {
     return `vault-${hash.toString(16).padStart(8, '0')}`;
 }
 // ── DB path resolution ────────────────────────────────────────────────────────
-//
-// Filamental stores its SQLite index in the OS app-config directory, NOT inside
-// the vault folder (so cloud-synced vaults don't re-index on every machine).
-// Path: <app_config_dir>/vaults/<vault-hash>/filamental.db
-//
-// If --db is supplied it overrides everything (useful for testing).
 function resolveDbPath(vaultPath, explicitDb) {
     if (explicitDb)
         return resolve(explicitDb);
-    // Tauri's app_config_dir for "com.filamental.app"
-    let appConfigDir;
-    if (process.platform === 'win32') {
-        appConfigDir = join(process.env['APPDATA'] ?? homedir(), 'com.filamental.app');
-    }
-    else if (process.platform === 'darwin') {
-        appConfigDir = join(homedir(), 'Library', 'Application Support', 'com.filamental.app');
-    }
-    else {
-        // Linux / XDG
-        appConfigDir = join(process.env['XDG_CONFIG_HOME'] ?? join(homedir(), '.config'), 'com.filamental.app');
-    }
-    const appDbPath = join(appConfigDir, 'vaults', vaultHash(vaultPath), 'filamental.db');
+    const appDbPath = join(appConfigDir(), 'vaults', vaultHash(vaultPath), 'filamental.db');
     if (existsSync(appDbPath))
         return appDbPath;
-    // Fallback: vault-local path (dev builds or future embedded mode)
     return join(vaultPath, '.filamental', 'filamental.db');
 }
+// ── Schema compatibility ──────────────────────────────────────────────────────
+// Must match SCHEMA_VERSION in src-tauri/src/index.rs
+const SUPPORTED_SCHEMA_VERSION = 5;
+function schemaVersionHint(detected) {
+    if (detected > SUPPORTED_SCHEMA_VERSION) {
+        return (`Version mismatch: your Filamental app uses schema v${detected} but this MCP only supports v${SUPPORTED_SCHEMA_VERSION}. ` +
+            `To fix:\n  1. Open a terminal\n  2. Run: npm update -g filamental-mcp\n  3. Restart Claude Desktop`);
+    }
+    return (`Version mismatch: this MCP expects schema v${SUPPORTED_SCHEMA_VERSION} but detected v${detected}. ` +
+        `To fix:\n  1. Download the latest Filamental app at https://filamental.app\n  2. Install it\n  3. Restart Claude Desktop`);
+}
+let activeState = null;
+function openVault(vaultPath, explicitDb) {
+    const dbPath = resolveDbPath(vaultPath, explicitDb);
+    if (!existsSync(dbPath)) {
+        throw new Error(`Filamental database not found at ${dbPath}.\n` +
+            `Open this vault in Filamental at least once so the SQLite index is initialised.`);
+    }
+    const db = new Database(dbPath);
+    const row = db.prepare('PRAGMA user_version').get();
+    const schemaVersion = row.user_version;
+    let schemaHint = null;
+    if (schemaVersion !== SUPPORTED_SCHEMA_VERSION) {
+        schemaHint = schemaVersionHint(schemaVersion);
+        // Log to stderr only — user never sees this in normal operation
+        console.error(`[filamental-mcp] warning: ${schemaHint}`);
+    }
+    return { vaultPath, db, schemaHint };
+}
 // ── Main ──────────────────────────────────────────────────────────────────────
 async function main() {
     const args = parseArgs(process.argv.slice(2));
-    const rawVaultArg = args['vault'];
-    if (!rawVaultArg) {
-        console.error('Error: --vault <path> is required');
-        console.error('');
-        console.error('Usage:');
-        console.error('  node --no-warnings dist/index.js --vault /path/to/your/vault');
-        console.error('  node --no-warnings dist/index.js --vault /path/to/vault --db /explicit/db/path');
-        process.exit(1);
+    const explicitVault = args['vault'] ? resolve(args['vault']) : undefined;
+    const explicitDb = args['db'] ? resolve(args['db']) : undefined;
+    // Resolve the initial vault path: explicit arg → active-vault file
+    let initialVaultPath;
+    if (explicitVault) {
+        if (!existsSync(explicitVault)) {
+            console.error(`Error: vault path does not exist: ${explicitVault}`);
+            process.exit(1);
+        }
+        initialVaultPath = explicitVault;
     }
-    const vaultPath = resolve(rawVaultArg);
-    if (!existsSync(vaultPath)) {
-        console.error(`Error: vault path does not exist: ${vaultPath}`);
-        process.exit(1);
+    else {
+        const active = readActiveVault();
+        if (!active) {
+            console.error('Error: no vault path supplied and no active-vault file found.');
+            console.error('');
+            console.error('Either:');
+            console.error('  1. Open a vault in Filamental (it writes the active-vault file automatically), or');
+            console.error('  2. Pass --vault <path> explicitly.');
+            process.exit(1);
+        }
+        if (!existsSync(active)) {
+            console.error(`Error: active vault path does not exist: ${active}`);
+            process.exit(1);
+        }
+        initialVaultPath = active;
     }
-    const dbPath = resolveDbPath(vaultPath, args['db']);
-    if (!existsSync(dbPath)) {
-        console.error(`Error: Filamental database not found at:`);
-        console.error(`  ${dbPath}`);
-        console.error('');
-        console.error('Make sure this vault has been opened in Filamental at least once');
-        console.error('so that the SQLite index is initialised.');
+    // Open the initial DB connection
+    try {
+        activeState = openVault(initialVaultPath, explicitDb);
+    }
+    catch (err) {
+        console.error(`Error: ${err}`);
         process.exit(1);
     }
-    const db = new Database(dbPath);
-    const server = createServer(db, vaultPath);
+    // Watch the active-vault file for changes (user switched worlds in Filamental).
+    // Only active when --vault was NOT explicitly supplied — explicit arg is pinned.
+    if (!explicitVault) {
+        const activeVaultFile = join(appConfigDir(), 'active-vault');
+        watchFile(activeVaultFile, { interval: 2000 }, () => {
+            const newPath = readActiveVault();
+            if (!newPath || newPath === activeState?.vaultPath)
+                return;
+            if (!existsSync(newPath))
+                return;
+            try {
+                const next = openVault(newPath);
+                activeState?.db.close();
+                activeState = next;
+                // Notify via stderr so Claude Desktop can surface the switch if desired
+                console.error(`[filamental-mcp] vault switched → ${newPath}`);
+            }
+            catch {
+                // Keep the old connection alive if the new vault's DB isn't ready yet
+            }
+        });
+    }
+    // Create the MCP server — it reads activeState on each tool call via the getter
+    const server = createServer(() => activeState.db, () => activeState.vaultPath, () => activeState.schemaHint);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/server.js

@@ -851,12 +851,15 @@ function toolDeleteEdge(db, args) {
     return { deleted: true, edge_id: edgeId };
 }
 // ── Server factory ────────────────────────────────────────────────────────────
-export function createServer(db, vaultPath) {
-    const server = new Server({ name: 'filamental', version: '0.2.0' }, { capabilities: { tools: {} } });
+export function createServer(getDb, getVaultPath, getSchemaHint) {
+    const server = new Server({ name: 'filamental', version: '0.2.2' }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args = {} } = request.params;
         const a = args;
+        // Resolve db and vaultPath fresh on every call so vault switches are transparent
+        const db = getDb();
+        const vaultPath = getVaultPath();
         try {
             let result;
             switch (name) {
@@ -906,7 +909,10 @@ export function createServer(db, vaultPath) {
         catch (err) {
             if (err instanceof McpError)
                 throw err;
-            throw new McpError(ErrorCode.InternalError, String(err));
+            // Append version hint only if there is one — keeps the message clean when versions match
+            const hint = getSchemaHint();
+            const base = String(err);
+            throw new McpError(ErrorCode.InternalError, hint ? `${base}\n\n${hint}` : base);
         }
     });
     return server;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filamental-mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "MCP server exposing your Filamental vault to AI assistants (Claude, Claude Code, etc.)",
   "type": "module",
   "main": "dist/index.js",