engram-mcp-server 1.2.0 → 1.2.2

package/README.md

@@ -210,209 +210,128 @@ See total sessions, changes, decisions, most-changed files, layer distribution,
 
 ---
 
-## Installation
+## Quickstart
 
-### Prerequisites
-- Node.js 18+ installed
-- npm or yarn
+Engram is published to the npm registry. **You do not need to download or compile any code.**
 
-### Setup
+As long as you have Node.js installed, your IDE will download and run the latest version of Engram automatically using `npx`.
 
-```bash
-# Clone the repository
-git clone git@github.com:keggan-std/Engram.git
-cd Engram
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# (Optional) Install git hooks for automatic change tracking
-npm run install-hooks
-```
+### Option 1: The Magic Installer (Zero Config)
 
-### Add to Your IDE — One Command
-
-Run this after building to automatically add Engram to all supported IDEs detected on your machine:
+Run this single command in your terminal. It will automatically detect your IDEs (Cursor, VS Code, Visual Studio, Cline, Windsurf, Antigravity) and inject the correct configuration for you:
 
 ```bash
-npm run install-mcp
+npx -y engram-mcp-server --install
 ```
 
-This detects and updates the MCP config for **Antigravity IDE, Cursor, VS Code, Cline, and Windsurf** — no manual path editing required. Just restart your IDE after.
-
-To preview which IDEs were detected before installing:
+*(You can also run `npx -y engram-mcp-server --list` to see what IDEs it detects before installing)*
 
-```bash
-npm run install-mcp:list
-```
-
-To add to a specific IDE only:
-
-```bash
-node scripts/install-mcp.js --ide antigravity
-node scripts/install-mcp.js --ide cursor
-node scripts/install-mcp.js --ide vscode
-```
-
-### Verify it works
-
-```bash
-# Test with MCP Inspector
-npm run inspect
-```
+Restart your IDE, and Engram is ready!
 
 ---
 
-## Configuration
-
-> [!TIP]
-> **Quickest way**: Run `npm run install-mcp` after building — it auto-detects your IDEs and writes the config for you. Restart your IDE after.
+### Option 2: Manual Configuration
 
 If you prefer to configure manually, find your IDE below and paste the config snippet.
 
-### Antigravity IDE
-
-1. Click the **`...`** menu at the top of the Agent panel
-2. Select **MCP Servers → Manage MCP Servers**
-3. Click **"View raw config"**
-4. Add the `engram` block inside `"mcpServers"`:
-
+#### Cline / Roo Code
+In the extension settings → MCP Servers:
 ```json
 {
   "mcpServers": {
     "engram": {
-      "command": "node",
-      "args": ["/absolute/path/to/Engram/dist/index.js"],
-      "env": {}
+      "command": "npx",
+      "args": ["-y", "engram-mcp-server"]
     }
   }
 }
 ```
 
-5. Save and **restart Antigravity IDE**
-
-> Replace `/absolute/path/to/Engram/dist/index.js` with the actual path on your machine — or just run `npm run install-mcp` and it's done automatically.
-
-### Claude Code
-
-Add to `~/.claude.json` or your project's `.claude/settings.json`:
+#### Cursor
+1. Go to **Cursor Settings** → **Features** → **MCP**
+2. Click **+ Add new MCP server**
+3. Select **command** type
+4. Name: `engram`
+5. Command: `npx -y engram-mcp-server`
 
+#### Claude Desktop
+Add to your `claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
     "engram": {
-      "command": "node",
-      "args": ["/absolute/path/to/Engram/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "engram-mcp-server"]
     }
   }
 }
 ```
 
-### Cursor
-
-In Cursor Settings → Features → MCP Servers, add:
-
-```json
-{
-  "engram": {
-    "command": "node",
-    "args": ["/absolute/path/to/Engram/dist/index.js"]
-  }
-}
-```
-
-### VS Code (with GitHub Copilot)
-
+#### VS Code (with GitHub Copilot)
 Create `.vscode/mcp.json` in your project root:
-
 ```json
 {
   "servers": {
     "engram": {
       "type": "stdio",
-      "command": "node",
-      "args": ["/absolute/path/to/Engram/dist/index.js"]
-    }
-  }
-}
-```
-
-Or add to your user `settings.json` to make Engram available across all workspaces:
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "engram": {
-        "type": "stdio",
-        "command": "node",
-        "args": ["/absolute/path/to/Engram/dist/index.js"]
-      }
+      "command": "npx",
+      "args": ["-y", "engram-mcp-server"]
     }
   }
 }
 ```
+Or add to your user `settings.json` to make it available across all workspaces.
 
-### Visual Studio 2022/2026
-
+#### Visual Studio 2022/2026
 Create `.vs/mcp.json` in your solution root:
-
 ```json
 {
   "servers": {
     "engram": {
       "type": "stdio",
-      "command": "node",
-      "args": ["/absolute/path/to/Engram/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "engram-mcp-server"]
     }
   }
 }
 ```
+Or create a global config at `%USERPROFILE%\.mcp.json`. Note: Server names in Visual Studio must not contain spaces.
 
-Or create a global config at `%USERPROFILE%\.mcp.json` (makes Engram available in all solutions):
-
+#### Windsurf
+In Settings → MCP:
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "engram": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["/absolute/path/to/Engram/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "engram-mcp-server"]
     }
   }
 }
 ```
 
-> **Note:** Server names in Visual Studio must not contain spaces.
+---
+
+### 2. Auto-Updates
+Because the configuration uses `npx -y engram-mcp-server`, your agent will **automatically fetch the latest version** of Engram from the npm registry every time it starts. You never have to manually update or run `git pull` again!
 
-### Cline / Roo Code
+---
 
-In the Cline extension settings → MCP Servers:
+### 3. Optional: Build from Source
+If you prefer to run Engram locally instead of fetching it via `npx` (e.g. for contributing to the repository):
 
+```bash
+git clone https://github.com/keggan-std/Engram.git
+cd Engram
+npm install
+npm run build
+```
+Then, point your MCP configuration to the local `dist/index.js` file instead of using `npx`:
 ```json
 {
   "engram": {
     "command": "node",
-    "args": ["/absolute/path/to/Engram/dist/index.js"],
-    "disabled": false
-  }
-}
-```
-
-### Windsurf
-
-In Settings → MCP:
-
-```json
-{
-  "mcpServers": {
-    "engram": {
-      "command": "node",
-      "args": ["/absolute/path/to/Engram/dist/index.js"]
-    }
+    "args": ["/absolute/path/to/Engram/dist/index.js"]
   }
 }
 ```
@@ -473,15 +392,14 @@ New machine:
 
 ---
 
-## Migration from v1.0.0
+## Migration from v1.0.0 (sql.js)
+
+If you're upgrading from the original `sql.js` version (v1.0.0) to native SQLite:
 
-If you're upgrading from the original sql.js version:
+1. Follow the **Quickstart** above to update your agent's MCP config to use `npx -y engram-mcp-server`
+2. Restart your IDE
 
-1. **Your existing `.engram/memory.db` files are fully compatible** — the SQLite format is the same
-2. **Run `npm install` to get the new dependencies** (better-sqlite3 replaces sql.js)
-3. **Run `npm run build`**
-4. The migration system will automatically upgrade your schema on first startup — adding FTS5 indexes, config table, and composite indexes
-5. Your existing data is preserved and immediately searchable via FTS5
+**That's it.** Your existing `.engram/memory.db` files are fully compatible. The migration system will automatically upgrade your schema on first startup — adding FTS5 indexes, the config table, composite indexes, and the new scheduled events tables. Your existing data is preserved and instantly searchable.
 
 ---
 

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 export declare const SERVER_NAME = "engram-mcp-server";
-export declare const SERVER_VERSION = "1.2.0";
+export declare const SERVER_VERSION = "1.2.2";
 export declare const TOOL_PREFIX = "engram";
 export declare const DB_DIR_NAME = ".engram";
 export declare const DB_FILE_NAME = "memory.db";

package/dist/constants.js

@@ -2,7 +2,7 @@
 // Engram MCP Server — Constants
 // ============================================================================
 export const SERVER_NAME = "engram-mcp-server";
-export const SERVER_VERSION = "1.2.0";
+export const SERVER_VERSION = "1.2.2";
 export const TOOL_PREFIX = "engram";
 // Database
 export const DB_DIR_NAME = ".engram";

package/dist/index.js

@@ -17,6 +17,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
 import { initDatabase } from "./database.js";
 import { findProjectRoot } from "./utils.js";
+import { runInstaller } from "./installer.js";
 // Tool registrations
 import { registerSessionTools } from "./tools/sessions.js";
 import { registerMemoryTools } from "./tools/memory.js";
@@ -26,6 +27,12 @@ import { registerMaintenanceTools } from "./tools/maintenance.js";
 import { registerSchedulerTools } from "./tools/scheduler.js";
 // ─── Initialize ───────────────────────────────────────────────────────
 async function main() {
+    const args = process.argv.slice(2);
+    // ─── Auto-Installer ───────────────────────────────────────────────────
+    if (args.includes("install") || args.includes("--install") || args.includes("--list")) {
+        runInstaller(args);
+        return;
+    }
     // Detect project root
     const projectRoot = findProjectRoot();
     console.error(`[Engram] Project root: ${projectRoot}`);

package/dist/installer.d.ts

@@ -0,0 +1,2 @@
+export declare function runInstaller(args: string[]): void;
+//# sourceMappingURL=installer.d.ts.map

package/dist/installer.js

@@ -0,0 +1,141 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+const HOME = os.homedir();
+const APPDATA = process.env.APPDATA || path.join(HOME, ".config");
+// ─── IDE Config Locations ────────────────────────────────────────────
+const IDE_CONFIGS = {
+    antigravity: {
+        name: "Antigravity IDE",
+        paths: [
+            path.join(HOME, ".gemini", "antigravity", "mcp_config.json"),
+        ],
+        format: "mcpServers",
+    },
+    cursor: {
+        name: "Cursor",
+        paths: [
+            path.join(HOME, ".cursor", "mcp.json"),
+            path.join(APPDATA, "Cursor", "mcp.json"),
+        ],
+        format: "mcpServers",
+    },
+    vscode: {
+        name: "VS Code (Copilot)",
+        paths: [
+            path.join(APPDATA, "Code", "User", "mcp.json"),
+            path.join(HOME, ".vscode", "mcp.json"),
+        ],
+        format: "servers",
+    },
+    cline: {
+        name: "Cline / Roo Code",
+        paths: [
+            path.join(APPDATA, "Code", "User", "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json"),
+            path.join(HOME, ".cline", "mcp_settings.json"),
+        ],
+        format: "mcpServers",
+    },
+    windsurf: {
+        name: "Windsurf",
+        paths: [
+            path.join(HOME, ".codeium", "windsurf", "mcp_config.json"),
+            path.join(APPDATA, "Windsurf", "mcp.json"),
+        ],
+        format: "mcpServers",
+    },
+    visualstudio: {
+        name: "Visual Studio 2022",
+        paths: [
+            path.join(HOME, ".mcp.json"), // Global config for Visual Studio
+        ],
+        format: "servers",
+    },
+};
+// ─── Engram Entry ────────────────────────────────────────────────────
+function makeEngramEntry(format) {
+    const entry = {
+        command: "npx",
+        args: ["-y", "engram-mcp-server"],
+    };
+    if (format === "servers") {
+        // VS Code uses a slightly different shape
+        return { type: "stdio", ...entry };
+    }
+    return entry;
+}
+// ─── Config Manipulation ─────────────────────────────────────────────
+function readJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function addToConfig(configPath, format) {
+    let config = readJson(configPath) || {};
+    const key = format; // "mcpServers" or "servers"
+    if (!config[key])
+        config[key] = {};
+    if (config[key].engram) {
+        // Already exists — update to use npx
+        config[key].engram = makeEngramEntry(format);
+        writeJson(configPath, config);
+        return "updated";
+    }
+    config[key].engram = makeEngramEntry(format);
+    writeJson(configPath, config);
+    return "added";
+}
+// ─── Main ────────────────────────────────────────────────────────────
+export function runInstaller(args) {
+    if (args.includes("--list")) {
+        console.log("\nEngram can be auto-installed into these IDEs:\n");
+        for (const [id, ide] of Object.entries(IDE_CONFIGS)) {
+            const found = ide.paths.find((p) => fs.existsSync(p) || fs.existsSync(path.dirname(p)));
+            console.log(`  ${id.padEnd(15)} ${ide.name} ${found ? "✅ detected" : "❌ not found"}`);
+        }
+        process.exit(0);
+    }
+    // Specific IDE requested?
+    const ideFlagIdx = args.indexOf("--ide");
+    const targetIde = ideFlagIdx >= 0 ? args[ideFlagIdx + 1] : null;
+    const idesToProcess = targetIde
+        ? (IDE_CONFIGS[targetIde] ? { [targetIde]: IDE_CONFIGS[targetIde] } : null)
+        : IDE_CONFIGS;
+    if (!idesToProcess) {
+        console.error(`Unknown IDE: "${targetIde}". Options: ${Object.keys(IDE_CONFIGS).join(", ")}`);
+        process.exit(1);
+    }
+    console.log("\n🧠 Engram MCP Installer\n");
+    let installed = 0;
+    for (const [id, ide] of Object.entries(idesToProcess)) {
+        const configPath = ide.paths.find((p) => fs.existsSync(p)) || ide.paths[0];
+        try {
+            const result = addToConfig(configPath, ide.format);
+            console.log(`\n   ✅ ${ide.name}`);
+            console.log(`      Config: ${configPath}`);
+            console.log(`      Status: ${result === "added" ? "Engram added" : "Engram config updated to use npx"}`);
+            installed++;
+        }
+        catch (e) {
+            console.log(`\n   ⚠️  ${ide.name}`);
+            console.log(`      Could not write to: ${configPath}`);
+            console.log(`      Reason: ${e.message}`);
+        }
+    }
+    if (installed === 0) {
+        console.log("\n   No supported IDEs were found on this machine.");
+        console.log("   Run 'npx -y engram-mcp-server --list' to see what was detected.\n");
+    }
+    else {
+        console.log(`\n✅ Done! Engram configured in ${installed} IDE(s).`);
+        console.log("   Restart your IDE(s) to load Engram.\n");
+    }
+}
+//# sourceMappingURL=installer.js.map

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "engram-mcp-server",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Engram — Persistent Memory Cortex for AI coding agents. Gives agents session continuity, change tracking, decision logging, and project intelligence across sessions.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "engram": "dist/index.js"
+    "engram": "dist/index.js",
+    "engram-mcp-server": "dist/index.js"
   },
   "scripts": {
     "build": "tsc",

package/src/constants.ts

@@ -3,7 +3,7 @@
 // ============================================================================
 
 export const SERVER_NAME = "engram-mcp-server";
-export const SERVER_VERSION = "1.2.0";
+export const SERVER_VERSION = "1.2.2";
 export const TOOL_PREFIX = "engram";
 
 // Database

package/src/index.ts

@@ -18,6 +18,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
 import { initDatabase, getProjectRoot } from "./database.js";
 import { findProjectRoot } from "./utils.js";
+import { runInstaller } from "./installer.js";
 
 // Tool registrations
 import { registerSessionTools } from "./tools/sessions.js";
@@ -30,6 +31,14 @@ import { registerSchedulerTools } from "./tools/scheduler.js";
 // ─── Initialize ───────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  // ─── Auto-Installer ───────────────────────────────────────────────────
+  if (args.includes("install") || args.includes("--install") || args.includes("--list")) {
+    runInstaller(args);
+    return;
+  }
+
   // Detect project root
   const projectRoot = findProjectRoot();
   console.error(`[Engram] Project root: ${projectRoot}`);

package/src/installer.ts

@@ -0,0 +1,160 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const HOME = os.homedir();
+const APPDATA = process.env.APPDATA || path.join(HOME, ".config");
+
+// ─── IDE Config Locations ────────────────────────────────────────────
+
+const IDE_CONFIGS: Record<string, any> = {
+    antigravity: {
+        name: "Antigravity IDE",
+        paths: [
+            path.join(HOME, ".gemini", "antigravity", "mcp_config.json"),
+        ],
+        format: "mcpServers",
+    },
+    cursor: {
+        name: "Cursor",
+        paths: [
+            path.join(HOME, ".cursor", "mcp.json"),
+            path.join(APPDATA, "Cursor", "mcp.json"),
+        ],
+        format: "mcpServers",
+    },
+    vscode: {
+        name: "VS Code (Copilot)",
+        paths: [
+            path.join(APPDATA, "Code", "User", "mcp.json"),
+            path.join(HOME, ".vscode", "mcp.json"),
+        ],
+        format: "servers",
+    },
+    cline: {
+        name: "Cline / Roo Code",
+        paths: [
+            path.join(APPDATA, "Code", "User", "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json"),
+            path.join(HOME, ".cline", "mcp_settings.json"),
+        ],
+        format: "mcpServers",
+    },
+    windsurf: {
+        name: "Windsurf",
+        paths: [
+            path.join(HOME, ".codeium", "windsurf", "mcp_config.json"),
+            path.join(APPDATA, "Windsurf", "mcp.json"),
+        ],
+        format: "mcpServers",
+    },
+    visualstudio: {
+        name: "Visual Studio 2022",
+        paths: [
+            path.join(HOME, ".mcp.json"), // Global config for Visual Studio
+        ],
+        format: "servers",
+    },
+};
+
+// ─── Engram Entry ────────────────────────────────────────────────────
+
+function makeEngramEntry(format: string) {
+    const entry = {
+        command: "npx",
+        args: ["-y", "engram-mcp-server"],
+    };
+
+    if (format === "servers") {
+        // VS Code uses a slightly different shape
+        return { type: "stdio", ...entry };
+    }
+
+    return entry;
+}
+
+// ─── Config Manipulation ─────────────────────────────────────────────
+
+function readJson(filePath: string) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    } catch {
+        return null;
+    }
+}
+
+function writeJson(filePath: string, data: any) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+function addToConfig(configPath: string, format: string) {
+    let config = readJson(configPath) || {};
+    const key = format; // "mcpServers" or "servers"
+
+    if (!config[key]) config[key] = {};
+
+    if (config[key].engram) {
+        // Already exists — update to use npx
+        config[key].engram = makeEngramEntry(format);
+        writeJson(configPath, config);
+        return "updated";
+    }
+
+    config[key].engram = makeEngramEntry(format);
+    writeJson(configPath, config);
+    return "added";
+}
+
+// ─── Main ────────────────────────────────────────────────────────────
+
+export function runInstaller(args: string[]) {
+    if (args.includes("--list")) {
+        console.log("\nEngram can be auto-installed into these IDEs:\n");
+        for (const [id, ide] of Object.entries(IDE_CONFIGS)) {
+            const found = ide.paths.find((p: string) => fs.existsSync(p) || fs.existsSync(path.dirname(p)));
+            console.log(`  ${id.padEnd(15)} ${ide.name} ${found ? "✅ detected" : "❌ not found"}`);
+        }
+        process.exit(0);
+    }
+
+    // Specific IDE requested?
+    const ideFlagIdx = args.indexOf("--ide");
+    const targetIde = ideFlagIdx >= 0 ? args[ideFlagIdx + 1] : null;
+
+    const idesToProcess = targetIde
+        ? (IDE_CONFIGS[targetIde] ? { [targetIde]: IDE_CONFIGS[targetIde] } : null)
+        : IDE_CONFIGS;
+
+    if (!idesToProcess) {
+        console.error(`Unknown IDE: "${targetIde}". Options: ${Object.keys(IDE_CONFIGS).join(", ")}`);
+        process.exit(1);
+    }
+
+    console.log("\n🧠 Engram MCP Installer\n");
+
+    let installed = 0;
+
+    for (const [id, ide] of Object.entries(idesToProcess)) {
+        const configPath = ide.paths.find((p: string) => fs.existsSync(p)) || ide.paths[0];
+
+        try {
+            const result = addToConfig(configPath, ide.format);
+            console.log(`\n   ✅ ${ide.name}`);
+            console.log(`      Config: ${configPath}`);
+            console.log(`      Status: ${result === "added" ? "Engram added" : "Engram config updated to use npx"}`);
+            installed++;
+        } catch (e: any) {
+            console.log(`\n   ⚠️  ${ide.name}`);
+            console.log(`      Could not write to: ${configPath}`);
+            console.log(`      Reason: ${e.message}`);
+        }
+    }
+
+    if (installed === 0) {
+        console.log("\n   No supported IDEs were found on this machine.");
+        console.log("   Run 'npx -y engram-mcp-server --list' to see what was detected.\n");
+    } else {
+        console.log(`\n✅ Done! Engram configured in ${installed} IDE(s).`);
+        console.log("   Restart your IDE(s) to load Engram.\n");
+    }
+}