fathom-mcp 0.6.3 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-mcp",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "MCP server for Fathom — vault operations, search, rooms, and cross-workspace communication",
   "type": "module",
   "bin": {

package/scripts/fathom-instructions.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# SessionStart hook (Fathom) — inject MCP tool reference + notification instructions.
+# Independent of version check — always runs.
+# Output: JSON with hookSpecificOutput.additionalContext.
+
+# Consume stdin (SessionStart sends JSON we don't need)
+cat > /dev/null
+
+read -r -d '' INSTRUCTIONS << 'FATHOM_EOF'
+# Fathom MCP (`mcp__fathom__*` + `mcp__fathom-vault__*`)
+
+**Load tools:** `ToolSearch query="+fathom" max_results=20`
+
+One MCP server: `fathom-vault`. Handles search, rooms, workspaces, TTS, and routines. Vault file I/O uses Claude Code's native tools (`Read`, `Write`, `Edit`, `Glob`) — a PostToolUse hook validates frontmatter automatically.
+
+**`mcp__fathom-vault__*` tools:**
+
+| Tool | What it does |
+|------|-------------|
+| **Search** | |
+| `fathom_vault_search` | Keyword search (BM25) across vault files — fast, start here |
+| `fathom_vault_vsearch` | Semantic/vector search — conceptual similarity, slower |
+| `fathom_vault_query` | Hybrid search (BM25 + vector + reranking) — most thorough |
+| **Rooms** | |
+| `fathom_room_post` | Post to a shared room (created on first post). Multilateral — all participants see it. Supports `@workspace` mentions and `@all`. |
+| `fathom_room_read` | Read recent room messages (default 60min window anchored to latest). Supports `minutes`/`start` for pagination. |
+| `fathom_room_list` | List all rooms with message count, last activity, unread counts. |
+| `fathom_room_describe` | Set or clear a room's description/topic. |
+| **Workspaces** | |
+| `fathom_workspaces` | List all workspaces with running status, model, and role. |
+| `fathom_send` | DM another workspace — stored in a shared `dm:a+b` room visible to both participants. |
+| **Voice & TTS** | |
+| `fathom_speak` | Generate speech (Kokoro TTS — am_echo 70% + bf_alice 30%). Returns WAV path. Optional `play=true`. |
+| `fathom_send_voice` | Generate speech and send as a voice bubble to Myra via the app. |
+| **Routines** | |
+| `fathom_routine_list` | List routines with merged runtime state (next_ping_at, last_fire_at). Works cross-workspace. |
+| `fathom_routine_fire` | Fire a routine immediately, bypassing conditions. Non-blocking. Works cross-workspace. |
+| **Admin** | |
+| `fathom_key_rotate` | Rotate this agent's API key. Revokes current key, issues new one, reconnects. |
+| `policy_evaluate` | Evaluate a permission request for a tool call (called automatically by --permission-prompt-tool). |
+
+**Image Generation (fal.ai):** Use `mcp__fal-ai__*` tools. Default model: `fal-ai/fast-sdxl/image-to-image` for img2img, `fal-ai/nano-banana-pro` for text-to-image. **Always use nano-banana-pro unless another model is specifically requested.**
+
+**Browser:** Use `mcp__chrome-devtools__*` tools. The MCP manages Chrome automatically — just call tools directly. **Always close your pages when done** (`close_page`) so other agents can use Chrome. Only one agent can drive Chrome at a time.
+
+**Vault structure:** See `vault/CLAUDE.md` for full folder map and what goes where.
+
+### App Notifications (#notification room)
+
+After posting to #general, also post a structured JSON message to `#notification` for the dashboard feed:
+`fathom_room_post room="notification" message='{"type":"post","title":"...","body":"..."}'`
+Types: `"post"` (findings/content), `"status"` (operational), `"content"` (linked content with `content_id`). Plain text fallback works too.
+
+**The body field supports full HTML with inline CSS.** This is a rich rendering surface — use it. Capabilities:
+- **Layout:** `display:flex`, `gap`, `padding`, `margin`, tables — all work. Flexbox is preferred.
+- **Styling:** `border-radius`, `background`, `color`, `font-size`, `font-weight`, `object-fit` — all inline CSS works.
+- **Images:** `<img src="...">` renders inline. Wrap in `<a href="..." target="_blank">` for clickable links to source. Use real CDN image URLs (grab via Chrome `evaluate_script` from product pages, paper figures, screenshots, etc.).
+- **Links:** `<a href="..." target="_blank">` for clickable links. Link images, titles, and add explicit text links — multiple touchpoints per item.
+- **Badges/chips:** Use inline `<span>` with background color, padding, border-radius for sale tags, status pills, warning chips.
+- **Markdown** also works in the body for simpler notifications.
+
+**Design your notifications to be visually rich and scannable.** Myra reads these on a dashboard — think product cards, not log entries. Each workspace should develop templates appropriate to its content (e.g., wardrobe uses product cards with images, NS uses equation summaries with paper links).
+
+**Attachments:** To attach vault files (images, docs, audio) to a notification, add an `attachments` array. Each entry has `path` (relative to your vault) and optional `label`. The dashboard resolves types from extensions and renders images inline, audio as players, and other files as clickable chips.
+```json
+{"type":"content","content_id":"unique-id","title":"Title","body":"<div style=\"font-family:system-ui\">HTML here</div>","attachments":[
+  {"path":"photos/olive-top.jpg","label":"Olive button-up"},
+  {"path":"research/note-96.md","label":"Note 96: Seregin Analysis"}
+]}
+```
+Supported: images (.png/.jpg/.gif/.webp), audio (.mp3/.wav/.webm), video (.mp4), documents (.pdf/.md/.txt/.csv/.json/.svg). Old `images` format still works (backward compat).
+FATHOM_EOF
+
+python3 -c "
+import json, sys
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'SessionStart',
+        'additionalContext': sys.argv[1]
+    }
+}))
+" "$INSTRUCTIONS"
+
+exit 0

