fathom-mcp 0.4.13 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-mcp",
-  "version": "0.4.13",
+  "version": "0.5.1",
   "description": "MCP server for Fathom — vault operations, search, rooms, and cross-workspace communication",
   "type": "module",
   "bin": {
@@ -23,7 +23,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.3",

package/scripts/fathom-start.sh

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+#
+# fathom-start.sh — Launch an agent in a correctly-named tmux session.
+#
+# Reads .fathom.json for workspace name and agent, creates
+# {workspace}_fathom-session, saves pane ID for WebSocket push injection.
+#
+# Usage:
+#   fathom-start.sh              Start agent, save pane ID, attach
+#   fathom-start.sh --detach     Start agent, save pane ID, don't attach
+#   fathom-start.sh --agent X    Override agent (claude-code|codex|gemini|opencode)
+#   fathom-start.sh --kill       Kill existing session
+#   fathom-start.sh --status     Show session status
+
+set -euo pipefail
+
+# ── Defaults ──────────────────────────────────────────────────────────────────
+
+ATTACH=true
+AGENT_OVERRIDE=""
+ACTION="start"
+
+# ── Parse flags ───────────────────────────────────────────────────────────────
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --detach)   ATTACH=false; shift ;;
+    --attach)   ATTACH=true; shift ;;
+    --agent)    AGENT_OVERRIDE="$2"; shift 2 ;;
+    --kill)     ACTION="kill"; shift ;;
+    --status)   ACTION="status"; shift ;;
+    -h|--help)
+      echo "Usage: fathom-start.sh [--attach] [--detach] [--agent NAME] [--kill] [--status]"
+      echo ""
+      echo "  (default)    Start agent in tmux, save pane ID, attach"
+      echo "  --detach     Start but don't attach"
+      echo "  --agent X    Override agent: claude-code, codex, gemini, opencode"
+      echo "  --kill       Kill existing session"
+      echo "  --status     Show if session is running"
+      exit 0
+      ;;
+    *)
+      echo "Unknown flag: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# ── Find .fathom.json ────────────────────────────────────────────────────────
+
+find_config() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/.fathom.json" ]]; then
+      echo "$dir/.fathom.json"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+CONFIG_FILE=$(find_config) || {
+  echo "Error: No .fathom.json found (searched from $PWD to /)" >&2
+  echo "Run 'npx fathom-mcp init' first." >&2
+  exit 1
+}
+
+PROJECT_DIR="$(dirname "$CONFIG_FILE")"
+
+# ── Parse config ──────────────────────────────────────────────────────────────
+
+read_json_field() {
+  local file="$1" field="$2"
+  if command -v jq &>/dev/null; then
+    jq -r ".$field // empty" "$file" 2>/dev/null
+  else
+    # Fallback: simple grep/sed for flat string fields
+    sed -n "s/.*\"$field\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$file" | head -1
+  fi
+}
+
+read_json_array_first() {
+  local file="$1" field="$2"
+  if command -v jq &>/dev/null; then
+    jq -r ".$field[0] // empty" "$file" 2>/dev/null
+  else
+    # Fallback: grab first quoted string after the array field
+    sed -n "/\"$field\"/,/\]/{ s/.*\"\([^\"]*\)\".*/\1/p; }" "$file" | head -1
+  fi
+}
+
+WORKSPACE=$(read_json_field "$CONFIG_FILE" "workspace")
+if [[ -z "$WORKSPACE" ]]; then
+  WORKSPACE="$(basename "$PROJECT_DIR")"
+fi
+
+SESSION="${WORKSPACE}_fathom-session"
+PANE_DIR="$HOME/.config/fathom"
+PANE_FILE="$PANE_DIR/${WORKSPACE}-pane-id"
+
+# ── Resolve agent command ─────────────────────────────────────────────────────
+
+resolve_agent_cmd() {
+  local agent="${AGENT_OVERRIDE:-}"
+  if [[ -z "$agent" ]]; then
+    agent=$(read_json_array_first "$CONFIG_FILE" "agents")
+  fi
+  if [[ -z "$agent" ]]; then
+    agent="claude-code"
+  fi
+
+  case "$agent" in
+    claude-code)
+      echo "claude --model opus --permission-mode bypassPermissions"
+      ;;
+    codex)
+      echo "codex"
+      ;;
+    gemini)
+      echo "gemini"
+      ;;
+    opencode)
+      echo "opencode"
+      ;;
+    *)
+      echo "Warning: Unknown agent '$agent', falling back to claude" >&2
+      echo "claude"
+      ;;
+  esac
+}
+
+# ── Save pane ID ──────────────────────────────────────────────────────────────
+
+save_pane_id() {
+  local pane_id
+  pane_id=$(tmux list-panes -t "$SESSION" -F '#{pane_id}' 2>/dev/null | head -1)
+  if [[ -n "$pane_id" ]]; then
+    mkdir -p "$PANE_DIR"
+    echo "$pane_id" > "$PANE_FILE"
+    echo "Pane ID: $pane_id → $PANE_FILE"
+  fi
+}
+
+# ── Session check ─────────────────────────────────────────────────────────────
+
+session_exists() {
+  tmux has-session -t "$SESSION" 2>/dev/null
+}
+
+# ── Actions ───────────────────────────────────────────────────────────────────
+
+do_status() {
+  echo "Workspace: $WORKSPACE"
+  echo "Session:   $SESSION"
+  if session_exists; then
+    echo "Status:    running"
+    if [[ -f "$PANE_FILE" ]]; then
+      echo "Pane ID:   $(cat "$PANE_FILE")"
+    fi
+  else
+    echo "Status:    not running"
+  fi
+}
+
+do_kill() {
+  if session_exists; then
+    tmux kill-session -t "$SESSION"
+    rm -f "$PANE_FILE"
+    echo "Killed session: $SESSION"
+  else
+    echo "Session not running: $SESSION"
+  fi
+}
+
+do_start() {
+  if session_exists; then
+    echo "Session already running: $SESSION"
+    save_pane_id
+    if [[ "$ATTACH" == true ]]; then
+      exec tmux attach-session -t "$SESSION"
+    fi
+    return 0
+  fi
+
+  local agent_cmd
+  agent_cmd=$(resolve_agent_cmd)
+
+  echo "Starting: $SESSION"
+  echo "Agent:    $agent_cmd"
+  echo "Dir:      $PROJECT_DIR"
+
+  # Unset CLAUDECODE to avoid nested session detection
+  unset CLAUDECODE 2>/dev/null || true
+
+  # Create detached tmux session running the agent
+  tmux new-session -d -s "$SESSION" -c "$PROJECT_DIR" $agent_cmd
+
+  # Wait briefly for session to stabilize
+  sleep 2
+
+  if session_exists; then
+    save_pane_id
+    echo "Session started."
+    if [[ "$ATTACH" == true ]]; then
+      exec tmux attach-session -t "$SESSION"
+    fi
+  else
+    echo "Error: Session failed to start" >&2
+    exit 1
+  fi
+}
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+case "$ACTION" in
+  status) do_status ;;
+  kill)   do_kill ;;
+  start)  do_start ;;
+esac

