fathom-mcp 0.4.13 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-mcp",
-  "version": "0.4.13",
+  "version": "0.5.0",
   "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/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 };
+}