screenpipe-mcp 0.18.1 → 0.18.4

package/src/index.ts

@@ -31,16 +31,20 @@ const SCREENPIPE_API = `http://localhost:${port}`;
 // Discover the local API key, in priority order:
 //
 //   1. env vars set by the launcher (Claude Desktop config, terminal, etc.)
-//   2. direct sqlite3 read of ~/.screenpipe/db.sqlite (plaintext entries only —
-//      encrypted ones need keychain, handled by 3+)
-//   3. bundled `bun` shipped with the desktop app → `bun x screenpipe@latest auth token`
-//      this is the kill-shot for Claude-Desktop-via-MCP: Claude strips PATH so
-//      `npx` and `sqlite3` lookups fail, but the desktop app's bundled bun is
-//      at a deterministic path. We invoke it with an absolute path, which
-//      then runs the screenpipe CLI's `auth token` command — which goes
-//      through `find_api_auth_key` (handles the encrypted-secret-store case).
-//   4. node-adjacent npx (legacy fallback for users without the desktop app)
-//   5. PATH-based npx (very last resort)
+//   2. CLI via bundled `bun` from screenpipe.app at a deterministic absolute
+//      path. Runs `bun x screenpipe@latest auth token` → goes through the
+//      Rust CLI's `find_api_auth_key` resolver, which handles the encrypted
+//      keychain-backed secret store. This is the canonical path: same
+//      contract as `screenpipe auth token` in a terminal, no PATH needed.
+//   3. CLI via node-adjacent npx — for dev environments that have node but
+//      not the desktop app.
+//   4. CLI via PATH-based npx — last CLI fallback.
+//   5. Direct sqlite3 read of ~/.screenpipe/db.sqlite — plaintext entries
+//      only (encrypted entries need the keychain, which only the CLI can
+//      reach). Kept as a final last-resort for users who have screenpipe
+//      *data* but no working CLI install (rare). Demoted below the CLI
+//      paths because it reimplements logic that lives in `auth_key.rs` and
+//      can silently drift on storage-format changes.
 //
 // If all 5 miss we log a loud stderr warning so it surfaces in the host's
 // MCP log instead of the user just seeing 403s with no explanation.
