context-vault 2.0.1

package/src/server/README.md

@@ -0,0 +1,44 @@
+# Server (Coordinator)
+
+The MCP server entry point. This is the only place where layers cross. It wires together Capture, Index, and Retrieve into MCP tool handlers.
+
+## Coordinator Pattern
+
+Each tool handler orchestrates layers sequentially:
+
+```
+save_context → writeEntry(ctx, data)      [Capture Layer]
+             → indexEntry(ctx, entry)      [Index Layer]
+
+get_context  → hybridSearch(ctx, query)    [Retrieve Layer]
+```
+
+No layer calls another layer directly — the server coordinates all cross-layer operations.
+
+## Auto-Reindex
+
+On the first tool call per session, the server runs a full reindex to ensure the search index matches the files on disk. This is transparent to the agent — no manual reindex tool needed.
+
+## Context Object (`ctx`)
+
+Bundles shared state passed to all layers:
+
+```js
+{ db, config, stmts, embed, insertVec, deleteVec }
+```
+
+## MCP Tools
+
+| Tool | Layers Used | Description |
+|------|-------------|-------------|
+| `get_context` | Retrieve | Hybrid FTS5 + vector search |
+| `save_context` | Capture → Index | Write-through knowledge capture |
+| `context_status` | Core (status) | Diagnostics |
+
+## Dependency Rule
+
+```
+server/ → core/, capture/, index/, retrieve/ (all layers)
+```
+
+This is the only module allowed to import across layer boundaries.

package/src/server/helpers.js

