fathom-mcp 2.1.0 → 2.2.2

package/index.js

@@ -36,13 +36,13 @@ function authHeaders(json = true) {
   return h;
 }
 
-// ── Result formatting ────────────────────────────
+// ── Result formatting (keyed by tool's response_kind) ────────────────
 
-function formatResults(data) {
+function formatMomentList(data) {
   const items = data.results || data.deltas || (Array.isArray(data) ? data : []);
-  if (!items.length) return "No results.";
+  if (!items.length) return "No moments surfaced.";
 
-  const lines = [`${items.length} results:\n`];
+  const lines = [`${items.length} moments:\n`];
   for (const raw of items) {
     const d = raw.delta || raw;
     const ts = (d.timestamp || "").slice(0, 16);
@@ -55,62 +55,140 @@ function formatResults(data) {
   return lines.join("\n");
 }
 
-function formatResponse(path, method, data) {
-  if (path === "/v1/search") return formatResults(data);
-  if (path === "/v1/deltas" && method === "POST") return `Written. ID: ${data.id || "?"}`;
-  if (path === "/v1/deltas" && method === "GET") return formatResults(data);
-  if (path === "/v1/stats") {
-    return `Lake: ${data.total ?? "?"} deltas, ${data.embedded ?? "?"} embedded (${data.percent ?? "?"}% coverage)`;
-  }
-  if (path === "/v1/chat/completions") {
-    const choices = data.choices || [];
-    return choices.length ? choices[0].message?.content || "" : JSON.stringify(data).slice(0, 2000);
+function formatRecall(data) {
+  const total = data.total_count || 0;
+  const tree = data.tree || [];
+  if (!total || !tree.length) return "No moments surfaced.";
+  const header = `${total} moments across ${tree.length} step(s):\n`;
+  return header + "\n" + (data.as_prompt || "");
+}
+
+function formatStats(data) {
+  return `Your mind: ${data.total ?? "?"} moments, ${data.embedded ?? "?"} embedded (${data.percent ?? "?"}% coverage)`;
+}
+
+function formatTags(data) {
+  // /v1/tags returns {tag: count}. Top 50 keeps context bounded.
+  if (!data || typeof data !== "object") return "No tags.";
+  const entries = Object.entries(data).sort((a, b) => b[1] - a[1]);
+  if (!entries.length) return "No tags.";
+  const top = entries.slice(0, 50);
+  const lines = [`${entries.length} tags (top ${top.length}):\n`];
+  for (const [tag, count] of top) lines.push(`  ${tag} (${count})`);
+  return lines.join("\n");
+}
+
+function formatByKind(kind, data) {
+  switch (kind) {
+    case "tree":
+      return formatRecall(data);
+    case "moments":
+      return formatMomentList(data);
+    case "stats":
+      return formatStats(data);
+    case "tags":
+      return formatTags(data);
+    case "write_receipt":
+      return `Written. ID: ${data.id || "?"}`;
+    default:
+      return JSON.stringify(data, null, 2).slice(0, 2000);
   }
-  return JSON.stringify(data, null, 2).slice(0, 2000);
 }
 
 // ── Tool execution ───────────────────────────────
 
+// Substitute {placeholder} segments in a URL path template using the
+// caller's args. Consumed args are returned separately so they don't
+// leak into the body or query string as duplicate fields.
+function applyPathTemplate(pathTemplate, args) {
+  const names = [...pathTemplate.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+  let path = pathTemplate;
+  const consumed = new Set();
+  for (const name of names) {
+    const val = args[name];
+    if (val == null) throw new Error(`missing path param: ${name}`);
+    path = path.replace(`{${name}}`, encodeURIComponent(String(val)));
+    consumed.add(name);
+  }
+  const remaining = {};
+  for (const [k, v] of Object.entries(args)) if (!consumed.has(k)) remaining[k] = v;
+  return { path, remaining };
+}
+
+// Returns a single MCP content block: `{type:"text",text}` or
+// `{type:"image",data,mimeType}`. The CallToolRequestSchema handler
+// wraps it into `{content: [block]}`.
 async function executeTool(toolDef, args) {
-  const { method, path } = toolDef.endpoint;
+  const { method, path: pathTemplate } = toolDef.endpoint;
   const requestMap = toolDef.request_map || {};
+  const { path, remaining } = applyPathTemplate(pathTemplate, args || {});
 
   const mapped = {};
-  for (const [k, v] of Object.entries(args)) {
+  for (const [k, v] of Object.entries(remaining)) {
     if (v == null) continue;
     mapped[requestMap[k] || k] = v;
   }
 
-  let data;
+  let r;
   if (method === "POST") {
-    const r = await fetch(`${API_URL}${path}`, {
+    r = await fetch(`${API_URL}${path}`, {
       method: "POST",
       headers: authHeaders(true),
       body: JSON.stringify(mapped),
     });
-    if (!r.ok) throw new Error(`${r.status} ${r.statusText}`);
-    data = await r.json();
   } else {
     const params = {};
     for (const [k, v] of Object.entries(mapped)) {
       params[k] = Array.isArray(v) ? v.join(",") : String(v);
     }
     const qs = Object.keys(params).length ? "?" + new URLSearchParams(params) : "";
-    const r = await fetch(`${API_URL}${path}${qs}`, { headers: authHeaders(false) });
-    if (!r.ok) throw new Error(`${r.status} ${r.statusText}`);
-    data = await r.json();
+    r = await fetch(`${API_URL}${path}${qs}`, { headers: authHeaders(false) });
   }
+  if (!r.ok) throw new Error(`${r.status} ${r.statusText}`);
+
+  const kind = toolDef.response_kind || "json";
 
-  return formatResponse(path, method, data);
+  if (kind === "image") {
+    const buf = Buffer.from(await r.arrayBuffer());
+    const mimeType = r.headers.get("content-type") || "image/webp";
+    return { type: "image", data: buf.toString("base64"), mimeType };
+  }
+
+  const data = await r.json();
+  return { type: "text", text: formatByKind(kind, data) };
 }
 
 // ── MCP server ───────────────────────────────────
 
+const MCP_SURFACE = "mcp";
+const FALLBACK_INSTRUCTIONS =
+  "You have a Fathom lake of memories. Call remember before answering anything " +
+  "about the past; write when you learn something; read the fathom://crystal " +
+  "resource at the start of every conversation.";
+
+async function fetchInstructions() {
+  try {
+    const r = await fetch(
+      `${API_URL}/v1/agent-instructions?surface=${encodeURIComponent(MCP_SURFACE)}`,
+      { headers: authHeaders(false) }
+    );
+    if (!r.ok) throw new Error(`${r.status} ${r.statusText}`);
+    const data = await r.json();
+    return (data.text || "").trim() || FALLBACK_INSTRUCTIONS;
+  } catch (e) {
+    console.error(`Could not load instructions from ${API_URL}: ${e.message}`);
+    return FALLBACK_INSTRUCTIONS;
+  }
+}
+
 async function main() {
-  // Load tool definitions from the API
+  // Load tool definitions from the API, scoped to the MCP surface so
+  // chat-only tools (rename_session, routines, explain) never appear here.
   let tools = [];
   try {
-    const r = await fetch(`${API_URL}/v1/tools`, { headers: authHeaders(false) });
+    const r = await fetch(`${API_URL}/v1/tools?surface=${encodeURIComponent(MCP_SURFACE)}`, {
+      headers: authHeaders(false),
+    });
     if (!r.ok) throw new Error(`${r.status} ${r.statusText}`);
     const data = await r.json();
     tools = data.tools || [];
@@ -122,14 +200,19 @@ async function main() {
   const toolMap = {};
   for (const t of tools) toolMap[t.name] = t;
 
+  const instructions = await fetchInstructions();
+
   const server = new Server(
     { name: "Fathom", version: "2.1.0" },
-    { capabilities: { tools: {}, resources: {} } },
+    {
+      capabilities: { tools: {}, resources: {} },
+      instructions,
+    }
   );
 
   // Tools — dynamic from /v1/tools
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: tools.map(t => ({
+    tools: tools.map((t) => ({
       name: t.name,
       description: t.description,
       inputSchema: t.parameters || { type: "object", properties: {} },
@@ -143,8 +226,8 @@ async function main() {
       return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
     }
     try {
-      const text = await executeTool(toolDef, args || {});
-      return { content: [{ type: "text", text }] };
+      const block = await executeTool(toolDef, args || {});
+      return { content: [block] };
     } catch (e) {
       return { content: [{ type: "text", text: `Error: ${e.message}` }] };
     }
@@ -156,7 +239,8 @@ async function main() {
       {
         uri: "fathom://crystal",
         name: "Identity Crystal",
-        description: "Fathom's identity — a first-person synthesis of who this mind is. Read this at the start of every conversation for persistent context.",
+        description:
+          "Fathom's identity — a first-person synthesis of who this mind is. Read this at the start of every conversation for persistent context.",
         mimeType: "text/plain",
       },
     ],
@@ -172,20 +256,26 @@ async function main() {
           const text = data.text || "No crystal generated yet.";
           const created = data.created_at || "unknown";
           return {
-            contents: [{
-              uri,
-              mimeType: "text/plain",
-              text: `Identity crystal (crystallized ${created}):\n\n${text}`,
-            }],
+            contents: [
+              {
+                uri,
+                mimeType: "text/plain",
+                text: `Identity crystal (crystallized ${created}):\n\n${text}`,
+              },
+            ],
           };
         }
-      } catch {}
+      } catch {
+        /* fall through to the "no crystal" fallback below */
+      }
       return {
-        contents: [{
-          uri,
-          mimeType: "text/plain",
-          text: "No identity crystal available. Generate one from the Fathom dashboard.",
-        }],
+        contents: [
+          {
+            uri,
+            mimeType: "text/plain",
+            text: "No identity crystal available. Generate one from the Fathom dashboard.",
+          },
+        ],
       };
     }
     throw new Error(`Unknown resource: ${uri}`);
@@ -195,7 +285,7 @@ async function main() {
   await server.connect(transport);
 }
 
-main().catch(e => {
+main().catch((e) => {
   console.error(e);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-mcp",
-  "version": "2.1.0",
+  "version": "2.2.2",
   "description": "Connect any MCP host to your Fathom memory lake",
   "bin": {
     "fathom-mcp": "index.js"