fathom-mcp 0.5.21 → 0.6.1

package/fathom-agents.md

@@ -4,14 +4,14 @@
 
 ## Vault
 
-Local files live in `{{VAULT_DIR}}/`. The vault is for long-form content — things that need to breathe, not be queried.
+Local files live in `{{VAULT_DIR}}/`. Read, write, and edit vault files using your native file tools (`Read`, `Write`, `Edit`, `Glob`). A PostToolUse hook validates frontmatter automatically on every write.
 
 **Folder conventions:**
 - `research/` — reading notes, paper annotations, deep dives
 - `thinking/` — speculative connections, insights, one file per idea
 - `daily/` — session heartbeats and progress logs
 
-**Frontmatter required** on vault files:
+**Frontmatter required** on `.md` files in the vault:
 ```yaml
 ---
 title: My Note          # required (string)
@@ -21,11 +21,15 @@ status: draft           # optional: draft | published | archived
 ---
 ```
 
+**Search** across vault files using MCP tools:
+- `fathom_vault_search` — keyword/BM25 (fast, exact match)
+- `fathom_vault_vsearch` — semantic/vector (conceptual similarity)
+- `fathom_vault_query` — hybrid (most thorough, slowest)
+
 ## Cross-Workspace Communication
 
 This workspace is part of a multi-workspace system. Other workspaces exist — you can talk to them.
 
-- **Peek at another workspace's vault:** `fathom_vault_read path="file.md" workspace="other-ws"`
 - **Send a direct message:** `fathom_send workspace="other-ws" message="..."`
 - **Post to a shared room:** `fathom_room_post room="general" message="..."`
 - **Read room history:** `fathom_room_read room="general"`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-mcp",
-  "version": "0.5.21",
+  "version": "0.6.1",
   "description": "MCP server for Fathom — vault operations, search, rooms, and cross-workspace communication",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "src/",
     "scripts/*.sh",
     "scripts/*.py",
+    "scripts/*.js",
     "fathom-agents.md",
     "README.md",
     "CHANGELOG.md",

package/scripts/vault-frontmatter-lint.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+/**
+ * Vault frontmatter lint hook for Claude Code PostToolUse (Write/Edit).
+ *
+ * Reads the tool result from stdin (JSON), checks if the file is inside a
+ * vault/ directory and ends in .md. If so, validates frontmatter.
+ * Exits 0 on pass, 1 on failure (with error message on stderr).
+ *
+ * Environment: CLAUDE_TOOL_NAME, CLAUDE_FILE_PATH are set by Claude Code hooks.
+ */
+
+import fs from "fs";
+import path from "path";
+import { parseFrontmatter, validateFrontmatter } from "../src/frontmatter.js";
+
+const toolName = process.env.CLAUDE_TOOL_NAME || "";
+const filePath = process.env.CLAUDE_FILE_PATH || "";
+
+// Only check Write and Edit tools
+if (toolName !== "Write" && toolName !== "Edit") {
+  process.exit(0);
+}
+
+// Only check .md files inside a vault/ directory
+if (!filePath || !filePath.endsWith(".md")) {
+  process.exit(0);
+}
+
+// Check if the file is inside a vault/ directory
+const parts = filePath.split(path.sep);
+if (!parts.includes("vault")) {
+  process.exit(0);
+}
+
+// Read the file and validate
+try {
+  const content = fs.readFileSync(filePath, "utf-8");
+
+  // Only validate if file has frontmatter
+  if (!content.startsWith("---")) {
+    process.exit(0);
+  }
+
+  const { fm } = parseFrontmatter(content);
+  if (Object.keys(fm).length === 0) {
+    process.exit(0);
+  }
+
+  const errors = validateFrontmatter(fm);
+  if (errors.length > 0) {
+    process.stderr.write(`Vault frontmatter validation failed for ${path.basename(filePath)}:\n`);
+    for (const err of errors) {
+      process.stderr.write(`  - ${err}\n`);
+    }
+    process.exit(1);
+  }
+} catch (e) {
+  // File read errors are non-fatal for the hook
+  if (e.code !== "ENOENT") {
+    process.stderr.write(`Frontmatter lint error: ${e.message}\n`);
+  }
+}
+
+process.exit(0);