package/src/cli.js

@@ -845,6 +845,35 @@ async function runUpdate() {
   console.log("  Restart your agent session to pick up changes.\n");
 }
 
+// --- Start command -----------------------------------------------------------
+
+function runStart(argv) {
+  // Find the installed fathom-start.sh script
+  const found = findConfigFile(process.cwd());
+  const projectDir = found?.dir || process.cwd();
+
+  // Check .fathom/scripts/ first (installed by init/update), then package scripts/
+  const localScript = path.join(projectDir, ".fathom", "scripts", "fathom-start.sh");
+  const packageScript = path.join(SCRIPTS_DIR, "fathom-start.sh");
+  const script = fs.existsSync(localScript) ? localScript : packageScript;
+
+  if (!fs.existsSync(script)) {
+    console.error("  Error: fathom-start.sh not found. Run `npx fathom-mcp update` first.");
+    process.exit(1);
+  }
+
+  // Pass remaining args through to the shell script
+  try {
+    execFileSync("bash", [script, ...argv], {
+      cwd: projectDir,
+      stdio: "inherit",
+    });
+  } catch (e) {
+    // Script already printed its own errors; just propagate exit code
+    process.exit(e.status || 1);
+  }
+}
+
 // --- Main --------------------------------------------------------------------
 
 // Guard: only run CLI when this module is the entry point (not when imported by tests)
