fathom-mcp 0.4.12 → 0.4.13

package/package.json

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

package/src/index.js

@@ -227,9 +227,8 @@ const tools = [
       "to the latest message. Default: 60 minutes before the latest message. Use start to look " +
       "further back. Example: minutes=15, start=120 returns 15 minutes of conversation starting " +
       "2 hours before the latest message. Response includes window metadata with has_older flag " +
-      "for pseudo-pagination. For virtual rooms (dm:*, mentions:*), messages are consumed on read — " +
-      "deleted after being returned. Use mark_read=false to peek without consuming. " +
-      "For regular rooms, automatically marks as read unless mark_read=false.",
+      "for pseudo-pagination. All rooms are persistent — messages are never deleted on read. " +
+      "Automatically marks the room as read unless mark_read=false.",
     inputSchema: {
       type: "object",
       properties: {
@@ -246,8 +245,8 @@ const tools = [
     description:
       "List all rooms with activity summary — message count, last activity time, last sender, " +
       "description, and per-room unread_count for this workspace. Use to discover active rooms " +
-      "and see which have new messages. Virtual rooms (dm:{workspace}, mentions:{workspace}) " +
-      "appear only for the owning workspace and disappear when empty.",
+      "and see which have new messages. DM rooms (dm:a+b) are filtered by workspace param — " +
+      "only participants see them. Mention rooms (mentions:{workspace}) visible only to the target workspace.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -282,10 +281,9 @@ const tools = [
   {
     name: "fathom_send",
     description:
-      "Send a message to another workspace's agent instance — stored in their dm:{workspace} " +
-      "virtual room. Use fathom_workspaces first to discover valid targets. Recipients see DMs " +
-      "via fathom_room_list and consume them with fathom_room_read. " +
-      "Message format: 'Message from workspace ({from}): {message}'",
+      "Send a message to another workspace's agent instance — stored in a shared dm:a+b room " +
+      "visible to both participants. Use fathom_workspaces first to discover valid targets. " +
+      "DMs are persistent and appear in both participants' room lists via fathom_room_list.",
     inputSchema: {
       type: "object",
       properties: {
@@ -344,6 +342,99 @@ const tools = [
       required: [],
     },
   },
+  {
+    name: "fathom_routine_list",
+    description:
+      "List all ping routines for a workspace with their status, intervals, " +
+      "enabled state, and next fire time. Use this to see what routines exist " +
+      "before updating or deleting them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: WORKSPACE_PROP,
+      },
+      required: [],
+    },
+  },
+  {
+    name: "fathom_routine_update",
+    description:
+      "Update an existing ping routine. Only provided fields are changed — " +
+      "omitted fields keep their current values. Use fathom_routine_list first " +
+      "to find the routine_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routine_id: { type: "string", description: "The routine ID to update. Use fathom_routine_list to find IDs." },
+        name: { type: "string", description: "New routine name." },
+        enabled: { type: "boolean", description: "Enable or disable the routine." },
+        interval_minutes: { type: "integer", description: "New interval in minutes.", minimum: 1 },
+        single_fire: { type: "boolean", description: "Auto-disable after firing once." },
+        workspace: WORKSPACE_PROP,
+        context_sources: {
+          type: "object",
+          description: "What to inject on each ping.",
+          properties: {
+            time: { type: "boolean", description: "Include current time/date. Default: true." },
+            scripts: {
+              type: "array",
+              description: "Shell commands to run and inject output.",
+              items: {
+                type: "object",
+                properties: {
+                  label: { type: "string" },
+                  command: { type: "string" },
+                  enabled: { type: "boolean" },
+                },
+              },
+            },
+            texts: {
+              type: "array",
+              description: "Static text blocks to inject.",
+              items: {
+                type: "object",
+                properties: {
+                  label: { type: "string" },
+                  content: { type: "string" },
+                  enabled: { type: "boolean" },
+                },
+              },
+            },
+          },
+        },
+      },
+      required: ["routine_id"],
+    },
+  },
+  {
+    name: "fathom_routine_delete",
+    description:
+      "Delete a ping routine permanently. Use fathom_routine_list first to find " +
+      "the routine_id. This cannot be undone — create a new routine if needed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routine_id: { type: "string", description: "The routine ID to delete." },
+        workspace: WORKSPACE_PROP,
+      },
+      required: ["routine_id"],
+    },
+  },
+  {
+    name: "fathom_routine_fire",
+    description:
+      "Fire a ping routine immediately, regardless of its schedule. Non-blocking — " +
+      "returns immediately while the routine fires in the background. The routine's " +
+      "next scheduled fire time is not affected.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        routine_id: { type: "string", description: "The routine ID to fire." },
+        workspace: WORKSPACE_PROP,
+      },
+      required: ["routine_id"],
+    },
+  },
 ];
 
 // --- Vault routing by mode ---------------------------------------------------