@@ -57,58 +61,14 @@ function discoverApiKey(): string {
   // eslint-disable-next-line @typescript-eslint/no-var-requires
   const { execFileSync, execSync } = require("child_process");
 
-  // Common absolute paths for `sqlite3`. Claude Desktop's MCP launcher
-  // strips PATH so the bare command name `sqlite3` would fail spawn
-  // even though `/usr/bin/sqlite3` is always present on macOS. Try the
-  // bare name first (cheap; works on dev machines with a normal shell)
-  // then walk known absolute paths.
-  const sqliteCandidates: string[] =
-    process.platform === "win32"
-      ? ["sqlite3.exe", "C\\:Windows\\System32\\sqlite3.exe"]
-      : process.platform === "darwin"
-      ? ["sqlite3", "/usr/bin/sqlite3", "/opt/homebrew/bin/sqlite3", "/usr/local/bin/sqlite3"]
-      : ["sqlite3", "/usr/bin/sqlite3", "/usr/local/bin/sqlite3"];
-
-  // 2. Direct sqlite3 read of the secret store. Only succeeds for
-  //    plaintext entries (nonce all zeros). Encrypted entries fall
-  //    through to the CLI path which can decrypt via keychain.
-  try {
-    const dbPath = path.join(os.homedir(), ".screenpipe", "db.sqlite");
-    if (fs.existsSync(dbPath)) {
-      let row: string | null = null;
-      for (const candidate of sqliteCandidates) {
-        try {
-          row = execFileSync(
-            candidate,
-            [dbPath, "SELECT hex(nonce), value FROM secrets WHERE key = 'api_auth_key';"],
-            { timeout: 5000, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
-          ).trim();
-          break;
-        } catch {
-          // try next candidate
-        }
-      }
-      if (row) {
-        const sepIdx = row.indexOf("|");
-        const nonceHex = sepIdx >= 0 ? row.substring(0, sepIdx) : "";
-        const value = sepIdx >= 0 ? row.substring(sepIdx + 1) : row;
-        const isPlaintext = !nonceHex || /^0+$/.test(nonceHex);
-        if (isPlaintext && value) {
-          const decoded = Buffer.from(value, "base64").toString("utf-8");
-          if (decoded && decoded.startsWith("sp-")) return decoded;
-          if (value.startsWith("sp-")) return value;
-        }
-        // Non-zero nonce = encrypted — fall through to bun/npx which decrypt via keychain.
-      }
-    }
-  } catch {}
-
-  // 3. Bundled `bun` shipped with the desktop app. The Tauri externalBin
-  //    config (apps/screenpipe-app-tauri/src-tauri/tauri.prod.conf.json)
-  //    places it next to the main app executable; on each OS the install
-  //    path is deterministic so we don't need PATH or current_exe — both
-  //    of which Claude Desktop's MCP launcher rolls back.
   const home = os.homedir();
+
+  // 2. CLI via bundled `bun` shipped with the desktop app. The Tauri
+  //    externalBin config places `bun` next to the main app exe at a
+  //    deterministic install path on each OS, so we don't need PATH —
+  //    which Claude Desktop's MCP launcher strips. The CLI's `auth
+  //    token` goes through `find_api_auth_key` and decrypts via
+  //    keychain when needed.
   const bunCandidates: string[] =
     process.platform === "darwin"
       ? [
@@ -146,9 +106,8 @@ function discoverApiKey(): string {
     }
   }
 
-  // 4. npx adjacent to the running node — works in dev environments
-  //    where the user installed @screenpipe/mcp via npx without the
-  //    desktop app.
+  // 3. CLI via npx adjacent to the running node. Works for dev
+  //    environments without the desktop app.
   try {
     const npxName = process.platform === "win32" ? "npx.cmd" : "npx";
     const npxPath = path.join(path.dirname(process.execPath), npxName);
@@ -162,8 +121,8 @@ function discoverApiKey(): string {
     }
   } catch {}
 
-  // 5. PATH-based npx — last-ditch. Will fail under Claude Desktop's
-  //    sanitized env; useful only on raw shells.
+  // 4. CLI via PATH-based npx. Last CLI try; works on raw shells with
+  //    npx on PATH.
   try {
     const token = execSync("npx screenpipe@latest auth token", {
       timeout: 30000,
@@ -173,6 +132,48 @@ function discoverApiKey(): string {
     if (token && token.startsWith("sp-")) return token;
   } catch {}
 
+  // 5. Direct sqlite3 read of the secret store (last-resort). Plaintext
+  //    entries only — encrypted ones live behind the keychain, which the
+  //    CLI paths above already cover. Used when the user has screenpipe
+  //    data on disk but no working CLI install.
+  const sqliteCandidates: string[] =
+    process.platform === "win32"
+      ? ["sqlite3.exe", "C:\\Windows\\System32\\sqlite3.exe"]
+      : process.platform === "darwin"
+      ? ["sqlite3", "/usr/bin/sqlite3", "/opt/homebrew/bin/sqlite3", "/usr/local/bin/sqlite3"]
+      : ["sqlite3", "/usr/bin/sqlite3", "/usr/local/bin/sqlite3"];
+  try {
+    const dbPath = path.join(home, ".screenpipe", "db.sqlite");
+    if (fs.existsSync(dbPath)) {
+      let row: string | null = null;
+      for (const candidate of sqliteCandidates) {
+        try {
+          row = execFileSync(
+            candidate,
+            [dbPath, "SELECT hex(nonce), value FROM secrets WHERE key = 'api_auth_key';"],
+            { timeout: 5000, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
+          ).trim();
+          break;
+        } catch {
+          // try next candidate
+        }
+      }
+      if (row) {
+        const sepIdx = row.indexOf("|");
+        const nonceHex = sepIdx >= 0 ? row.substring(0, sepIdx) : "";
+        const value = sepIdx >= 0 ? row.substring(sepIdx + 1) : row;
+        const isPlaintext = !nonceHex || /^0+$/.test(nonceHex);
+        if (isPlaintext && value) {
+          const decoded = Buffer.from(value, "base64").toString("utf-8");
+          if (decoded && decoded.startsWith("sp-")) return decoded;
+          if (value.startsWith("sp-")) return value;
+        }
+        // Encrypted — only the CLI paths above can decrypt this; we
+        // already tried them.
+      }
+    }
+  } catch {}
+
   // All five paths missed. Log loudly to stderr so the host's MCP
   // panel surfaces this instead of the user seeing cryptic 403s from
   // the screenpipe server on every tool call.
@@ -180,9 +181,9 @@ function discoverApiKey(): string {
     [
       "[screenpipe-mcp] could not discover SCREENPIPE_LOCAL_API_KEY from any source.",
       "  - env vars (SCREENPIPE_LOCAL_API_KEY / SCREENPIPE_API_KEY) not set",
-      "  - direct sqlite3 read of ~/.screenpipe/db.sqlite failed",
       "  - bundled `bun` from screenpipe.app not found at any known install path",
       "  - npx fallback unavailable",
+      "  - direct sqlite3 read of ~/.screenpipe/db.sqlite failed",
       "Fix: set SCREENPIPE_LOCAL_API_KEY in your MCP launcher's env block,",
       "or install the screenpipe desktop app (https://screenpi.pe).",
       "",
@@ -193,6 +194,49 @@ function discoverApiKey(): string {
 
 const API_KEY = discoverApiKey();
 
+// Enterprise team token — when present, this MCP additionally registers
+// `team-*` tools that query the org-wide telemetry control plane
+// (https://screenpi.pe/api/enterprise/v1/*) instead of just the local
+// recordings. Same audience: an enterprise admin running screenpipe-mcp
+// inside Claude Desktop / Cursor / Windsurf wants to ask "what did MY
+// machine do" AND "what did MY TEAM do" without juggling two MCPs.
+//
+// Resolution order matches discoverApiKey() in spirit:
+//   1. SCREENPIPE_ENTERPRISE_TOKEN env var (Claude config, terminal)
+//   2. team_api_token field in ~/.screenpipe/enterprise.json (written by
+//      the desktop app's Settings → Privacy → Admin Team API Token)
+//
+// Token format is `sk_ent_…`. Empty / missing → team tools are not
+// registered; non-admin users of screenpipe-mcp see exactly what they
+// see today.
+function discoverTeamToken(): string {
+  const envTok = process.env.SCREENPIPE_ENTERPRISE_TOKEN;
+  if (envTok && envTok.startsWith("sk_ent_")) return envTok;
+  try {
+    const entPath = path.join(os.homedir(), ".screenpipe", "enterprise.json");
+    if (fs.existsSync(entPath)) {
+      const raw = fs.readFileSync(entPath, "utf-8");
+      const parsed = JSON.parse(raw);
+      const tok = typeof parsed?.team_api_token === "string" ? parsed.team_api_token : "";
+      if (tok && tok.startsWith("sk_ent_")) return tok;
+    }
+  } catch {}
+  return "";
+}
+
+const TEAM_TOKEN = discoverTeamToken();
+const TEAM_API = "https://screenpi.pe/api/enterprise/v1";
+
+async function fetchTeam(p: string, init: RequestInit = {}): Promise<Response> {
+  return fetch(`${TEAM_API}${p}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${TEAM_TOKEN}`,
+      ...(init.headers || {}),
+    },
+  });
+}
+
 // Read version from package.json (single source of truth)
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const PKG_VERSION: string = require("../package.json").version;
@@ -218,11 +262,11 @@ const TOOLS: Tool[] = [
   {
     name: "search-content",
     description:
-      "Search screen text, audio transcriptions, input events, and memories. " +
-      "Returns timestamped results with app context. " +
-      "IMPORTANT: prefer activity-summary for broad questions ('what was I doing?'). " +
-      "Use search-content only when you need specific text/content. " +
-      "Start with limit=5, increase only if needed. Results can be large — use max_content_length=500 to truncate.",
+      "Search screen text, audio transcriptions, input events, and memories. Returns timestamped results with app context. " +
+      "USE WHEN: you need the actual text/content of a moment — quotes, OCR snippets, transcript lines — or want to filter by speaker/window. " +
+      "DO NOT USE for: broad questions like 'what was I doing?' (use activity-summary, it pre-summarizes apps + windows + transcripts). " +
+      "Also DO NOT USE for: targeted UI controls (use search-elements). " +
+      "Start with limit=5, increase only if needed. Per-result text is auto-truncated to 1000 chars; pass max_content_length=0 to opt out, or a custom integer to override.",
     annotations: { title: "Search Content", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     inputSchema: {
       type: "object",
@@ -234,14 +278,15 @@ const TOOLS: Tool[] = [
         content_type: {
           type: "string",
           enum: ["all", "ocr", "audio", "input", "accessibility", "memory"],
-          description: "Filter by content type. 'accessibility' is preferred for screen text (OS-native). 'ocr' is fallback for apps without accessibility support. Default: 'all'.",
+          description:
+            "Filter by content type. NOTE on screen text: 'ocr' is a legacy label — it returns ALL screen-text rows, which are accessibility-derived for most apps (the result tag [Screen·a11y] vs [Screen·ocr] tells you which). Use 'ocr' for screen text (covers both paths), 'audio' for transcriptions, 'input' for keyboard/mouse events, 'memory' for stored facts. Default: 'all'.",
           default: "all",
         },
         limit: { type: "integer", description: "Max results (default 10, max 20). Start with 5 for exploration.", default: 10 },
         offset: { type: "integer", description: "Pagination offset. Use when results say 'use offset=N for more'.", default: 0 },
         start_time: {
           type: "string",
-          description: "ISO 8601 UTC or relative (e.g. '2h ago', '1d ago'). Always provide to avoid scanning entire history.",
+          description: "Accepted: ISO 8601 ('2024-01-15T10:00:00Z'), 'Nh ago' / 'Nd ago' / 'Nw ago', 'now', 'yesterday', 'today', or bare 'YYYY-MM-DD'. Always provide to avoid scanning entire history.",
         },
         end_time: {
           type: "string",
@@ -285,9 +330,9 @@ const TOOLS: Tool[] = [
     name: "activity-summary",
     description:
       "Rich activity overview: app usage, window/tab titles with URLs and time spent, key text per context, audio transcriptions. " +
-      "USE THIS FIRST for broad questions: 'what was I doing?', 'how long on X?', 'which apps?'. " +
-      "The 'windows' field shows exactly what the user worked on (e.g. 'Debug crash issue — 20 min', 'Stripe pricing page — 5 min'). " +
-      "Usually sufficient without further searches.",
+      "USE WHEN: any broad question about what the user did — 'what was I doing?', 'how long on X?', 'which apps?', 'recap my morning'. " +
+      "This is almost always the right first call for time-range questions — usually sufficient without follow-up searches. " +
+      "DO NOT USE for: finding a specific keyword (use keyword-search) or a specific UI control (use search-elements).",
     annotations: { title: "Activity Summary", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     inputSchema: {
       type: "object",
@@ -302,9 +347,9 @@ const TOOLS: Tool[] = [
   {
     name: "search-elements",
     description:
-      "Search UI elements (buttons, links, text fields) from the accessibility tree. " +
-      "Lighter than search-content for targeted UI lookups. " +
-      "Use when you need to find specific UI controls or page structure, not general content.",
+      "Search UI elements (buttons, links, text fields) from the accessibility tree, filterable by role. " +
+      "USE WHEN: you want a specific UI control or page-structure question — 'find every Submit button I saw', 'list the links in that page'. " +
+      "DO NOT USE for: general text/content (use search-content) or fast keyword lookup (use keyword-search).",
     annotations: { title: "Search Elements", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     inputSchema: {
       type: "object",
@@ -552,19 +597,21 @@ const TOOLS: Tool[] = [
   {
     name: "keyword-search",
     description:
-      "Fast keyword search using FTS index. Faster than search-content for exact keyword matching. " +
-      "Returns frame IDs and matched text.",
+      "Fast FTS5 keyword search across OCR + audio combined. Returns matches with frame_id, app, timestamp, and text positions. " +
+      "USE WHEN: you have a specific keyword/phrase and want the fastest hit-list (e.g. 'find every screen where I typed \"stripe\"'). " +
+      "DO NOT USE for: structured filters by content_type / speaker / window — this endpoint ignores those (use search-content instead). " +
+      "DO NOT USE for: broad questions like 'what was I doing' (use activity-summary).",
     annotations: { title: "Keyword Search", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     inputSchema: {
       type: "object",
       properties: {
-        q: { type: "string", description: "Keyword search query" },
-        content_type: { type: "string", enum: ["ocr", "audio", "all"], description: "Content type filter", default: "all" },
-        start_time: { type: "string", description: "ISO 8601 UTC or relative" },
-        end_time: { type: "string", description: "ISO 8601 UTC or relative" },
-        app_name: { type: "string", description: "Filter by app name" },
+        q: { type: "string", description: "Keyword query (FTS5 syntax: quoted phrases, AND/OR, prefix*)" },
+        start_time: { type: "string", description: "ISO 8601 UTC, 'Nh ago' / 'Nd ago' / 'Nw ago', 'now', 'yesterday', 'today', or 'YYYY-MM-DD'" },
+        end_time: { type: "string", description: "Same formats as start_time" },
+        app_name: { type: "string", description: "Filter by exact app name (case-sensitive, e.g. 'Google Chrome')" },
         limit: { type: "integer", description: "Max results (default 20)", default: 20 },
         offset: { type: "integer", description: "Pagination offset", default: 0 },
+        fuzzy_match: { type: "boolean", description: "Enable typo-tolerant matching", default: false },
       },
       required: ["q"],
     },
@@ -597,8 +644,74 @@ const TOOLS: Tool[] = [
   },
 ];
 
+// ---------------------------------------------------------------------------
+// Enterprise team tools — registered only when a team API token is present.
+// Same endpoint surface as the desktop `screenpipe-team` pi-agent skill:
+// proxy GETs to https://screenpi.pe/api/enterprise/v1/* with Bearer auth.
+//
+// Naming convention: every team tool is `team-*` so it's obvious at a glance
+// which scope (just-me vs the-whole-org) any given call is hitting.
+// ---------------------------------------------------------------------------
+const TEAM_TOOLS: Tool[] = [
+  {
+    name: "team-search",
+    description:
+      "Substring-search across the ENTIRE ORG's telemetry (every enrolled " +
+      "device). Use when the question is about the team or another teammate " +
+      "(\"what did engineering work on yesterday\", \"did alice touch the auth code\"). " +
+      "For your own machine only, use search-content. " +
+      "Auth: enterprise admin token (sk_ent_…). " +
+      "Defaults: since=now-24h, limit=50. Returns matched records with device + timestamp.",
+    annotations: { title: "Team Search", readOnlyHint: true, openWorldHint: true, idempotentHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "Substring to match (case-insensitive). Empty = all records in window." },
+        device_id: { type: "string", description: "Restrict to one device. Get the ID from team-devices." },
+        app_name: { type: "string", description: "Restrict to records whose app_name equals this (case-insensitive)." },
+        since: { type: "string", description: "ISO 8601 lower bound. Default = now - 24h." },
+        until: { type: "string", description: "ISO 8601 upper bound. Default = now." },
+        since_hours_ago: { type: "integer", description: "Convenience: equivalent to since=now-N*h." },
+        limit: { type: "integer", description: "Max records (default 50, max 200).", default: 50 },
+      },
+    },
+  },
+  {
+    name: "team-devices",
+    description:
+      "List all devices enrolled under this org's license — hostname, OS, " +
+      "app version, last-seen timestamp. Use to discover device IDs to pass " +
+      "to team-search or team-records, or to spot stale machines.",
+    annotations: { title: "Team Devices", readOnlyHint: true, openWorldHint: true, idempotentHint: true },
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "team-records",
+    description:
+      "Chronological raw dump of the org's telemetry for a time window. " +
+      "Returns oldest → newest (vs team-search which is recency-ranked). " +
+      "Use for ETL or \"walk me through X from Y to Z\" — NOT for question-answering, use team-search for that. " +
+      "Auth: enterprise admin token.",
+    annotations: { title: "Team Records", readOnlyHint: true, openWorldHint: true, idempotentHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        device_id: { type: "string", description: "Restrict to one device (optional)." },
+        kind: { type: "string", enum: ["frame", "audio", "all"], description: "Record kind filter. Default: all.", default: "all" },
+        since: { type: "string", description: "ISO 8601 lower bound." },
+        until: { type: "string", description: "ISO 8601 upper bound." },
+        since_hours_ago: { type: "integer", description: "Convenience: equivalent to since=now-N*h." },
+        limit: { type: "integer", description: "Max records (default 50, max 200).", default: 50 },
+      },
+    },
+  },
+];
+
 server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return { tools: TOOLS };
+  // Team tools only surface when an enterprise token was discovered at boot.
+  // No token = consumer / non-admin user; their MCP looks identical to today.
+  const tools = TEAM_TOKEN ? [...TOOLS, ...TEAM_TOOLS] : TOOLS;
+  return { tools };
 });
 
 // ---------------------------------------------------------------------------
@@ -685,7 +798,7 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 - **Use max_content_length=500** to keep responses compact
 - **Don't use q for audio** — transcriptions are noisy, q filters too aggressively. Search audio by time range and speaker instead
 - **app_name is case-sensitive** — use exact names: "Google Chrome" not "chrome"
-- **content_type=accessibility is preferred** for screen text (OS-native). ocr is fallback for apps without accessibility support
+- **Screen text is mostly accessibility-derived, not OCR.** Screenpipe walks the OS accessibility tree first; OCR is only a fallback (terminals, canvas-rendered apps, games). \`content_type=ocr\` returns both paths — the result label \`[Screen·a11y]\` vs \`[Screen·ocr]\` tells you which produced the row. Don't pre-filter to a11y/ocr unless you specifically need one or the other
 
 ## Common Patterns
 
@@ -711,21 +824,154 @@ Never fabricate IDs or timestamps — only use values from actual results.
 });
 
 // ---------------------------------------------------------------------------
-// Helper
+// Helpers
 // ---------------------------------------------------------------------------
+
+// Thrown by fetchAPI / callAPI when the backend is unreachable. Caught in the
+// tool dispatcher to surface an actionable hint ("backend not running")
+// instead of the opaque "fetch failed" the model used to see.
+class BackendDownError extends Error {
+  constructor(public readonly cause: unknown) {
+    super(
+      `screenpipe backend not running on ${SCREENPIPE_API}. ` +
+        `Start it with \`screenpipe\` in a terminal, or open the screenpipe desktop app.`,
+    );
+    this.name = "BackendDownError";
+  }
+}
+
+// Thrown when the backend returns a non-2xx. Carries the server's response
+// body so the dispatcher can include it in the user-visible error message.
+class BackendHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly bodyText: string,
+    endpoint: string,
+  ) {
+    let hint = "";
+    if (status === 401 || status === 403) {
+      hint =
+        " — API key not accepted. Set SCREENPIPE_LOCAL_API_KEY in your MCP " +
+        "launcher env, or install the screenpipe desktop app so the MCP can " +
+        "discover the key automatically.";
+    } else if (status === 404) {
+      hint =
+        " — endpoint not found. The backend may be on a different version than this MCP.";
+    } else if (status === 400) {
+      hint = " — bad request. Check argument names and types against the tool schema.";
+    } else if (status >= 500) {
+      hint = " — backend error. Check screenpipe logs.";
+    }
+    const trimmed = bodyText.trim().slice(0, 300);
+    const bodyPart = trimmed ? ` body: ${trimmed}` : "";
+    super(`HTTP ${status} from ${endpoint}${hint}${bodyPart}`);
+    this.name = "BackendHttpError";
+  }
+}
+
 async function fetchAPI(
   endpoint: string,
   options: RequestInit = {}
 ): Promise<Response> {
   const url = `${SCREENPIPE_API}${endpoint}`;
-  return fetch(url, {
-    ...options,
-    headers: {
-      "Content-Type": "application/json",
-      ...(API_KEY ? { Authorization: `Bearer ${API_KEY}` } : {}),
-      ...options.headers,
-    },
-  });
+  try {
+    return await fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...(API_KEY ? { Authorization: `Bearer ${API_KEY}` } : {}),
+        ...options.headers,
+      },
+    });
+  } catch (e) {
+    throw new BackendDownError(e);
+  }
+}
+
+// Wrap a fetchAPI call: throw BackendHttpError on non-2xx with body included.
+// Use from handlers instead of `if (!response.ok) throw new Error(...)`.
+async function callAPI(endpoint: string, options: RequestInit = {}): Promise<Response> {
+  const response = await fetchAPI(endpoint, options);
+  if (!response.ok) {
+    let body = "";
+    try {
+      body = await response.text();
+    } catch {
+      // body may not be readable; that's fine
+    }
+    throw new BackendHttpError(response.status, body, endpoint);
+  }
+  return response;
+}
+
+// Server's deserialize_flexible_datetime accepts ISO 8601 + "Nh ago" / "Nd ago"
+// / "Nw ago" / "now". Models also try "yesterday", "today", and bare dates
+// ("2026-05-17") — normalize those here so the request doesn't 400.
+function normalizeTime(input: string | undefined): string | undefined {
+  if (!input) return input;
+  const s = input.trim();
+  if (!s) return input;
+  const lower = s.toLowerCase();
+  if (lower === "yesterday") return "1d ago";
+  if (lower === "today") {
+    return `${new Date().toISOString().split("T")[0]}T00:00:00Z`;
+  }
+  if (lower === "tomorrow") {
+    const t = new Date();
+    t.setUTCDate(t.getUTCDate() + 1);
+    return `${t.toISOString().split("T")[0]}T00:00:00Z`;
+  }
+  // Bare YYYY-MM-DD → start of day UTC
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return `${s}T00:00:00Z`;
+  return s;
+}
+
+// Apply normalizeTime to start_time/end_time fields in an args object.
+// Returns a new object — does not mutate the input.
+function normalizeTimeFields(
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const out = { ...args };
+  for (const k of ["start_time", "end_time"] as const) {
+    if (typeof out[k] === "string") {
+      out[k] = normalizeTime(out[k] as string);
+    }
+  }
+  return out;
+}
+
+// Middle-truncate long strings: keep head + tail, mark the gap with how much
+// was cut. Used to cap OCR/transcription text in search-content responses
+// so a single call doesn't blow past Claude Code's per-tool output limit
+// (one logged call returned 131k chars from a limit:10 search).
+function truncateMiddle(text: string | null | undefined, max: number): string {
+  if (!text) return text ?? "";
+  if (max <= 0 || text.length <= max) return text;
+  const halfLeft = Math.floor(max / 2);
+  const halfRight = max - halfLeft;
+  const cut = text.length - max;
+  return (
+    text.slice(0, halfLeft) +
+    `…[${cut} chars truncated — pass max_content_length=0 for full text]…` +
+    text.slice(text.length - halfRight)
+  );
+}
+
+// Default per-result text cap for search-content when the caller didn't
+// specify one. Tuned to keep limit=10 responses well under tool-output limits
+// while still giving the model enough text to reason over.
+const DEFAULT_SEARCH_CONTENT_TRUNCATE = 1000;
+
+// Format the screen-text tag for a result. The server's `text_source` is
+// "accessibility" (OS-native tree, primary path) or "ocr" (fallback for
+// terminals, canvas, weak a11y). Older rows have no text_source, so we
+// fall back to a bare `[Screen]`. The result type is historically called
+// OCR in the engine but most captures are accessibility-derived — surface
+// the actual source so the model picks filters correctly.
+function screenTag(textSource: unknown): string {
+  if (textSource === "accessibility") return "[Screen·a11y]";
+  if (textSource === "ocr") return "[Screen·ocr]";
+  return "[Screen]";
 }
 
 // ---------------------------------------------------------------------------
@@ -742,16 +988,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     switch (name) {
       case "search-content": {
         const includeFrames = args.include_frames === true;
+        const normalized = normalizeTimeFields(args);
+        // Default text cap if the caller didn't pass max_content_length.
+        // Keeps single calls under Claude Code's per-tool output limit.
+        const userCap = normalized.max_content_length;
+        const effectiveCap =
+          typeof userCap === "number"
+            ? userCap
+            : userCap === undefined
+            ? DEFAULT_SEARCH_CONTENT_TRUNCATE
+            : Number(userCap);
         const params = new URLSearchParams();
-        for (const [key, value] of Object.entries(args)) {
+        for (const [key, value] of Object.entries(normalized)) {
           if (value !== null && value !== undefined) {
             params.append(key, String(value));
           }
         }
 
-        const response = await fetchAPI(`/search?${params.toString()}`);
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
-
+        const response = await callAPI(`/search?${params.toString()}`);
         const data = await response.json();
         const results = data.data || [];
         const pagination = data.pagination || {};
@@ -781,10 +1035,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
           if (result.type === "OCR") {
             const tagsStr = content.tags?.length ? `\nTags: ${content.tags.join(", ")}` : "";
+            // result.type is "OCR" by historical naming, but content.text_source
+            // tells us if the text actually came from the accessibility tree
+            // (primary path) or OCR (fallback). Use it to label honestly.
+            const tag = screenTag(content.text_source);
             formattedResults.push(
-              `[OCR] ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
+              `${tag} ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
                 `${content.timestamp || ""}\n` +
-                `${content.text || ""}` +
+                `${truncateMiddle(content.text || "", effectiveCap)}` +
                 tagsStr
             );
             if (includeFrames && content.frame) {
@@ -798,14 +1056,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             formattedResults.push(
               `[Audio] ${content.device_name || "?"}\n` +
                 `${content.timestamp || ""}\n` +
-                `${content.transcription || ""}` +
+                `${truncateMiddle(content.transcription || "", effectiveCap)}` +
                 tagsStr
             );
           } else if (result.type === "UI" || result.type === "Accessibility") {
             formattedResults.push(
               `[Accessibility] ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
                 `${content.timestamp || ""}\n` +
-                `${content.text || ""}`
+                `${truncateMiddle(content.text || "", effectiveCap)}`
             );
           } else if (result.type === "Memory") {
             const tagsStr = content.tags?.length ? ` [${content.tags.join(", ")}]` : "";
@@ -814,7 +1072,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             formattedResults.push(
               `[Memory #${content.id}]${tagsStr}${importance}\n` +
                 `${content.created_at || ""}\n` +
-                `${content.content || ""}`
+                `${truncateMiddle(content.content || "", effectiveCap)}`
             );
           }
         }
@@ -839,15 +1097,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "list-meetings": {
+        const normalized = normalizeTimeFields(args);
         const params = new URLSearchParams();
-        for (const [key, value] of Object.entries(args)) {
+        for (const [key, value] of Object.entries(normalized)) {
           if (value !== null && value !== undefined) {
             params.append(key, String(value));
           }
         }
 
-        const response = await fetchAPI(`/meetings?${params.toString()}`);
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI(`/meetings?${params.toString()}`);
 
         const meetings = await response.json();
 
@@ -874,15 +1132,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "activity-summary": {
+        const normalized = normalizeTimeFields(args);
         const params = new URLSearchParams();
-        for (const [key, value] of Object.entries(args)) {
+        for (const [key, value] of Object.entries(normalized)) {
           if (value !== null && value !== undefined) {
             params.append(key, String(value));
           }
         }
 
-        const response = await fetchAPI(`/activity-summary?${params.toString()}`);
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI(`/activity-summary?${params.toString()}`);
 
         const data = await response.json();
 
@@ -957,15 +1215,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "search-elements": {
+        const normalized = normalizeTimeFields(args);
         const params = new URLSearchParams();
-        for (const [key, value] of Object.entries(args)) {
+        for (const [key, value] of Object.entries(normalized)) {
           if (value !== null && value !== undefined) {
             params.append(key, String(value));
           }
         }
 
-        const response = await fetchAPI(`/elements?${params.toString()}`);
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI(`/elements?${params.toString()}`);
 
         const data = await response.json();
         const elements = data.data || [];
@@ -1016,8 +1274,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           return { content: [{ type: "text", text: "Error: frame_id is required" }] };
         }
 
-        const response = await fetchAPI(`/frames/${frameId}/context`);
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI(`/frames/${frameId}/context`);
 
         const data = await response.json();
         const lines = [`Frame ${data.frame_id} (source: ${data.text_source})`];
@@ -1047,8 +1304,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "export-video": {
-        const startTime = args.start_time as string;
-        const endTime = args.end_time as string;
+        const startTime = normalizeTime(args.start_time as string);
+        const endTime = normalizeTime(args.end_time as string);
         const fps = (args.fps as number) || 1.0;
 
         if (!startTime || !endTime) {
@@ -1065,11 +1322,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           limit: "10000",
         });
 
-        const searchResponse = await fetchAPI(`/search?${searchParams.toString()}`);
-        if (!searchResponse.ok) {
-          throw new Error(`Failed to search for frames: HTTP ${searchResponse.status}`);
-        }
-
+        const searchResponse = await callAPI(`/search?${searchParams.toString()}`);
         const searchData = await searchResponse.json();
         const results = searchData.data || [];
 
@@ -1188,9 +1441,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case "update-memory": {
         if (args.delete && args.id) {
-          const response = await fetchAPI(`/memories/${args.id}`, { method: "DELETE" });
-          if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
-          return { content: [{ type: "text", text: `Memory ${args.id} deleted.` }] };
+          const response = await callAPI(`/memories/${args.id}`, { method: "DELETE" });
+            return { content: [{ type: "text", text: `Memory ${args.id} deleted.` }] };
         }
         if (args.id) {
           const body: Record<string, unknown> = {};
@@ -1198,12 +1450,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           if (args.tags !== undefined) body.tags = args.tags;
           if (args.importance !== undefined) body.importance = args.importance;
           if (args.source_context !== undefined) body.source_context = args.source_context;
-          const response = await fetchAPI(`/memories/${args.id}`, {
+          const response = await callAPI(`/memories/${args.id}`, {
             method: "PUT",
             body: JSON.stringify(body),
           });
-          if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
-          const memory = await response.json();
+            const memory = await response.json();
           return {
             content: [{ type: "text", text: `Memory ${memory.id} updated: "${memory.content}"` }],
           };
@@ -1220,11 +1471,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           importance: args.importance ?? 0.5,
         };
         if (args.source_context) memoryBody.source_context = args.source_context;
-        const memoryResponse = await fetchAPI("/memories", {
+        const memoryResponse = await callAPI("/memories", {
           method: "POST",
           body: JSON.stringify(memoryBody),
         });
-        if (!memoryResponse.ok) throw new Error(`HTTP error: ${memoryResponse.status}`);
         const newMemory = await memoryResponse.json();
         return {
           content: [
@@ -1241,12 +1491,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
         if (args.timeout_secs) notifBody.timeout = Number(args.timeout_secs) * 1000;
         if (args.actions) notifBody.actions = args.actions;
-        const notifResponse = await fetch("http://localhost:11435/notify", {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(notifBody),
-        });
-        if (!notifResponse.ok) throw new Error(`HTTP error: ${notifResponse.status}`);
+        // send-notification hits the desktop notify daemon on a separate port
+        // (11435), not the screenpipe API. Keep direct fetch with friendlier
+        // error so the model sees an actionable message if the daemon's down.
+        let notifResponse: Response;
+        try {
+          notifResponse = await fetch("http://localhost:11435/notify", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(notifBody),
+          });
+        } catch (e) {
+          throw new Error(
+            "notification daemon not reachable on localhost:11435 — is the screenpipe desktop app running?",
+          );
+        }
+        if (!notifResponse.ok) {
+          let body = "";
+          try { body = await notifResponse.text(); } catch {}
+          throw new Error(`notify daemon HTTP ${notifResponse.status}${body ? `: ${body.slice(0, 200)}` : ""}`);
+        }
         const notifResult = await notifResponse.json();
         return {
           content: [{ type: "text", text: `Notification sent: ${notifResult.message}` }],
@@ -1254,8 +1518,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "health-check": {
-        const response = await fetchAPI("/health");
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI("/health");
         const data = await response.json();
         return {
           content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -1263,8 +1526,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "list-audio-devices": {
-        const response = await fetchAPI("/audio/list");
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI("/audio/list");
         const devices = await response.json();
         if (!Array.isArray(devices) || devices.length === 0) {
           return { content: [{ type: "text", text: "No audio devices found." }] };
@@ -1279,8 +1541,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "list-monitors": {
-        const response = await fetchAPI("/vision/list");
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI("/vision/list");
         const monitors = await response.json();
         if (!Array.isArray(monitors) || monitors.length === 0) {
           return { content: [{ type: "text", text: "No monitors found." }] };
@@ -1301,11 +1562,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (!contentType || !id || !tags) {
           return { content: [{ type: "text", text: "Error: content_type, id, and tags are required" }] };
         }
-        const response = await fetchAPI(`/tags/${contentType}/${id}`, {
+        const response = await callAPI(`/tags/${contentType}/${id}`, {
           method: "POST",
           body: JSON.stringify({ tags }),
         });
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
         return {
           content: [{ type: "text", text: `Tags added to ${contentType}/${id}: ${tags.join(", ")}` }],
         };
@@ -1316,8 +1576,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (!nameQuery) {
           return { content: [{ type: "text", text: "Error: name is required" }] };
         }
-        const response = await fetchAPI(`/speakers/search?name=${encodeURIComponent(nameQuery)}`);
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI(`/speakers/search?name=${encodeURIComponent(nameQuery)}`);
         const speakers = await response.json();
         if (!Array.isArray(speakers) || speakers.length === 0) {
           return { content: [{ type: "text", text: "No speakers found." }] };
@@ -1334,8 +1593,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "list-unnamed-speakers": {
         const limit = (args.limit as number) || 10;
         const offset = (args.offset as number) || 0;
-        const response = await fetchAPI(`/speakers/unnamed?limit=${limit}&offset=${offset}`);
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI(`/speakers/unnamed?limit=${limit}&offset=${offset}`);
         const speakers = await response.json();
         if (!Array.isArray(speakers) || speakers.length === 0) {
           return { content: [{ type: "text", text: "No unnamed speakers found." }] };
@@ -1356,11 +1614,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const body: Record<string, unknown> = { id: speakerId };
         if (args.name !== undefined) body.name = args.name;
         if (args.metadata !== undefined) body.metadata = args.metadata;
-        const response = await fetchAPI("/speakers/update", {
+        const response = await callAPI("/speakers/update", {
           method: "POST",
           body: JSON.stringify(body),
         });
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
         return {
           content: [{ type: "text", text: `Speaker ${speakerId} updated.` }],
         };
@@ -1372,11 +1629,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (!keepId || !mergeId) {
           return { content: [{ type: "text", text: "Error: speaker_to_keep_id and speaker_to_merge_id are required" }] };
         }
-        const response = await fetchAPI("/speakers/merge", {
+        const response = await callAPI("/speakers/merge", {
           method: "POST",
           body: JSON.stringify({ speaker_to_keep_id: keepId, speaker_to_merge_id: mergeId }),
         });
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
         return {
           content: [{ type: "text", text: `Merged speaker ${mergeId} into ${keepId}.` }],
         };
@@ -1387,11 +1643,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (args.app) body.app = args.app;
         if (args.title) body.title = args.title;
         if (args.attendees) body.attendees = args.attendees;
-        const response = await fetchAPI("/meetings/start", {
+        const response = await callAPI("/meetings/start", {
           method: "POST",
           body: JSON.stringify(body),
         });
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
         const meeting = await response.json();
         return {
           content: [{ type: "text", text: `Meeting started (id: ${meeting.id || "ok"}).` }],
@@ -1399,8 +1654,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "stop-meeting": {
-        const response = await fetchAPI("/meetings/stop", { method: "POST" });
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI("/meetings/stop", { method: "POST" });
         return {
           content: [{ type: "text", text: "Meeting stopped." }],
         };
@@ -1411,8 +1665,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (!meetingId) {
           return { content: [{ type: "text", text: "Error: id is required" }] };
         }
-        const response = await fetchAPI(`/meetings/${meetingId}`);
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI(`/meetings/${meetingId}`);
         const meeting = await response.json();
         return {
           content: [{ type: "text", text: JSON.stringify(meeting, null, 2) }],
@@ -1439,12 +1692,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             ],
           };
         }
-        const response = await fetchAPI(`/meetings/${meetingId}`, {
+        const response = await callAPI(`/meetings/${meetingId}`, {
           method: "PATCH",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify(body),
         });
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
         const updated = await response.json();
         return {
           content: [{ type: "text", text: JSON.stringify(updated, null, 2) }],
@@ -1452,22 +1704,52 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "keyword-search": {
-        const params = new URLSearchParams();
-        for (const [key, value] of Object.entries(args)) {
-          if (value !== null && value !== undefined) {
-            params.append(key, String(value));
-          }
+        // Translate model-facing arg names to what the engine actually
+        // accepts (KeywordSearchRequest in routes/search.rs):
+        //   q          -> query    (mandatory; the field is literally named `query`)
+        //   app_name   -> app_names (comma-separated; serde splits it)
+        //   content_type: dropped — the keyword endpoint doesn't filter by type.
+        //                  It searches OCR + audio together via the FTS index.
+        // Without these mappings every keyword-search request 400s (and used
+        // to: in logs, 25/25 calls failed before this fix).
+        const queryStr = (args.query as string) ?? (args.q as string);
+        if (!queryStr) {
+          return {
+            content: [{ type: "text", text: "Error: 'q' (search query) is required" }],
+          };
         }
-        const response = await fetchAPI(`/search/keyword?${params.toString()}`);
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const normalized = normalizeTimeFields(args);
+        const params = new URLSearchParams();
+        params.append("query", queryStr);
+        if (normalized.start_time) params.append("start_time", String(normalized.start_time));
+        if (normalized.end_time) params.append("end_time", String(normalized.end_time));
+        if (normalized.limit !== undefined) params.append("limit", String(normalized.limit));
+        if (normalized.offset !== undefined) params.append("offset", String(normalized.offset));
+        if (normalized.app_name) params.append("app_names", String(normalized.app_name));
+        if (normalized.app_names) params.append("app_names", String(normalized.app_names));
+        if (args.fuzzy_match !== undefined) params.append("fuzzy_match", String(args.fuzzy_match));
+        const response = await callAPI(`/search/keyword?${params.toString()}`);
         const data = await response.json();
-        const results = data.data || [];
+        // /search/keyword returns a bare array (Vec<KeywordSearchMatch> from
+        // routes/search.rs), not the {data, pagination} shape /search uses.
+        // The old `data.data || []` always lost results.
+        const results: Array<Record<string, unknown>> = Array.isArray(data)
+          ? data
+          : (data.data ?? []);
         if (results.length === 0) {
           return { content: [{ type: "text", text: "No keyword search results found." }] };
         }
-        const formatted = results.map((r: Record<string, unknown>) => {
-          const content = r.content as Record<string, unknown> | undefined;
-          return `[${r.type}] ${content?.app_name || "?"} | ${content?.timestamp || ""}\n${content?.text || content?.transcription || ""}`;
+        const formatted = results.map((r) => {
+          // Flat shape from search_with_text_positions: { app_name, frame_id,
+          // timestamp, text, text_source, ... }. Truncate to keep responses
+          // under tool-output limits. text_source is "accessibility" (primary)
+          // or "ocr" (fallback) — show it so the model knows which path hit.
+          const text = (r.text as string) || (r.transcription as string) || "";
+          const tag = screenTag(r.text_source);
+          return (
+            `${tag} [frame:${r.frame_id ?? "?"}] ${r.app_name ?? "?"} | ${r.timestamp ?? ""}\n` +
+            truncateMiddle(text, DEFAULT_SEARCH_CONTENT_TRUNCATE)
+          );
         });
         return {
           content: [{ type: "text", text: `Results: ${results.length}\n\n${formatted.join("\n---\n")}` }],
@@ -1479,8 +1761,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (!frameId) {
           return { content: [{ type: "text", text: "Error: frame_id is required" }] };
         }
-        const response = await fetchAPI(`/frames/${frameId}/elements`);
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        const response = await callAPI(`/frames/${frameId}/elements`);
         const elements = await response.json();
         if (!Array.isArray(elements) || elements.length === 0) {
           return { content: [{ type: "text", text: `No elements found for frame ${frameId}.` }] };
@@ -1507,19 +1788,69 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         else {
           return { content: [{ type: "text", text: `Error: unknown action '${action}'` }] };
         }
-        const response = await fetchAPI(endpoint, { method: "POST" });
-        if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+        await callAPI(endpoint, { method: "POST" });
         return {
           content: [{ type: "text", text: `Recording action '${action}' executed.` }],
         };
       }
 
+      // ---------------------------------------------------------------------
+      // Enterprise team tools — only callable when TEAM_TOKEN is set at boot.
+      // If we got this far without one, the tool wasn't in the listed set the
+      // host saw, but a misbehaving client could still try to call it. Fail
+      // loudly so the host surfaces the misconfiguration.
+      // ---------------------------------------------------------------------
+      case "team-search":
+      case "team-devices":
+      case "team-records": {
+        if (!TEAM_TOKEN) {
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  `team-* tools require an enterprise admin token. Set ` +
+                  `SCREENPIPE_ENTERPRISE_TOKEN in your MCP env, or mint one ` +
+                  `at https://screenpi.pe/enterprise → API Tokens and paste ` +
+                  `it into Settings → Privacy → Admin Team API Token in the ` +
+                  `screenpipe desktop app.`,
+              },
+            ],
+          };
+        }
+        // Map MCP tool name → /api/enterprise/v1 path
+        const subpath =
+          name === "team-search" ? "/search"
+          : name === "team-devices" ? "/devices"
+          : "/records";
+        // Forward every primitive arg as a query param. The server validates;
+        // unknown params are ignored, so we don't need to gatekeep here.
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(args)) {
+          if (v !== null && v !== undefined && v !== "") {
+            params.append(k, String(v));
+          }
+        }
+        const query = params.toString();
+        const response = await fetchTeam(`${subpath}${query ? `?${query}` : ""}`);
+        const body = await response.text();
+        if (!response.ok) {
+          throw new Error(
+            `${name} failed: HTTP ${response.status} ${response.statusText} — ${body.slice(0, 300)}`
+          );
+        }
+        return { content: [{ type: "text", text: body }] };
+      }
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    // isError flags the result as a failure so the model retries with a
+    // different approach instead of treating the error text as data.
     return {
+      isError: true,
       content: [{ type: "text", text: `Error executing ${name}: ${errorMessage}` }],
     };
   }