package/src/cli.js

@@ -154,34 +154,6 @@ function copyScripts(targetDir) {
   }
 }
 
-// ---------------------------------------------------------------------------
-// CLAUDE.md integration
-// ---------------------------------------------------------------------------
-
-const FATHOM_MD_MARKER_START = "<!-- BEGIN fathom-mcp -->";
-const FATHOM_MD_MARKER_END = "<!-- END fathom-mcp -->";
-
-function appendToClaudeMd(cwd, blob) {
-  const mdPath = path.join(cwd, "CLAUDE.md");
-  let content = "";
-  try { content = fs.readFileSync(mdPath, "utf-8"); } catch { /* new file */ }
-
-  const wrappedBlob = `${FATHOM_MD_MARKER_START}\n${blob}\n${FATHOM_MD_MARKER_END}`;
-
-  const markerRe = new RegExp(
-    `${FATHOM_MD_MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${FATHOM_MD_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
-  );
-
-  if (markerRe.test(content)) {
-    content = content.replace(markerRe, wrappedBlob);
-  } else {
-    content = content.trimEnd() + "\n\n" + wrappedBlob + "\n";
-  }
-
-  fs.writeFileSync(mdPath, content, "utf-8");
-  return mdPath;
-}
-
 /**
  * Check if fathom-server is available on PATH.
  * Returns "installed" or "not-found".
@@ -562,6 +534,7 @@ async function runInit(flags = {}) {
   }
 
   // Hook scripts (central location, shared across agents)
+  const instructionsCmd = "bash ~/.config/fathom-mcp/scripts/fathom-instructions.sh";
   const sessionStartCmd = "bash ~/.config/fathom-mcp/scripts/fathom-sessionstart.sh";
   const recallCmd = "bash ~/.config/fathom-mcp/scripts/fathom-recall.sh";
   const precompactCmd = "bash ~/.config/fathom-mcp/scripts/fathom-precompact.sh";
@@ -572,6 +545,8 @@ async function runInit(flags = {}) {
     const settingsPath = path.join(cwd, ".claude", "settings.local.json");
     const settings = readJsonFile(settingsPath) || {};
     let changed = ensurePermissions(settings);
+    // Instructions hook always registered (injects tool reference tables)
+    changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000) || changed;
     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;
@@ -586,7 +561,8 @@ async function runInit(flags = {}) {
   if (hasGemini) {
     const settingsPath = path.join(cwd, ".gemini", "settings.json");
     const settings = readJsonFile(settingsPath) || {};
-    let changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000);
+    let changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000);
+    changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000) || changed;
     if (enableRecallHook) changed = ensureHook(settings, "BeforeAgent", recallCmd, 10000) || changed;
     if (enablePrecompactHook) changed = ensureHook(settings, "PreCompress", precompactCmd, 30000) || changed;
     if (changed) {
@@ -673,50 +649,6 @@ async function runInit(flags = {}) {
     console.log(`\n  Non-interactive equivalent:\n    ${parts.join(" ")}\n`);
   }
 
-  // Append agent instructions to CLAUDE.md
-  let instructionsBlob = "";
-  try {
-    instructionsBlob = fs.readFileSync(agentMdDest, "utf-8");
-  } catch { /* template wasn't created — skip */ }
-
-  if (instructionsBlob) {
-    if (nonInteractive) {
-      const mdPath = appendToClaudeMd(cwd, instructionsBlob);
-      console.log(`\n  ✓ Instructions written to ${path.relative(cwd, mdPath)}\n`);
-    } else {
-      const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
-      console.log("\n" + "─".repeat(60));
-      const integrate = await askYesNo(
-        rl2,
-        "\n  Append Fathom instructions to CLAUDE.md?",
-        true,
-      );
-      rl2.close();
-
-      if (integrate) {
-        const mdPath = appendToClaudeMd(cwd, instructionsBlob);
-        console.log(`\n  ✓ Instructions written to ${path.relative(cwd, mdPath)}\n`);
-      } else {
-        printInstructionsFallback(agentMdDest, selectedAgents);
-      }
-    }
-  } else {
-    console.log("\n  No agent instructions template found — skipping integration.\n");
-  }
-}
-
-function printInstructionsFallback(agentMdPath, selectedAgents) {
-  const hasNonClaude = selectedAgents.some((k) => k !== "claude-code");
-  const docTarget = hasNonClaude
-    ? "your CLAUDE.md, AGENTS.md, or equivalent"
-    : "your CLAUDE.md";
-
-  console.log(`
-  Agent instructions saved to: ${path.relative(process.cwd(), agentMdPath)}
-
-  Paste into ${docTarget}, or point your agent at the file
-  and ask it to integrate the instructions.
-`);
 }
 
 // --- Status command ----------------------------------------------------------
@@ -784,9 +716,10 @@ async function runUpdate() {
   const scriptsDir = path.join(process.env.HOME, ".config", "fathom-mcp", "scripts");
   const copiedScripts = copyScripts(scriptsDir);
 
-  // Ensure SessionStart hook is registered for agents that support hooks
+  // Ensure SessionStart hooks are registered for agents that support hooks
   // Detect by config agents field or directory presence (older configs may lack agents)
   const agents = found.config.agents || [];
+  const instructionsCmd = "bash ~/.config/fathom-mcp/scripts/fathom-instructions.sh";
   const sessionStartCmd = "bash ~/.config/fathom-mcp/scripts/fathom-sessionstart.sh";
   const registeredHooks = [];
 
@@ -797,6 +730,7 @@ async function runUpdate() {
     const settingsPath = path.join(projectDir, ".claude", "settings.local.json");
     const settings = readJsonFile(settingsPath) || {};
     let changed = ensurePermissions(settings);
+    changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000) || changed;
     changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000) || changed;
     if (changed) {
       writeJsonFile(settingsPath, settings);
@@ -810,7 +744,9 @@ async function runUpdate() {
   if (hasGemini) {
     const settingsPath = path.join(projectDir, ".gemini", "settings.json");
     const settings = readJsonFile(settingsPath) || {};
-    if (ensureHook(settings, "SessionStart", sessionStartCmd, 10000)) {
+    let changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000);
+    changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000) || changed;
+    if (changed) {
       writeJsonFile(settingsPath, settings);
       registeredHooks.push("Gemini CLI → .gemini/settings.json");
     }