package/src/cli.js

@@ -8,13 +8,7 @@
  *   npx fathom-mcp init         — Interactive setup wizard
  *   npx fathom-mcp status       — Check server connection + workspace status
  *   npx fathom-mcp update       — Update hook scripts + version file
- *   npx fathom-mcp list         — List all agents + running status
- *   npx fathom-mcp start [name] — Start agent by name or legacy cwd-walk
- *   npx fathom-mcp stop <name>  — Stop an agent
- *   npx fathom-mcp restart <name> — Restart an agent
- *   npx fathom-mcp add [name]   — Add agent to registry (reads .fathom.json defaults)
- *   npx fathom-mcp remove <name>— Remove agent from registry
- *   npx fathom-mcp config <name>— Print agent config JSON
+ *   npx fathom-mcp list         — List workspaces + status (from server)
  */
 
 import fs from "fs";
@@ -25,17 +19,6 @@ import { fileURLToPath } from "url";
 
 import { findConfigFile, resolveConfig, writeConfig } from "./config.js";
 import { createClient } from "./server-client.js";
-import {
-  listAgents,
-  getAgent,
-  addAgent as registryAddAgent,
-  removeAgent as registryRemoveAgent,
-  isAgentRunning,
-  startAgent,
-  stopAgent,
-  defaultCommand,
-  buildEntryFromConfig,
-} from "./agents.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SCRIPTS_DIR = path.join(__dirname, "..", "scripts");
@@ -463,7 +446,7 @@ async function runInit(flags = {}) {
 
   // 8. Vault mode selection
   let vaultMode;
-  const validVaultModes = ["hosted", "synced", "local", "none"];
+  const validVaultModes = ["synced", "local", "none"];
   if (nonInteractive) {
     if (!serverReachable && flagServer) {
       console.error(`\n  Error: Server at ${serverUrl} is not reachable.`);
@@ -475,26 +458,25 @@ async function runInit(flags = {}) {
         console.error(`  Error: unknown vault mode "${flagVaultMode}". Valid modes: ${validVaultModes.join(", ")}`);
         process.exit(1);
       }
-      if ((flagVaultMode === "hosted" || flagVaultMode === "synced") && !serverReachable) {
+      if (flagVaultMode === "synced" && !serverReachable) {
         console.error(`  Error: vault mode "${flagVaultMode}" requires a reachable server.`);
         process.exit(1);
       }
       vaultMode = flagVaultMode;
       console.log(`  Vault mode: ${vaultMode} (--vault-mode flag)`);
     } else {
-      vaultMode = serverReachable ? "hosted" : "local";
+      vaultMode = serverReachable ? "synced" : "local";
       console.log(`  Vault mode: ${vaultMode} (auto-selected)`);
     }
   } else {
     if (serverReachable) {
       console.log("\n  Vault mode:");
-      console.log("    1. Hosted (default) — vault stored on server, accessible everywhere");
-      console.log("    2. Synced — local vault + server mirror (local is source of truth)");
-      console.log("    3. Local — vault on disk only, not visible to server");
-      console.log("    4. None — no vault, coordination features only");
+      console.log("    1. Synced (default) — local vault + server indexing");
+      console.log("    2. Local — vault on disk only, not visible to server");
+      console.log("    3. None — no vault, coordination features only");
       const modeChoice = await ask(rl, "\n  Select mode", "1");
-      const modeMap = { "1": "hosted", "2": "synced", "3": "local", "4": "none" };
-      vaultMode = modeMap[modeChoice] || "hosted";
+      const modeMap = { "1": "synced", "2": "local", "3": "none" };
+      vaultMode = modeMap[modeChoice] || "synced";
     } else {
       console.log("\n  Vault mode (server not available — hosted/synced require server):");
       console.log("    1. Local (default) — vault on disk only");
@@ -594,6 +576,7 @@ async function runInit(flags = {}) {
   const precompactCmd = "bash ~/.config/fathom-mcp/scripts/fathom-precompact.sh";
 
   // Claude Code hooks
+  const lintCmd = "node ~/.config/fathom-mcp/scripts/vault-frontmatter-lint.js";
   if (hasClaude) {
     const settingsPath = path.join(cwd, ".claude", "settings.local.json");
     const settings = readJsonFile(settingsPath) || {};
@@ -601,6 +584,7 @@ async function runInit(flags = {}) {
     changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000) || changed;
     if (enableRecallHook) changed = ensureHook(settings, "UserPromptSubmit", recallCmd, 10000) || changed;
     if (enablePrecompactHook) changed = ensureHook(settings, "PreCompact", precompactCmd, 30000) || changed;
+    changed = ensureHook(settings, "PostToolUse", lintCmd, 5000) || changed;
     if (changed) {
       writeJsonFile(settingsPath, settings);
       console.log("  ✓ .claude/settings.local.json (permissions + hooks)");
@@ -657,11 +641,6 @@ async function runInit(flags = {}) {
     }
   }
 
-  // Register in CLI agent registry (for ls/start/stop)
-  const entry = buildEntryFromConfig(cwd, configData);
-  registryAddAgent(workspace, entry);
-  console.log(`  ✓ Registered agent "${workspace}" in CLI registry`);
-
   // Context-aware next steps
   console.log(`\n  Done! Fathom MCP is configured for workspace "${workspace}".`);
   console.log(`  Vault mode: ${vaultMode}`);
@@ -677,11 +656,8 @@ async function runInit(flags = {}) {
 
   const stepNum = serverReachable ? 1 : 2;
   switch (vaultMode) {
-    case "hosted":
-      console.log(`    ${stepNum}. Your vault is stored on the server. Start writing!`);
-      break;
     case "synced":
-      console.log(`    ${stepNum}. Local vault syncs to server. Files in ./${vault}/ are the source of truth.`);
+      console.log(`    ${stepNum}. Local vault indexed by server. Files in ./${vault}/ are the source of truth.`);
       break;
     case "local":
       console.log(`    ${stepNum}. Local vault only. Server can't search or peek into it.`);
@@ -897,70 +873,56 @@ async function runUpdate() {
   console.log("\n  Restart your agent session to pick up changes.\n");
 }
 
-// --- Start command -----------------------------------------------------------
-
-function runStart(argv) {
-  // Check if first non-flag arg matches a registry entry
-  const firstArg = argv.find((a) => !a.startsWith("-"));
-  if (firstArg) {
-    const entry = getAgent(firstArg);
-    if (entry) {
-      const result = startAgent(firstArg, entry);
-      console.log(`  ${result.message}`);
-      process.exit(result.ok ? 0 : 1);
-      return;
-    }
-  }
+// --- List command (via server API) --------------------------------------------
 
-  // Legacy fallback: delegate to fathom-start.sh
-  const found = findConfigFile(process.cwd());
-  const projectDir = found?.dir || process.cwd();
-
-  const centralScript = path.join(process.env.HOME, ".config", "fathom-mcp", "scripts", "fathom-start.sh");
-  const packageScript = path.join(SCRIPTS_DIR, "fathom-start.sh");
-  const script = fs.existsSync(centralScript) ? centralScript : packageScript;
+async function runList() {
+  const config = resolveConfig();
+  const client = createClient(config);
 
-  if (!fs.existsSync(script)) {
-    console.error("  Error: fathom-start.sh not found. Run `npx fathom-mcp update` first.");
+  const isUp = await client.healthCheck();
+  if (!isUp) {
+    console.error(`\n  Error: Server not reachable at ${config.server}`);
+    console.error("  Start the server or check --server URL.\n");
     process.exit(1);
   }
 
-  try {
-    execFileSync("bash", [script, ...argv], {
-      cwd: projectDir,
-      stdio: "inherit",
-    });
-  } catch (e) {
-    process.exit(e.status || 1);
+  const wsResult = await client.listWorkspaces();
+  if (wsResult.error) {
+    console.error(`\n  Error: ${wsResult.error}\n`);
+    process.exit(1);
   }
-}
 
-// --- List command -------------------------------------------------------------
-
-function runList() {
-  const agents = listAgents();
-  const names = Object.keys(agents);
+  const profiles = wsResult.profiles || {};
+  const names = Object.keys(profiles);
 
   if (names.length === 0) {
-    console.log("\n  No agents registered. Run `fathom-mcp add` to register one.\n");
+    console.log("\n  No workspaces registered on server.\n");
     return;
   }
 
-  // Header
-  const cols = { name: 16, type: 13, status: 10 };
+  const cols = { name: 20, type: 10, status: 12 };
   console.log(
     "\n  " +
-      "NAME".padEnd(cols.name) +
+      "WORKSPACE".padEnd(cols.name) +
       "TYPE".padEnd(cols.type) +
       "STATUS".padEnd(cols.status) +
-      "DIR",
+      "PATH",
   );
 
   for (const name of names) {
-    const entry = agents[name];
-    const type = entry.agentType || "claude-code";
-    const status = entry.ssh ? "[ssh]" : isAgentRunning(name, entry);
-    const dir = entry.projectDir.replace(process.env.HOME, "~");
+    const p = profiles[name];
+    const type = p.type || "local";
+    let status;
+    if (type === "human") {
+      status = "human";
+    } else if (p.process && p.connected) {
+      status = "running";
+    } else if (p.process || p.connected) {
+      status = "partial";
+    } else {
+      status = "stopped";
+    }
+    const dir = (p.path || "").replace(process.env.HOME, "~");
 
     console.log(
       "  " +
@@ -973,134 +935,6 @@ function runList() {
   console.log();
 }
 
-// --- Stop command ------------------------------------------------------------
-
-function runStop(name) {
-  if (!name) {
-    console.error("  Usage: fathom-mcp stop <name>");
-    process.exit(1);
-  }
-  const entry = getAgent(name);
-  if (!entry) {
-    console.error(`  Error: No agent "${name}" in registry. Run \`fathom-mcp list\` to see agents.`);
-    process.exit(1);
-  }
-  const result = stopAgent(name, entry);
-  console.log(`  ${result.message}`);
-  process.exit(result.ok ? 0 : 1);
-}
-
-// --- Restart command ---------------------------------------------------------
-
-function runRestart(name) {
-  if (!name) {
-    console.error("  Usage: fathom-mcp restart <name>");
-    process.exit(1);
-  }
-  const entry = getAgent(name);
-  if (!entry) {
-    console.error(`  Error: No agent "${name}" in registry. Run \`fathom-mcp list\` to see agents.`);
-    process.exit(1);
-  }
-
-  const stopResult = stopAgent(name, entry);
-  if (stopResult.ok) {
-    console.log(`  ${stopResult.message}`);
-  }
-
-  // Brief pause between stop and start
-  try { execFileSync("sleep", ["1"], { stdio: "pipe" }); } catch { /* */ }
-
-  const startResult = startAgent(name, entry);
-  console.log(`  ${startResult.message}`);
-  process.exit(startResult.ok ? 0 : 1);
-}
-
-// --- Add command -------------------------------------------------------------
-
-async function runAdd(argv) {
-  const flags = parseFlags(argv);
-  const nameArg = argv.find((a) => !a.startsWith("-"));
-  const cwd = process.cwd();
-
-  // Try to read .fathom.json from cwd for defaults
-  const found = findConfigFile(cwd);
-  const fathomConfig = found?.config || {};
-  const projectDir = found?.dir || cwd;
-
-  const defaults = buildEntryFromConfig(projectDir, fathomConfig);
-  const defaultName = fathomConfig.workspace || path.basename(projectDir);
-
-  if (flags.nonInteractive) {
-    const name = nameArg || defaultName;
-    registryAddAgent(name, defaults);
-    console.log(`  ✓ Added agent "${name}" to registry.`);
-    return;
-  }
-
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-  const name = await ask(rl, "  Agent name", nameArg || defaultName);
-  const agentProjectDir = await ask(rl, "  Project directory", defaults.projectDir);
-  const agentType = await ask(rl, "  Agent type (claude-code|gemini|manual)", defaults.agentType);
-  const command = await ask(rl, "  Command", defaultCommand(agentType));
-  const server = await ask(rl, "  Server URL", defaults.server);
-  const apiKey = await ask(rl, "  API key", defaults.apiKey);
-  const vault = await ask(rl, "  Vault subdirectory", defaults.vault || "vault");
-  const vaultMode = await ask(rl, "  Vault mode (hosted|synced|local|none)", defaults.vaultMode);
-  const description = await ask(rl, "  Description", defaults.description);
-
-  rl.close();
-
-  const entry = {
-    projectDir: path.resolve(agentProjectDir),
-    agentType,
-    command,
-    server,
-    apiKey,
-    vault,
-    vaultMode,
-    description,
-    hooks: defaults.hooks || {},
-    ssh: null,
-    env: {},
-  };
-
-  registryAddAgent(name, entry);
-  console.log(`\n  ✓ Added agent "${name}" to registry.`);
-}
-
-// --- Remove command ----------------------------------------------------------
-
-function runRemove(name) {
-  if (!name) {
-    console.error("  Usage: fathom-mcp remove <name>");
-    process.exit(1);
-  }
-  const removed = registryRemoveAgent(name);
-  if (removed) {
-    console.log(`  ✓ Removed agent "${name}" from registry.`);
-  } else {
-    console.error(`  Error: No agent "${name}" in registry.`);
-    process.exit(1);
-  }
-}
-
-// --- Config command ----------------------------------------------------------
-
-function runConfigCmd(name) {
-  if (!name) {
-    console.error("  Usage: fathom-mcp config <name>");
-    process.exit(1);
-  }
-  const entry = getAgent(name);
-  if (!entry) {
-    console.error(`  Error: No agent "${name}" in registry.`);
-    process.exit(1);
-  }
-  console.log(JSON.stringify({ [name]: entry }, null, 2));
-}
-
 // --- Main --------------------------------------------------------------------
 
 // Guard: only run CLI when this module is the entry point (not when imported by tests)
@@ -1122,20 +956,8 @@ if (isMain) {
     asyncHandler(runStatus);
   } else if (command === "update") {
     asyncHandler(runUpdate);
-  } else if (command === "start") {
-    runStart(process.argv.slice(3));
   } else if (command === "list" || command === "ls") {
-    runList();
-  } else if (command === "stop") {
-    runStop(process.argv[3]);
-  } else if (command === "restart") {
-    runRestart(process.argv[3]);
-  } else if (command === "add") {
-    asyncHandler(() => runAdd(process.argv.slice(3)));
-  } else if (command === "remove" || command === "rm") {
-    runRemove(process.argv[3]);
-  } else if (command === "config") {
-    runConfigCmd(process.argv[3]);
+    asyncHandler(runList);
   } else if (!command || command === "serve") {
     import("./index.js");
   } else {
@@ -1147,14 +969,7 @@ if (isMain) {
   fathom-mcp init [-y --api-key KEY --vault-mode MODE --agent AGENT]    Interactive/non-interactive setup
   fathom-mcp status                                  Check connection status
   fathom-mcp update                                  Update hooks + version
-
-  fathom-mcp list                                    List all agents + status
-  fathom-mcp start [name]                            Start agent (by name or legacy cwd)
-  fathom-mcp stop <name>                             Stop agent
-  fathom-mcp restart <name>                          Stop + start agent
-  fathom-mcp add [name]                              Add agent to registry
-  fathom-mcp remove <name>                           Remove from registry
-  fathom-mcp config <name>                           Print agent config JSON`);
+  fathom-mcp list                                    List workspaces + status (from server)`);
     process.exit(1);
   }
 }

package/src/config.js

@@ -4,17 +4,15 @@
  * Precedence (highest wins):
  *   1. Environment variables (FATHOM_SERVER_URL, FATHOM_API_KEY, FATHOM_WORKSPACE, FATHOM_VAULT_DIR)
  *   2. .fathom.json (walked up from cwd to filesystem root)
- *   3. Central registry (~/.config/fathom-mcp/agents.json, matched by projectDir)
- *   4. Built-in defaults
+ *   3. Built-in defaults
  */
 
 import fs from "fs";
 import path from "path";
-import { findAgentByDir } from "./agents.js";
 
 const CONFIG_FILENAME = ".fathom.json";
 
-const VALID_VAULT_MODES = new Set(["hosted", "synced", "local", "none"]);
+const VALID_VAULT_MODES = new Set(["synced", "local", "none"]);
 
 const DEFAULTS = {
   workspace: "",
@@ -76,31 +74,13 @@ function applyConfig(result, config) {
 }
 
 /**
- * Resolve final config by merging: defaults → registry → .fathom.json → env vars.
+ * Resolve final config by merging: defaults → .fathom.json → env vars.
  */
 export function resolveConfig(startDir = process.cwd()) {
   const result = { ...DEFAULTS, hooks: { ...DEFAULTS.hooks } };
   let projectDir = startDir;
 
-  // Layer 3: Central registry (matched by projectDir walk-up)
-  let registryMatch = null;
-  try {
-    registryMatch = findAgentByDir(startDir);
-  } catch {
-    // Registry not available — skip
-  }
-  if (registryMatch) {
-    const { name, entry } = registryMatch;
-    projectDir = entry.projectDir;
-    result.workspace = name;
-    applyConfig(result, entry);
-    if (entry.agentType) {
-      result.agents = [entry.agentType];
-    }
-    result._registryName = name;
-  }
-
-  // Layer 2: .fathom.json (overrides registry)
+  // Layer 2: .fathom.json
   const found = findConfigFile(startDir);
   if (found) {
     projectDir = found.dir;

package/src/frontmatter.js

@@ -0,0 +1,77 @@
+/**
+ * Shared frontmatter parsing and validation for vault files.
+ *
+ * Used by the vault-frontmatter-lint hook script and any other
+ * code that needs to validate vault file frontmatter.
+ */
+
+// --- Constants ---------------------------------------------------------------
+
+export const VALID_STATUSES = new Set(["draft", "published", "archived"]);
+
+export const VAULT_SCHEMA = {
+  title:   { required: true,  type: "string" },
+  date:    { required: true,  type: "string" },
+  tags:    { required: false, type: "array"  },
+  status:  { required: false, type: "string" },
+  project: { required: false, type: "string" },
+  aliases: { required: false, type: "array"  },
+};
+
+// --- Frontmatter -------------------------------------------------------------
+
+export function parseFrontmatter(content) {
+  if (!content.startsWith("---")) return { fm: {}, body: content };
+  const lines = content.split("\n");
+  let endIdx = null;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") { endIdx = i; break; }
+  }
+  if (endIdx === null) return { fm: {}, body: content };
+  try {
+    const fmLines = lines.slice(1, endIdx);
+    const fm = {};
+    let currentKey = null;
+    for (const line of fmLines) {
+      const listMatch = line.match(/^[ ]{2}- (.+)$/);
+      const kvMatch = line.match(/^(\w+):\s*(.*)$/);
+      if (listMatch && currentKey) {
+        fm[currentKey].push(listMatch[1].trim());
+      } else if (kvMatch) {
+        currentKey = kvMatch[1];
+        const val = kvMatch[2].trim();
+        if (val === "") {
+          fm[currentKey] = [];
+        } else {
+          fm[currentKey] = val;
+        }
+      }
+    }
+    const body = lines.slice(endIdx + 1).join("\n");
+    return { fm, body };
+  } catch {
+    return { fm: {}, body: content };
+  }
+}
+
+export function validateFrontmatter(fm) {
+  const errors = [];
+  for (const [field, spec] of Object.entries(VAULT_SCHEMA)) {
+    const val = fm[field];
+    if (spec.required && val == null) {
+      errors.push(`Missing required field: '${field}'`);
+      continue;
+    }
+    if (val != null) {
+      const actualType = Array.isArray(val) ? "array" : typeof val;
+      if (actualType !== spec.type) {
+        errors.push(`Field '${field}' must be ${spec.type}, got ${actualType}`);
+      }
+    }
+  }
+  const status = fm["status"];
+  if (status != null && !VALID_STATUSES.has(status)) {
+    errors.push(`Field 'status' must be one of [${[...VALID_STATUSES].join(", ")}], got '${status}'`);
+  }
+  return errors;
+}