@@ -381,6 +472,47 @@ function resolveVault(args) {
   }
 }
 
+// --- Telegram tools (primary agent only) -------------------------------------
+
+const telegramTools = [
+  {
+    name: "fathom_telegram_contacts",
+    description:
+      "List Telegram contacts who have messaged. Returns name, username, chat_id, " +
+      "last_message time, and unread count.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "fathom_telegram_read",
+    description:
+      "Read recent Telegram messages from a contact. Same windowing as fathom_room_read — " +
+      "anchored to latest message, default 60 minutes. Use start to look further back.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        contact: { type: "string", description: "Contact name, @username, or chat_id" },
+        minutes: { type: "number", description: "Window duration in minutes. Default: 60." },
+        start: { type: "number", description: "Offset in minutes from latest message. Default: 0." },
+        mark_read: { type: "boolean", description: "Mark messages as read. Default: true." },
+      },
+      required: ["contact"],
+    },
+  },
+  {
+    name: "fathom_telegram_send",
+    description:
+      "Send a Telegram message to a contact via the persistent Telethon client.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        contact: { type: "string", description: "Contact name, @username, or chat_id" },
+        message: { type: "string", description: "Message text to send" },
+      },
+      required: ["contact", "message"],
+    },
+  },
+];
+
 // --- Server setup & dispatch -------------------------------------------------
 
 const server = new Server(
@@ -388,7 +520,19 @@ const server = new Server(
   { capabilities: { tools: {} } },
 );
 
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  // Telegram tools only visible to the primary (default) workspace
+  let isPrimary = false;
+  try {
+    const settings = await client.getSettings();
+    const primaryAgent = settings.default_workspace;
+    isPrimary = config.workspace === primaryAgent;
+  } catch {
+    // If settings unavailable, hide telegram tools
+  }
+  const allTools = [...tools, ...(isPrimary ? telegramTools : [])];
+  return { tools: allTools };
+});
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
@@ -543,6 +687,76 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       result = await client.createRoutine(routineParams, args.workspace || config.workspace);
       break;
     }
+    case "fathom_routine_list":
+      result = await client.listRoutines(args.workspace || config.workspace);
+      break;
+    case "fathom_routine_update": {
+      const updateParams = {};
+      if (args.name != null) updateParams.name = args.name;
+      if (args.enabled != null) updateParams.enabled = args.enabled;
+      if (args.interval_minutes != null) updateParams.intervalMinutes = args.interval_minutes;
+      if (args.single_fire != null) updateParams.singleFire = args.single_fire;
+      if (args.context_sources != null) updateParams.contextSources = args.context_sources;
+      result = await client.updateRoutine(args.routine_id, updateParams, args.workspace || config.workspace);
+      break;
+    }
+    case "fathom_routine_delete":
+      result = await client.deleteRoutine(args.routine_id, args.workspace || config.workspace);
+      break;
+    case "fathom_routine_fire":
+      result = await client.fireRoutine(args.routine_id, args.workspace || config.workspace);
+      break;
+    // --- Telegram ---
+    case "fathom_telegram_contacts":
+      result = await client.telegramContacts(config.workspace);
+      break;
+    case "fathom_telegram_read": {
+      // Resolve contact name to chat_id via contacts list
+      const contacts = await client.telegramContacts(config.workspace);
+      const contactList = contacts?.contacts || [];
+      const contactArg = (args.contact || "").trim();
+      let chatId = parseInt(contactArg, 10);
+      if (isNaN(chatId)) {
+        const lower = contactArg.toLowerCase().replace(/^@/, "");
+        const match = contactList.find(c =>
+          (c.username || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase().includes(lower)
+        );
+        chatId = match ? match.chat_id : null;
+      }
+      if (!chatId) {
+        result = { error: `Contact not found: ${contactArg}. Use fathom_telegram_contacts to list known contacts.` };
+      } else {
+        result = await client.telegramRead(
+          chatId, args.minutes, args.start,
+          args.mark_read !== false ? config.workspace : undefined,
+          args.mark_read,
+        );
+      }
+      break;
+    }
+    case "fathom_telegram_send": {
+      const sendContacts = await client.telegramContacts(config.workspace);
+      const sendList = sendContacts?.contacts || [];
+      const sendArg = (args.contact || "").trim();
+      let sendChatId = parseInt(sendArg, 10);
+      if (isNaN(sendChatId)) {
+        const lower = sendArg.toLowerCase().replace(/^@/, "");
+        const match = sendList.find(c =>
+          (c.username || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase() === lower ||
+          (c.first_name || "").toLowerCase().includes(lower)
+        );
+        sendChatId = match ? match.chat_id : null;
+      }
+      if (!sendChatId) {
+        result = { error: `Contact not found: ${sendArg}. Use fathom_telegram_contacts to list known contacts.` };
+      } else {
+        result = await client.telegramSend(sendChatId, args.message);
+      }
+      break;
+    }
     default:
       result = { error: `Unknown tool: ${name}` };
   }

package/src/server-client.js

@@ -205,6 +205,37 @@ export function createClient(config) {
     });
   }
 
