screenpipe-mcp 0.18.1 → 0.18.4

package/dist/index.js

@@ -56,16 +56,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.
@@ -81,55 +85,13 @@ function discoverApiKey() {
     const fs = require("fs");
     // 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 = 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 = 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 = process.platform === "darwin"
         ? [
             // Standard system-wide install
@@ -168,9 +130,8 @@ function discoverApiKey() {
             // try next candidate
         }
     }
-    // 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);
@@ -185,8 +146,8 @@ function discoverApiKey() {
         }
     }
     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,
@@ -197,15 +158,55 @@ function discoverApiKey() {
             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 = 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 = 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.
     process.stderr.write([
         "[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).",
         "",
@@ -213,6 +214,49 @@ function discoverApiKey() {
     return "";
 }
 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() {
+    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, init = {}) {
+    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 = require("../package.json").version;
@@ -232,11 +276,11 @@ const server = new index_js_1.Server({
 const TOOLS = [
     {
         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.",
+        description: "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",
@@ -248,14 +292,14 @@ const TOOLS = [
                 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",
@@ -297,9 +341,9 @@ const TOOLS = [
     {
         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",
@@ -313,9 +357,9 @@ const TOOLS = [
     },
     {
         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.",
+        description: "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",
@@ -554,19 +598,21 @@ const TOOLS = [
     },
     {
         name: "keyword-search",
-        description: "Fast keyword search using FTS index. Faster than search-content for exact keyword matching. " +
-            "Returns frame IDs and matched text.",
+        description: "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"],
         },
@@ -596,8 +642,70 @@ const TOOLS = [
         },
     },
 ];
+// ---------------------------------------------------------------------------
+// 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 = [
+    {
+        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(types_js_1.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 };
 });
 // ---------------------------------------------------------------------------
 // Resources — dynamic context only (no duplicated reference docs)
@@ -675,7 +783,7 @@ server.setRequestHandler(types_js_1.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
 
@@ -699,18 +807,151 @@ Never fabricate IDs or timestamps — only use values from actual results.
     throw new Error(`Unknown resource: ${uri}`);
 });
 // ---------------------------------------------------------------------------
-// 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 {
+    cause;
+    constructor(cause) {
+        super(`screenpipe backend not running on ${SCREENPIPE_API}. ` +
+            `Start it with \`screenpipe\` in a terminal, or open the screenpipe desktop app.`);
+        this.cause = cause;
+        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 {
+    status;
+    bodyText;
+    constructor(status, bodyText, endpoint) {
+        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.status = status;
+        this.bodyText = bodyText;
+        this.name = "BackendHttpError";
+    }
+}
 async function fetchAPI(endpoint, options = {}) {
     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, options = {}) {
+    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) {
+    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) {
+    const out = { ...args };
+    for (const k of ["start_time", "end_time"]) {
+        if (typeof out[k] === "string") {
+            out[k] = normalizeTime(out[k]);
+        }
+    }
+    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, max) {
+    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) {
+    if (textSource === "accessibility")
+        return "[Screen·a11y]";
+    if (textSource === "ocr")
+        return "[Screen·ocr]";
+    return "[Screen]";
 }
 // ---------------------------------------------------------------------------
 // Tool handlers
@@ -724,15 +965,22 @@ server.setRequestHandler(types_js_1.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 || {};
@@ -755,9 +1003,13 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                         continue;
                     if (result.type === "OCR") {
                         const tagsStr = content.tags?.length ? `\nTags: ${content.tags.join(", ")}` : "";
-                        formattedResults.push(`[OCR] ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
+                        // 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(`${tag} ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
                             `${content.timestamp || ""}\n` +
-                            `${content.text || ""}` +
+                            `${truncateMiddle(content.text || "", effectiveCap)}` +
                             tagsStr);
                         if (includeFrames && content.frame) {
                             images.push({
@@ -770,20 +1022,20 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                         const tagsStr = content.tags?.length ? `\nTags: ${content.tags.join(", ")}` : "";
                         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(", ")}]` : "";
                         const importance = content.importance != null ? ` (importance: ${content.importance})` : "";
                         formattedResults.push(`[Memory #${content.id}]${tagsStr}${importance}\n` +
                             `${content.created_at || ""}\n` +
-                            `${content.content || ""}`);
+                            `${truncateMiddle(content.content || "", effectiveCap)}`);
                     }
                 }
                 const header = `Results: ${results.length}/${pagination.total || "?"}` +
@@ -801,15 +1053,14 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 return { content: contentItems };
             }
             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();
                 if (!Array.isArray(meetings) || meetings.length === 0) {
                     return {
@@ -831,15 +1082,14 @@ server.setRequestHandler(types_js_1.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();
                 const appsLines = (data.apps || []).map((a) => {
                     const timeSpan = a.first_seen && a.last_seen
@@ -880,15 +1130,14 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: summary }] };
             }
             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 || [];
                 const pagination = data.pagination || {};
@@ -921,9 +1170,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 if (!frameId) {
                     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})`];
                 if (data.urls?.length) {
@@ -946,8 +1193,8 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: lines.join("\n") }] };
             }
             case "export-video": {
-                const startTime = args.start_time;
-                const endTime = args.end_time;
+                const startTime = normalizeTime(args.start_time);
+                const endTime = normalizeTime(args.end_time);
                 const fps = args.fps || 1.0;
                 if (!startTime || !endTime) {
                     return {
@@ -961,10 +1208,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                     end_time: endTime,
                     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 || [];
                 if (results.length === 0) {
@@ -1067,9 +1311,7 @@ server.setRequestHandler(types_js_1.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}`);
+                    const response = await callAPI(`/memories/${args.id}`, { method: "DELETE" });
                     return { content: [{ type: "text", text: `Memory ${args.id} deleted.` }] };
                 }
                 if (args.id) {
@@ -1082,12 +1324,10 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                         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();
                     return {
                         content: [{ type: "text", text: `Memory ${memory.id} updated: "${memory.content}"` }],
@@ -1106,12 +1346,10 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
                 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: [
@@ -1129,31 +1367,42 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                     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;
+                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}` }],
                 };
             }
             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) }],
                 };
             }
             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." }] };
@@ -1164,9 +1413,7 @@ server.setRequestHandler(types_js_1.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." }] };
@@ -1183,12 +1430,10 @@ server.setRequestHandler(types_js_1.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(", ")}` }],
                 };
@@ -1198,9 +1443,7 @@ server.setRequestHandler(types_js_1.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." }] };
@@ -1213,9 +1456,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "list-unnamed-speakers": {
                 const limit = args.limit || 10;
                 const offset = args.offset || 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." }] };
@@ -1235,12 +1476,10 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                     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.` }],
                 };
@@ -1251,12 +1490,10 @@ server.setRequestHandler(types_js_1.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}.` }],
                 };
@@ -1269,21 +1506,17 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                     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"}).` }],
                 };
             }
             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." }],
                 };
@@ -1293,9 +1526,7 @@ server.setRequestHandler(types_js_1.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) }],
@@ -1322,36 +1553,68 @@ server.setRequestHandler(types_js_1.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) }],
                 };
             }
             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 ?? args.q;
+                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.isArray(data)
+                    ? data
+                    : (data.data ?? []);
                 if (results.length === 0) {
                     return { content: [{ type: "text", text: "No keyword search results found." }] };
                 }
                 const formatted = results.map((r) => {
-                    const content = r.content;
-                    return `[${r.type}] ${content?.app_name || "?"} | ${content?.timestamp || ""}\n${content?.text || content?.transcription || ""}`;
+                    // 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 || r.transcription || "";
+                    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")}` }],
@@ -1362,9 +1625,7 @@ server.setRequestHandler(types_js_1.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}.` }] };
@@ -1390,20 +1651,64 @@ server.setRequestHandler(types_js_1.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}` }],
         };
     }