@echomem/mcp 1.0.0

package/README.md

@@ -0,0 +1,159 @@
+# EchoMem Cloud-First MCP Server
+
+This package implements a stateless, cloud-first [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for EchoMem. It allows local IDE agents (like Cursor, Windsurf, Claude Desktop, and VS Code) to interact with the user's secure EchoMem personal backend without risk of file-locking or sandbox conflict with the running Chrome Extension's local database.
+
+## Architecture
+
+This MCP Server bridges local tools and your EchoMem Cloud API entirely via authenticated REST `fetch()` calls. 
+
+- `search_memories`: Connects to `POST /api/extension/memories/search`
+- `save_conversation`: Connects to `POST /api/extension/memories/ingest`
+- `get_memories_by_time_range`: Connects to `POST /api/extension/memories/time-range`
+- `search_memories_by_keywords`: Connects to `POST /api/extension/memories/keywords`
+- `search_others_memories`: Connects to MemoryFeed search after resolving the authenticated Echo user id
+
+No direct access to the `IndexedDB` or local files is required.
+
+## Encryption — the local bridge is the encrypted surface
+
+For **zero-knowledge accounts**, the key never leaves your machine. The bridge holds the key locally
+(exactly like the Chrome extension) and:
+
+- **reads:** the server returns ciphertext; the bridge **decrypts locally** so the model only ever
+  sees plaintext. The server never holds your key.
+- **writes:** the key is handed to your own backend transiently in the `X-Encryption-Key` header so
+  memories are encrypted at rest (the server processes plaintext for the request only — never stores
+  the key).
+- **locked state:** if the key is absent or past its TTL (7 days, matching the extension), tools
+  return a `🔒 locked` nudge to run `echomem-mcp unlock` — **ciphertext is never handed to the model**.
+
+Unencrypted accounts are unaffected and use the tuned two-phase retriever as before.
+
+## Quick start (recommended)
+
+```bash
+# One command: detect your editor, write its MCP config, log in via the browser.
+npx -y @echomem/mcp setup
+```
+
+`setup` detects the client (Cursor / Windsurf / Claude Desktop), writes its MCP config (with **no
+secret** in it — credentials live in `~/.echomem/credentials.json`, mode 0600), then opens the
+browser to approve the device and, for encrypted accounts, unlock the vault. Reload your editor and
+you're done.
+
+| Command | What it does |
+|---|---|
+| `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop]` | Write client config + log in |
+| `echomem-mcp login` | Approve device in browser (or use `--token` / `--passphrase`) |
+| `echomem-mcp unlock` | Re-derive the encryption key after its TTL (or `--passphrase`) |
+| `echomem-mcp status` | Show token / key / detected clients |
+| `echomem-mcp logout` | Remove stored credentials |
+
+### Manual / headless (SSH, containers, CI)
+
+No browser? Provide secrets directly — this is the documented headless path:
+
+```bash
+echomem-mcp login --token ec_xxx                       # unencrypted account
+echomem-mcp login --token ec_xxx --passphrase '<vault>' # encrypted: derives + verifies the key
+# or pre-provision via env: ECHO_API_TOKEN, ECHO_ENCRYPTION_KEY (base64)
+```
+
+> The browser flow depends on the EchoMem **"connect device"** web page posting `{ token, key? }` to
+> the bridge's localhost callback. Until that page ships, use the manual flags above (same result).
+
+## Setup & Configuration (manual config)
+
+### Prerequisites
+A valid EchoMem API key (`ec_…`). For encrypted accounts, your vault passphrase.
+
+### Building
+```bash
+cd packages/mcp-server
+npm install
+npm run build
+npm test   # crypto compat + encrypted-local integration tests
+```
+
+### Add to your IDE (Cursor or Windsurf)
+
+> Prefer `npx -y @echomem/mcp setup` above — it writes these files for you and keeps secrets out of
+> the client config. The manual steps below are the fallback.
+
+#### For Cursor
+In Cursor, go to Settings -> Features -> MCP Servers. Add a new MCP Server:
+- **Type**: `command`
+- **Name**: `echomem`
+- **Command**: `npx`
+- **Args**: `-y @echomem/mcp@latest`
+
+Under the **Environment Variables** section of the server configuration, add:
+- `ECHO_API_TOKEN`: `ec_...` *(Required unless provisioned via `login`: your EchoMem API key)*
+- `ECHO_API_BASE_URL`: `https://echo-mem-chrome.vercel.app` *(Optional: Defaults to production URL)*
+- `MEMORY_FEED_API_URL`: `https://memory-feed.vercel.app` *(Optional: Defaults to production MemoryFeed URL)*
+
+#### For Windsurf
+1. Open your global Windsurf MCP configuration file:
+   - **Mac/Linux**: `~/.codeium/windsurf/mcp_config.json`
+   - **Windows**: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+2. Add the `echomem` server beneath your existing configurations:
+```json
+{
+  "mcpServers": {
+     "echomem": {
+       "command": "npx",
+       "args": ["-y", "@echomem/mcp@latest"],
+       "env": {
+         "ECHO_API_TOKEN": "ec_YOUR_API_KEY_HERE",
+         "ECHO_API_BASE_URL": "https://echo-mem-chrome.vercel.app"
+       }
+     }
+  }
+}
+```
+3. Restart Windsurf.
+
+### Add to Claude Desktop
+
+claude.ai integrations must be configured via the Claude Desktop app.
+1. Open your Claude Desktop setting file:
+   - **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+2. Update your `mcpServers` object to include EchoMem, adding `ECHO_API_TOKEN` to the `env` object:
+```json
+{
+  "mcpServers": {
+     "echomem": {
+       "command": "node",
+       "args": ["/absolute/path/to/EchoMem-Chrome/packages/mcp-server/dist/index.js"],
+       "env": {
+         "ECHO_API_TOKEN": "your_generated_ec_key..."
+       }
+     }
+  }
+}
+```
+3. Restart Claude Desktop.
+
+### Using via CLI (testing)
+```bash
+ECHO_API_TOKEN="your_token" ECHO_API_BASE_URL="http://localhost:3000" npm run start
+```
+
+## Available Tools
+
+* **`search_memories`**: Perform semantic searches against your personal memory vault using cloud embeddings.
+* **`save_conversation`**: Ingest and structure a conversation directly into your EchoMem timeline.
+* **`get_memories_by_time_range`**: Retrieve memories between explicit start/end timestamps.
+* **`search_memories_by_keywords`**: Retrieve memories by matching the `keys` field.
+* **`search_others_memories`**: Search other users' public memories through MemoryFeed.
+
+Legacy aliases are preserved for compatibility:
+
+* `search_memories_by_description_semantic` -> `search_memories`
+* `search_memories_by_time_range` -> `get_memories_by_time_range`
+
+Contract reference:
+
+* `docs/PUBLIC_API_CONTRACT_V1.md`
+* `docs/MCP_COMPAT_MATRIX.md`

package/dist/crypto.js

@@ -0,0 +1,107 @@
+/**
+ * AES-256-GCM crypto for the local MCP bridge.
+ *
+ * ⚠️  MIRRORED FROM `utils/crypto.ts` (the extension/web shared module). The two MUST stay
+ * byte-compatible — the bridge decrypts ciphertext the extension/server wrote and vice versa.
+ * The ONLY intentional deviation: this file pins `node:crypto` webcrypto (the bridge is a
+ * Node-only CLI, never a browser), whereas the shared module reads `globalThis.crypto` so it
+ * can also run in-page. Algorithm, IV size, ciphertext envelope, PBKDF2 params, and the
+ * verification plaintext are identical — do not change them here without changing both.
+ *
+ * Ciphertext format: base64( 12-byte IV || ciphertext || 16-byte GCM auth tag )
+ */
+import { webcrypto } from "node:crypto";
+const ALGORITHM = "AES-GCM";
+const KEY_LENGTH = 256;
+const IV_BYTES = 12;
+const SALT_BYTES = 16;
+const DEFAULT_ITERATIONS = 600_000;
+const VERIFICATION_PLAINTEXT = "echomem-verify-v1";
+// Legacy plaintext used before rename — tokens in the DB may still use this.
+const LEGACY_VERIFICATION_PLAINTEXT = "echo-vault-verify";
+const subtle = webcrypto.subtle;
+function toBase64(buf) {
+    const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+function fromBase64(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/** Generate a random 16-byte salt for PBKDF2. */
+export function generateSalt() {
+    return webcrypto.getRandomValues(new Uint8Array(SALT_BYTES));
+}
+export function saltToBase64(salt) {
+    return toBase64(salt);
+}
+export function saltFromBase64(b64) {
+    return fromBase64(b64);
+}
+/**
+ * Derive an AES-256-GCM CryptoKey from a passphrase and salt via PBKDF2.
+ * Deterministic: same passphrase + salt + iterations → same key on any platform.
+ */
+export async function deriveKey(passphrase, salt, iterations = DEFAULT_ITERATIONS) {
+    const encoder = new TextEncoder();
+    const keyMaterial = await subtle.importKey("raw", encoder.encode(passphrase), "PBKDF2", false, ["deriveKey"]);
+    const saltBuf = new Uint8Array(salt).buffer;
+    return subtle.deriveKey({ name: "PBKDF2", salt: saltBuf, iterations, hash: "SHA-256" }, keyMaterial, { name: ALGORITHM, length: KEY_LENGTH }, true, ["encrypt", "decrypt"]);
+}
+export async function exportKeyToBase64(key) {
+    const raw = await subtle.exportKey("raw", key);
+    return toBase64(raw);
+}
+const importedKeyCache = new Map();
+export async function importKeyFromBase64(b64) {
+    const cached = importedKeyCache.get(b64);
+    if (cached)
+        return cached;
+    const raw = fromBase64(b64);
+    const keyBuf = new Uint8Array(raw).buffer;
+    const key = await subtle.importKey("raw", keyBuf, { name: ALGORITHM, length: KEY_LENGTH }, false, ["encrypt", "decrypt"]);
+    importedKeyCache.set(b64, key);
+    return key;
+}
+/**
+ * Encrypt a plaintext string with AES-256-GCM.
+ * Returns base64( 12-byte IV || ciphertext || 16-byte auth tag ). Fresh random IV per call.
+ */
+export async function encrypt(plaintext, key) {
+    const iv = webcrypto.getRandomValues(new Uint8Array(IV_BYTES));
+    const encoder = new TextEncoder();
+    const ciphertext = await subtle.encrypt({ name: ALGORITHM, iv }, key, encoder.encode(plaintext));
+    const combined = new Uint8Array(IV_BYTES + ciphertext.byteLength);
+    combined.set(iv, 0);
+    combined.set(new Uint8Array(ciphertext), IV_BYTES);
+    return toBase64(combined);
+}
+/**
+ * Decrypt a base64 ciphertext string produced by `encrypt()`.
+ * Throws if the key is wrong or data is tampered.
+ */
+export async function decrypt(ciphertext, key) {
+    const combined = fromBase64(ciphertext);
+    const iv = combined.slice(0, IV_BYTES);
+    const data = combined.slice(IV_BYTES);
+    const plainBuffer = await subtle.decrypt({ name: ALGORITHM, iv }, key, data);
+    return new TextDecoder().decode(plainBuffer);
+}
+/** Verify a key against a stored verification token (current + legacy plaintexts). */
+export async function verifyKey(key, token) {
+    try {
+        const result = await decrypt(token, key);
+        return result === VERIFICATION_PLAINTEXT || result === LEGACY_VERIFICATION_PLAINTEXT;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/encryption.js

@@ -0,0 +1,60 @@
+import { deriveKey, exportKeyToBase64, importKeyFromBase64, decrypt, verifyKey, saltFromBase64 } from "./crypto.js";
+/** GET the account's encryption status from the EchoMem backend using the bridge's authed client. */
+export async function fetchEncryptionConfig(axios) {
+    const res = await axios.get("/api/extension/account/encryption");
+    const data = res.data ?? {};
+    return {
+        enabled: !!data.enabled,
+        salt: data.salt,
+        verification: data.verification,
+        iterations: typeof data.iterations === "number" ? data.iterations : undefined,
+    };
+}
+/**
+ * Derive a key from a passphrase using the account's salt/iterations, verify it against the
+ * server's verification token, and return the base64 key — or null if the passphrase is wrong.
+ * Never returns an unverified key.
+ */
+export async function deriveAndVerifyKey(passphrase, config) {
+    if (!config.enabled || !config.salt || !config.verification)
+        return null;
+    const salt = saltFromBase64(config.salt);
+    const key = await deriveKey(passphrase, salt, config.iterations ?? 600_000);
+    if (!(await verifyKey(key, config.verification)))
+        return null;
+    return exportKeyToBase64(key);
+}
+/** Verify an already-exported base64 key against the server's verification token. */
+export async function verifyKeyB64(keyBase64, config) {
+    if (!config.enabled || !config.verification)
+        return false;
+    try {
+        const key = await importKeyFromBase64(keyBase64);
+        return await verifyKey(key, config.verification);
+    }
+    catch {
+        return false;
+    }
+}
+/** Decrypt one field with the cached key; returns the original value if it isn't valid ciphertext. */
+export async function decryptField(value, keyBase64) {
+    if (!value)
+        return value;
+    try {
+        const key = await importKeyFromBase64(keyBase64);
+        return await decrypt(value, key);
+    }
+    catch {
+        return value; // plaintext / pre-encryption data — leave as-is
+    }
+}
+/** Decrypt the model-visible text fields on a memory row in place-safe fashion. */
+export async function decryptMemoryFields(memory, keyBase64) {
+    const out = { ...memory };
+    for (const field of ["description", "details", "content"]) {
+        if (typeof out[field] === "string") {
+            out[field] = await decryptField(out[field], keyBase64);
+        }
+    }
+    return out;
+}