@@ -871,12 +900,14 @@ if (isMain) {
       console.error(`Error: ${e.message}`);
       process.exit(1);
     });
+  } else if (command === "start") {
+    runStart(process.argv.slice(3));
   } else if (!command || command === "serve") {
     // Default: start MCP server
     import("./index.js");
   } else {
     console.error(`Unknown command: ${command}`);
-    console.error(`Usage: fathom-mcp [init|status|update|serve]
+    console.error(`Usage: fathom-mcp [init|status|update|start|serve]
 
   fathom-mcp init                                    Interactive setup
   fathom-mcp init -y --api-key KEY                   Non-interactive setup
@@ -884,6 +915,9 @@ if (isMain) {
   fathom-mcp init -y --api-key KEY --workspace NAME  Custom workspace name
   fathom-mcp status                                  Check connection status
   fathom-mcp update                                  Update hooks + version
+  fathom-mcp start                                   Start agent in tmux session
+  fathom-mcp start --detach                          Start without attaching
+  fathom-mcp start --kill                            Kill agent session
   fathom-mcp                                         Start MCP server`);
     process.exit(1);
   }

package/src/index.js

@@ -20,6 +20,7 @@ import {
 
 import { resolveConfig } from "./config.js";
 import { createClient } from "./server-client.js";
+import { createWSConnection } from "./ws-connection.js";
 import {
   handleVaultWrite,
   handleVaultAppend,
@@ -32,6 +33,7 @@ import {
 
 const config = resolveConfig();
 const client = createClient(config);
+let wsConn = null;
 
 // --- Tool definitions --------------------------------------------------------
 
@@ -511,6 +513,36 @@ const telegramTools = [
       required: ["contact", "message"],
     },
   },
+  {
+    name: "fathom_telegram_image",
+    description:
+      "Read a Telegram message's attached image and return it as base64 so Claude can perceive it. " +
+      "Use after fathom_telegram_read shows a message has media: true. " +
+      "Supports jpg, jpeg, png, gif, webp. Max 5MB.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        message_id: { type: "number", description: "The message ID from fathom_telegram_read results" },
+      },
+      required: ["message_id"],
+    },
+  },
+  {
+    name: "fathom_telegram_send_image",
+    description:
+      "Send an image to a Telegram contact via the persistent Telethon client. " +
+      "Provide an absolute file path to a local image. Optionally include a caption. " +
+      "Contact can be a name, @username, or chat_id number.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        contact: { type: "string", description: "Contact name, @username, or chat_id" },
+        file_path: { type: "string", description: "Absolute path to the image file to send" },
+        caption: { type: "string", description: "Optional caption text for the image (max 1024 chars)" },
+      },
+      required: ["contact", "file_path"],
+    },
+  },
 ];
 
 // --- Server setup & dispatch -------------------------------------------------
@@ -757,6 +789,48 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
       break;
     }
+    case "fathom_telegram_image": {
+      const msgId = args.message_id;
+      if (!msgId) {
+        result = { error: "message_id is required" };
+      } else {
+        // Check local WebSocket cache first (avoids HTTP round-trip for pushed images)
+        const cached = wsConn?.getCachedImage(msgId);
+        if (cached) {
+          result = { _image: true, data: cached.data, mimeType: cached.mimeType };
+        } else {
+          result = await client.telegramImage(msgId);
+          if (result?.data && result?.mimeType) {
+            result = { _image: true, data: result.data, mimeType: result.mimeType };
+          }
+        }
+      }
+      break;
+    }
+    case "fathom_telegram_send_image": {
+      const imgContactArg = args.contact;
+      if (!imgContactArg) { result = { error: "contact is required" }; break; }
+      if (!args.file_path) { result = { error: "file_path is required" }; break; }
+
+      const imgContacts = await client.telegramContacts(config.workspace);
+      const imgList = imgContacts?.contacts || [];
+      let imgChatId = parseInt(imgContactArg, 10);
+      if (isNaN(imgChatId)) {
+        const lower = imgContactArg.toLowerCase().replace(/^@/, "");
+        const match = imgList.find(c =>
+          (c.username || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase().includes(lower)
+        );
+        imgChatId = match ? match.chat_id : null;
+      }
+      if (!imgChatId) {
+        result = { error: `Contact not found: ${imgContactArg}. Use fathom_telegram_contacts to list known contacts.` };
+      } else {
+        result = await client.telegramSendImage(imgChatId, args.file_path, args.caption);
+      }
+      break;
+    }
     default:
       result = { error: `Unknown tool: ${name}` };
   }
@@ -842,7 +916,12 @@ async function main() {
   // Startup sync for synced mode (fire-and-forget)
   startupSync().catch(() => {});
 
-  // Heartbeat — report liveness to server every 30s
+  // WebSocket push channel — receives server-pushed messages
+  if (config.server && config.workspace && config.apiKey) {
+    wsConn = createWSConnection(config);
+  }
+
+  // Heartbeat — report liveness to server every 30s (kept for backwards compat)
   if (config.server && config.workspace) {
     const beat = () =>
       client

package/src/server-client.js

@@ -265,6 +265,16 @@ export function createClient(config) {
     });
   }
 
+  async function telegramImage(messageId) {
+    return request("GET", `/api/telegram/image/${messageId}`);
+  }
+
+  async function telegramSendImage(chatId, filePath, caption) {
+    return request("POST", `/api/telegram/send-image/${chatId}`, {
+      body: { file_path: filePath, caption: caption || "" },
+    });
+  }
+
   async function telegramStatus() {
     return request("GET", "/api/telegram/status");
   }
@@ -323,6 +333,8 @@ export function createClient(config) {
     telegramContacts,
     telegramRead,
     telegramSend,
+    telegramImage,
+    telegramSendImage,
     telegramStatus,
     getSettings,
     getApiKey,

package/src/ws-connection.js

@@ -0,0 +1,250 @@
+/**
+ * WebSocket push channel — receives server-pushed messages and handles them locally.
+ *
+ * Connects to fathom-server's /ws/agent/{workspace} endpoint. Receives:
+ *   - inject / ping_fire → tmux send-keys into local pane
+ *   - image → cache base64 data to .fathom/telegram-cache/
+ *   - ping → respond with pong
+ *
+ * Auto-reconnects with exponential backoff (1s → 60s cap).
+ * HTTP heartbeat still runs separately for backwards compat with old servers.
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import WebSocket from "ws";
+
+const KEEPALIVE_INTERVAL_MS = 30_000;
+const INITIAL_RECONNECT_MS = 1_000;
+const MAX_RECONNECT_MS = 60_000;
+const IMAGE_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+/**
+ * @param {object} config — resolved config from config.js
+ * @returns {{ getCachedImage: (messageId: number) => {data: string, mimeType: string} | null, close: () => void }}
+ */
+export function createWSConnection(config) {
+  const workspace = config.workspace;
+  const agent = config.agents?.[0] || "unknown";
+  const vaultMode = config.vaultMode || "local";
+
+  // Derive WS URL from HTTP server URL
+  const serverUrl = config.server || "http://localhost:4243";
+  const wsUrl = serverUrl
+    .replace(/^http:/, "ws:")
+    .replace(/^https:/, "wss:")
+    + `/ws/agent/${encodeURIComponent(workspace)}`
+    + `?token=${encodeURIComponent(config.apiKey || "")}`;
+
+  // Image cache directory
+  const cacheDir = path.join(os.homedir(), ".fathom", "telegram-cache");
+
+  let ws = null;
+  let reconnectDelay = INITIAL_RECONNECT_MS;
+  let keepaliveTimer = null;
+  let closed = false;
+
+  // Clean up old cached images on startup
+  cleanupImageCache();
+
+  connect();
+
+  function connect() {
+    if (closed) return;
+
+    try {
+      ws = new WebSocket(wsUrl);
+    } catch {
+      scheduleReconnect();
+      return;
+    }
+
+    ws.on("open", () => {
+      reconnectDelay = INITIAL_RECONNECT_MS;
+
+      // Send hello handshake
+      ws.send(JSON.stringify({
+        type: "hello",
+        agent,
+        vault_mode: vaultMode,
+      }));
+
+      // Start keepalive pong timer
+      startKeepalive();
+    });
+
+    ws.on("message", (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+
+      switch (msg.type) {
+        case "welcome":
+          break;
+
+        case "inject":
+        case "ping_fire":
+          injectToTmux(msg.text || "");
+          break;
+
+        case "image":
+          cacheImage(msg);
+          break;
+
+        case "ping":
+          safeSend({ type: "pong" });
+          break;
+
+        case "error":
+          // Server rejected us — don't reconnect immediately
+          reconnectDelay = MAX_RECONNECT_MS;
+          break;
+      }
+    });
+
+    ws.on("close", () => {
+      stopKeepalive();
+      if (!closed) scheduleReconnect();
+    });
+
+    ws.on("error", () => {
+      // Error always followed by close event — reconnect handled there
+      stopKeepalive();
+    });
+  }
+
+  function safeSend(obj) {
+    try {
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify(obj));
+      }
+    } catch {
+      // Swallow — close event will trigger reconnect
+    }
+  }
+
+  function startKeepalive() {
+    stopKeepalive();
+    keepaliveTimer = setInterval(() => {
+      safeSend({ type: "pong" });
+    }, KEEPALIVE_INTERVAL_MS);
+  }
+
+  function stopKeepalive() {
+    if (keepaliveTimer) {
+      clearInterval(keepaliveTimer);
+      keepaliveTimer = null;
+    }
+  }
+
+  function scheduleReconnect() {
+    if (closed) return;
+    setTimeout(connect, reconnectDelay);
+    reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_MS);
+  }
+
+  // ── tmux injection ──────────────────────────────────────────────────────────
+
+  function injectToTmux(text) {
+    if (!text) return;
+    const pane = resolvePaneTarget();
+
+    try {
+      // Send the text literally, then press Enter
+      execSync(`tmux send-keys -t ${shellEscape(pane)} -l ${shellEscape(text)}`, {
+        timeout: 5000,
+        stdio: "ignore",
+      });
+      execSync(`tmux send-keys -t ${shellEscape(pane)} Enter`, {
+        timeout: 5000,
+        stdio: "ignore",
+      });
+    } catch {
+      // tmux not available or pane not found — non-fatal
+    }
+  }
+
+  function resolvePaneTarget() {
+    // Check for explicit pane ID file
+    const paneIdFile = path.join(os.homedir(), ".config", "fathom", `${workspace}-pane-id`);
+    try {
+      const paneId = fs.readFileSync(paneIdFile, "utf-8").trim();
+      if (paneId) return paneId;
+    } catch {
+      // Fall through to default
+    }
+    return `${workspace}_fathom-session`;
+  }
+
+  function shellEscape(s) {
+    // Escape for shell — wrap in single quotes, escape internal single quotes
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+  }
+
+  // ── Image cache ─────────────────────────────────────────────────────────────
+
+  function cacheImage(msg) {
+    if (!msg.message_id || !msg.data) return;
+
+    try {
+      fs.mkdirSync(cacheDir, { recursive: true });
+      const ext = (msg.filename || "").split(".").pop() || "jpg";
+      const filename = `${msg.message_id}.${ext}`;
+      const filePath = path.join(cacheDir, filename);
+      fs.writeFileSync(filePath, Buffer.from(msg.data, "base64"));
+    } catch {
+      // Cache write failure is non-fatal
+    }
+  }
+
+  function getCachedImage(messageId) {
+    try {
+      const dir = fs.readdirSync(cacheDir);
+      const match = dir.find(f => f.startsWith(`${messageId}.`));
+      if (!match) return null;
+
+      const filePath = path.join(cacheDir, match);
+      const data = fs.readFileSync(filePath);
+      const ext = path.extname(match).slice(1).toLowerCase();
+      const mimeMap = { jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif", webp: "image/webp" };
+      return {
+        data: data.toString("base64"),
+        mimeType: mimeMap[ext] || "image/jpeg",
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  function cleanupImageCache() {
+    try {
+      if (!fs.existsSync(cacheDir)) return;
+      const now = Date.now();
+      for (const file of fs.readdirSync(cacheDir)) {
+        const filePath = path.join(cacheDir, file);
+        const stat = fs.statSync(filePath);
+        if (now - stat.mtimeMs > IMAGE_CACHE_MAX_AGE_MS) {
+          fs.unlinkSync(filePath);
+        }
+      }
+    } catch {
+      // Cleanup failure is non-fatal
+    }
+  }
+
+  function close() {
+    closed = true;
+    stopKeepalive();
+    if (ws) {
+      try { ws.close(); } catch { /* ignore */ }
+      ws = null;
+    }
+  }
+
+  return { getCachedImage, close };
+}