@@ -0,0 +1,29 @@
+/**
+ * helpers.js — Shared MCP response helpers and validation
+ */
+
+// ─── MCP Response Helpers ────────────────────────────────────────────────────
+
+export function ok(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+export function err(text, code = "UNKNOWN") {
+  return { content: [{ type: "text", text }], isError: true, code };
+}
+
+// ─── Validation Helpers ──────────────────────────────────────────────────────
+
+export function ensureVaultExists(config) {
+  if (!config.vaultDirExists) {
+    return err(`Vault directory not found: ${config.vaultDir}. Run context_status for diagnostics.`, "VAULT_NOT_FOUND");
+  }
+  return null;
+}
+
+export function ensureValidKind(kind) {
+  if (!/^[a-z][a-z0-9_-]*$/.test(kind)) {
+    return err("Required: kind (lowercase alphanumeric, e.g. 'insight', 'reference')", "INVALID_KIND");
+  }
+  return null;
+}

package/src/server/index.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "..", "package.json"), "utf-8"));
+
+import { resolveConfig } from "../core/config.js";
+import { embed } from "../index/embed.js";
+import { initDatabase, prepareStatements, insertVec, deleteVec } from "../index/db.js";
+import { registerTools } from "./tools.js";
+
+// ─── Config Resolution ──────────────────────────────────────────────────────
+
+const config = resolveConfig();
+
+// Create directories
+mkdirSync(config.dataDir, { recursive: true });
+mkdirSync(config.vaultDir, { recursive: true });
+
+// Write .context-mcp marker (always update to reflect current version)
+const markerPath = join(config.vaultDir, ".context-mcp");
+const markerData = existsSync(markerPath) ? JSON.parse(readFileSync(markerPath, "utf-8")) : {};
+writeFileSync(markerPath, JSON.stringify({ created: markerData.created || new Date().toISOString(), version: pkg.version }, null, 2) + "\n");
+
+// Update existence flag after directory creation
+config.vaultDirExists = existsSync(config.vaultDir);
+
+// Startup diagnostics
+console.error(`[context-mcp] Vault: ${config.vaultDir}`);
+console.error(`[context-mcp] Database: ${config.dbPath}`);
+console.error(`[context-mcp] Dev dir: ${config.devDir}`);
+if (!config.vaultDirExists) {
+  console.error(`[context-mcp] WARNING: Vault directory not found!`);
+}
+
+// ─── Database Init ───────────────────────────────────────────────────────────
+
+let db, stmts;
+try {
+  db = initDatabase(config.dbPath);
+  stmts = prepareStatements(db);
+} catch (e) {
+  console.error(`[context-mcp] Database init failed: ${e.message}`);
+  console.error(`[context-mcp] DB path: ${config.dbPath}`);
+  console.error(`[context-mcp] Try deleting the DB file and restarting: rm "${config.dbPath}"`);
+  process.exit(1);
+}
+
+const ctx = {
+  db,
+  config,
+  stmts,
+  embed,
+  insertVec: (rowid, embedding) => insertVec(stmts, rowid, embedding),
+  deleteVec: (rowid) => deleteVec(stmts, rowid),
+};
+
+// ─── MCP Server ──────────────────────────────────────────────────────────────
+
+const server = new McpServer(
+  { name: "context-mcp", version: pkg.version },
+  { capabilities: { tools: {} } }
+);
+
+registerTools(server, ctx);
+
+// ─── Graceful Shutdown ───────────────────────────────────────────────────────
+
+function shutdown() {
+  try { db.close(); } catch {}
+  process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/server/tools.js

@@ -0,0 +1,211 @@
+/**
+ * tools.js — MCP tool registrations
+ *
+ * Three tools: save_context (write), get_context (read), context_status (diag).
+ * Auto-reindex runs transparently on first tool call per session.
+ */
+
+import { z } from "zod";
+import { existsSync } from "node:fs";
+
+import { captureAndIndex } from "../capture/index.js";
+import { hybridSearch } from "../retrieve/index.js";
+import { reindex, indexEntry } from "../index/index.js";
+import { gatherVaultStatus } from "../core/status.js";
+import { categoryFor } from "../core/categories.js";
+import { normalizeKind } from "../core/files.js";
+import { ok, err, ensureVaultExists, ensureValidKind } from "./helpers.js";
+
+/**
+ * Register all MCP tools on the server.
+ *
+ * @param {import("@modelcontextprotocol/sdk/server/mcp.js").McpServer} server
+ * @param {{ db, config, stmts, embed, insertVec, deleteVec }} ctx
+ */
+export function registerTools(server, ctx) {
+  const { config } = ctx;
+
+  // ─── Auto-Reindex (runs once per session, on first tool call) ──────────────
+
+  let reindexDone = false;
+  let reindexPromise = null;
+  let reindexAttempts = 0;
+  let reindexFailed = false;
+  const MAX_REINDEX_ATTEMPTS = 2;
+
+  async function ensureIndexed() {
+    if (reindexDone) return;
+    if (reindexPromise) return reindexPromise;
+    reindexPromise = reindex(ctx, { fullSync: true })
+      .then((stats) => {
+        reindexDone = true;
+        const total = stats.added + stats.updated + stats.removed;
+        if (total > 0) {
+          console.error(`[context-mcp] Auto-reindex: +${stats.added} ~${stats.updated} -${stats.removed} (${stats.unchanged} unchanged)`);
+        }
+      })
+      .catch((e) => {
+        reindexAttempts++;
+        console.error(`[context-mcp] Auto-reindex failed (attempt ${reindexAttempts}/${MAX_REINDEX_ATTEMPTS}): ${e.message}`);
+        if (reindexAttempts >= MAX_REINDEX_ATTEMPTS) {
+          console.error(`[context-mcp] Giving up on auto-reindex. Run \`context-mcp reindex\` manually to diagnose.`);
+          reindexDone = true;
+          reindexFailed = true;
+        } else {
+          reindexPromise = null; // Allow retry on next tool call
+        }
+      });
+    return reindexPromise;
+  }
+
+  // ─── get_context (read) ────────────────────────────────────────────────────
+
+  server.tool(
+    "get_context",
+    "Search your knowledge vault. Returns entries ranked by relevance using hybrid full-text + semantic search. Use this to find insights, decisions, patterns, or any saved context.",
+    {
+      query: z.string().describe("Search query (natural language or keywords)"),
+      kind: z.string().optional().describe("Filter by kind (e.g. 'insight', 'decision', 'pattern')"),
+      category: z.enum(["knowledge", "entity", "event"]).optional().describe("Filter by category"),
+      tags: z.array(z.string()).optional().describe("Filter by tags (entries must match at least one)"),
+      since: z.string().optional().describe("ISO date, return entries created after this"),
+      until: z.string().optional().describe("ISO date, return entries created before this"),
+      limit: z.number().optional().describe("Max results to return (default 10)"),
+    },
+    async ({ query, kind, category, tags, since, until, limit }) => {
+      if (!query?.trim()) return err("Required: query (non-empty string)", "INVALID_INPUT");
+      await ensureIndexed();
+
+      const kindFilter = kind ? normalizeKind(kind) : null;
+      const sorted = await hybridSearch(ctx, query, {
+        kindFilter,
+        categoryFilter: category || null,
+        since: since || null,
+        until: until || null,
+        limit: limit || 10,
+      });
+
+      // Post-filter by tags if provided
+      const filtered = tags?.length
+        ? sorted.filter((r) => {
+            const entryTags = r.tags ? JSON.parse(r.tags) : [];
+            return tags.some((t) => entryTags.includes(t));
+          })
+        : sorted;
+
+      if (!filtered.length) return ok("No results found for: " + query);
+
+      const lines = [];
+      if (reindexFailed) lines.push(`> **Warning:** Auto-reindex failed. Results may be stale. Run \`context-mcp reindex\` to fix.\n`);
+      lines.push(`## Results for "${query}" (${filtered.length} matches)\n`);
+      for (const r of filtered) {
+        const meta = r.meta ? JSON.parse(r.meta) : {};
+        lines.push(`### ${r.title || "(untitled)"} [${r.kind}/${r.category}]`);
+        lines.push(`Score: ${r.score.toFixed(3)} | Tags: ${r.tags || "none"} | File: ${r.file_path || "n/a"}`);
+        lines.push(r.body?.slice(0, 300) + (r.body?.length > 300 ? "..." : ""));
+        lines.push("");
+      }
+      return ok(lines.join("\n"));
+    }
+  );
+
+  // ─── save_context (write) ──────────────────────────────────────────────────
+
+  server.tool(
+    "save_context",
+    "Save knowledge to your vault. Creates a .md file and indexes it for search. Use for any kind of context: insights, decisions, patterns, references, or any custom kind.",
+    {
+      kind: z.string().describe("Entry kind — determines folder (e.g. 'insight', 'decision', 'pattern', 'reference', or any custom kind)"),
+      title: z.string().optional().describe("Entry title (optional for insights)"),
+      body: z.string().describe("Main content"),
+      tags: z.array(z.string()).optional().describe("Tags for categorization and search"),
+      meta: z.any().optional().describe("Additional structured metadata (JSON object, e.g. { language: 'js', status: 'accepted' })"),
+      folder: z.string().optional().describe("Subfolder within the kind directory (e.g. 'react/hooks')"),
+      source: z.string().optional().describe("Where this knowledge came from"),
+      identity_key: z.string().optional().describe("Required for entity kinds (contact, project, tool, source). The unique identifier for this entity."),
+      expires_at: z.string().optional().describe("ISO date for TTL expiry"),
+    },
+    async ({ kind, title, body, tags, meta, folder, source, identity_key, expires_at }) => {
+      const vaultErr = ensureVaultExists(config);
+      if (vaultErr) return vaultErr;
+      const kindErr = ensureValidKind(kind);
+      if (kindErr) return kindErr;
+      if (!body?.trim()) return err("Required: body (non-empty string)", "INVALID_INPUT");
+
+      // Validate: entity kinds require identity_key
+      if (categoryFor(kind) === "entity" && !identity_key) {
+        return err(`Entity kind "${kind}" requires identity_key`, "MISSING_IDENTITY_KEY");
+      }
+
+      await ensureIndexed();
+
+      const mergedMeta = { ...(meta || {}) };
+      if (folder) mergedMeta.folder = folder;
+      const finalMeta = Object.keys(mergedMeta).length ? mergedMeta : undefined;
+
+      const entry = await captureAndIndex(ctx, { kind, title, body, meta: finalMeta, tags, source, folder, identity_key, expires_at }, indexEntry);
+      return ok(`Saved ${kind} ${entry.id}\nFile: ${entry.filePath}${title ? "\nTitle: " + title : ""}`);
+    }
+  );
+
+  // ─── context_status (diagnostics) ──────────────────────────────────────────
+
+  server.tool(
+    "context_status",
+    "Show vault health: resolved config, file counts per kind, database size, and any issues. Use to verify setup or troubleshoot.",
+    {},
+    () => {
+      const status = gatherVaultStatus(ctx);
+
+      const lines = [
+        `## Vault Status`,
+        ``,
+        `Vault:     ${config.vaultDir} (exists: ${config.vaultDirExists}, ${status.fileCount} files)`,
+        `Database:  ${config.dbPath} (exists: ${existsSync(config.dbPath)}, ${status.dbSize})`,
+        `Dev dir:   ${config.devDir}`,
+        `Data dir:  ${config.dataDir}`,
+        `Config:    ${config.configPath}`,
+        `Resolved via: ${status.resolvedFrom}`,
+        `Schema:    v5 (categories)`,
+        ``,
+        `### Indexed`,
+      ];
+
+      if (status.kindCounts.length) {
+        for (const { kind, c } of status.kindCounts) lines.push(`- ${c} ${kind}s`);
+      } else {
+        lines.push(`- (empty)`);
+      }
+
+      if (status.categoryCounts.length) {
+        lines.push(``);
+        lines.push(`### Categories`);
+        for (const { category, c } of status.categoryCounts) lines.push(`- ${category}: ${c}`);
+      }
+
+      if (status.subdirs.length) {
+        lines.push(``);
+        lines.push(`### Disk Directories`);
+        for (const { name, count } of status.subdirs) lines.push(`- ${name}/: ${count} files`);
+      }
+
+      if (status.stalePaths) {
+        lines.push(``);
+        lines.push(`### Stale Paths Detected`);
+        lines.push(`DB contains ${status.staleCount} paths not matching current vault dir.`);
+        lines.push(`Auto-reindex will fix this on next search or save.`);
+      }
+
+      if (status.embeddingStatus) {
+        const { indexed, total, missing } = status.embeddingStatus;
+        if (missing > 0) {
+          lines.push(``);
+          lines.push(`### Embeddings`);
+          lines.push(`${indexed}/${total} entries have embeddings (${missing} missing)`);
+        }
+      }
+
+      return ok(lines.join("\n"));
+    }
+  );
+}

package/ui/Context.applescript

@@ -0,0 +1,36 @@
+-- Context MCP UI Launcher
+-- Starts the server if not running, then opens the dashboard
+
+on run
+	-- Dynamic node path
+	set nodePath to do shell script "which node"
+
+	-- Dynamic serve.js path (relative to this script's bundle)
+	set scriptDir to do shell script "dirname " & quoted form of (POSIX path of (path to me))
+	set serverScript to scriptDir & "/serve.js"
+	set serverPort to "3141"
+	set serverURL to "http://localhost:" & serverPort
+
+	-- Check if server is already running on port
+	set isRunning to false
+	try
+		do shell script "lsof -ti:" & serverPort
+		set isRunning to true
+	end try
+
+	-- Start server via nohup so it survives after this app exits
+	if not isRunning then
+		do shell script "nohup " & quoted form of nodePath & " " & quoted form of serverScript & " > /tmp/context-mcp.log 2>&1 &"
+		-- Wait for server to be ready
+		repeat 10 times
+			delay 0.5
+			try
+				do shell script "curl -s -o /dev/null -w '%{http_code}' " & serverURL & "/api/discover"
+				exit repeat
+			end try
+		end repeat
+	end if
+
+	-- Open in default browser
+	open location serverURL
+end run