+  async function listRoutines(ws) {
+    return request("GET", "/api/activation/ping/routines", {
+      params: { workspace: ws },
+    });
+  }
+
+  async function updateRoutine(routineId, params, ws) {
+    const body = {};
+    if (params.name != null) body.name = params.name;
+    if (params.enabled != null) body.enabled = params.enabled;
+    if (params.intervalMinutes != null) body.intervalMinutes = params.intervalMinutes;
+    if (params.singleFire != null) body.singleFire = params.singleFire;
+    if (params.contextSources != null) body.contextSources = params.contextSources;
+    return request("POST", `/api/activation/ping/routines/${encodeURIComponent(routineId)}`, {
+      params: { workspace: ws },
+      body,
+    });
+  }
+
+  async function deleteRoutine(routineId, ws) {
+    return request("DELETE", `/api/activation/ping/routines/${encodeURIComponent(routineId)}`, {
+      params: { workspace: ws },
+    });
+  }
+
+  async function fireRoutine(routineId, ws) {
+    return request("POST", `/api/activation/ping/routines/${encodeURIComponent(routineId)}/now`, {
+      params: { workspace: ws },
+    });
+  }
+
   // --- Heartbeat -------------------------------------------------------------
 
   async function heartbeat(ws, agent, vaultMode) {
@@ -214,6 +245,36 @@ export function createClient(config) {
     return request("POST", `/api/workspaces/${encodeURIComponent(ws)}/heartbeat`, { body });
   }
 
+  // --- Telegram --------------------------------------------------------------
+
+  async function telegramContacts(ws) {
+    return request("GET", "/api/telegram/contacts", {
+      params: { workspace: ws },
+    });
+  }
+
+  async function telegramRead(chatId, minutes, start, ws, markRead) {
+    return request("GET", `/api/telegram/messages/${chatId}`, {
+      params: { minutes, start, workspace: ws, mark_read: markRead },
+    });
+  }
+
+  async function telegramSend(chatId, message) {
+    return request("POST", `/api/telegram/send/${chatId}`, {
+      body: { message },
+    });
+  }
+
+  async function telegramStatus() {
+    return request("GET", "/api/telegram/status");
+  }
+
+  // --- Settings --------------------------------------------------------------
+
+  async function getSettings() {
+    return request("GET", "/api/settings");
+  }
+
   // --- Auth ------------------------------------------------------------------
 
   async function getApiKey() {
@@ -254,7 +315,16 @@ export function createClient(config) {
     pushFile,
     syncManifest,
     createRoutine,
+    listRoutines,
+    updateRoutine,
+    deleteRoutine,
+    fireRoutine,
     heartbeat,
+    telegramContacts,
+    telegramRead,
+    telegramSend,
+    telegramStatus,
+    getSettings,
     getApiKey,
     healthCheck,
   };