filamental-mcp 0.2.2 → 0.2.3

package/README.md

@@ -120,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

@@ -58,6 +58,17 @@ function resolveDbPath(vaultPath, explicitDb) {
         return appDbPath;
     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);
@@ -66,7 +77,15 @@ function openVault(vaultPath, explicitDb) {
             `Open this vault in Filamental at least once so the SQLite index is initialised.`);
     }
     const db = new Database(dbPath);
-    return { vaultPath, db };
+    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() {
@@ -129,7 +148,7 @@ async function main() {
         });
     }
     // Create the MCP server — it reads activeState on each tool call via the getter
-    const server = createServer(() => activeState.db, () => activeState.vaultPath);
+    const server = createServer(() => activeState.db, () => activeState.vaultPath, () => activeState.schemaHint);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/server.js

@@ -851,8 +851,8 @@ function toolDeleteEdge(db, args) {
     return { deleted: true, edge_id: edgeId };
 }
 // ── Server factory ────────────────────────────────────────────────────────────
-export function createServer(getDb, getVaultPath) {
-    const server = new Server({ name: 'filamental', version: '0.2.1' }, { 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;
@@ -909,7 +909,10 @@ export function createServer(getDb, getVaultPath) {
         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.2",
+  "version": "0.2.3",
   "description": "MCP server exposing your Filamental vault to AI assistants (Claude, Claude Code, etc.)",
   "type": "module",
   "main": "dist/index.js",