screenpipe-mcp 0.8.2 → 0.8.4

package/dist/index.js

@@ -69,7 +69,7 @@ const SCREENPIPE_API = `http://localhost:${port}`;
 // Initialize server
 const server = new index_js_1.Server({
     name: "screenpipe",
-    version: "0.8.2",
+    version: "0.8.3",
 }, {
     capabilities: {
         tools: {},
@@ -81,10 +81,14 @@ const server = new index_js_1.Server({
 const BASE_TOOLS = [
     {
         name: "search-content",
-        description: "Search screenpipe's recorded content: screen text (OCR), audio transcriptions, and UI elements. " +
+        description: "Search screenpipe's recorded content: screen text (accessibility APIs, with OCR fallback), audio transcriptions, and UI elements. " +
             "Returns timestamped results with app context. " +
             "Call with no parameters to get recent activity. " +
             "Use the 'screenpipe://context' resource for current time when building time-based queries.\n\n" +
+            "SEARCH STRATEGY: First search with ONLY time params (start_time/end_time) — no q, no app_name, no content_type. " +
+            "This gives ground truth of what's recorded. Scan results to find correct app_name values, then narrow with filters using exact observed values. " +
+            "App names are case-sensitive and may differ from user input (e.g. 'Discord' vs 'Discord.exe'). " +
+            "The q param searches captured text (accessibility/OCR), NOT app names. NEVER report 'no data' after one filtered search — verify with unfiltered time-only search first.\n\n" +
             "DEEP LINKS: When referencing specific moments, create clickable links using IDs from search results:\n" +
             "- OCR results (PREFERRED): [10:30 AM — Chrome](screenpipe://frame/12345) — use content.frame_id from the result\n" +
             "- Audio results: [meeting at 3pm](screenpipe://timeline?timestamp=2024-01-15T15:00:00Z) — use exact timestamp from result\n" +
@@ -103,7 +107,7 @@ const BASE_TOOLS = [
                 content_type: {
                     type: "string",
                     enum: ["all", "ocr", "audio", "input", "accessibility"],
-                    description: "Content type filter: 'ocr' (screen text), 'audio' (transcriptions), 'input' (clicks, keystrokes, clipboard, app switches), 'accessibility' (accessibility tree text), 'all'. Default: 'all'.",
+                    description: "Content type filter: 'ocr' (screen text via OCR, legacy fallback), 'audio' (transcriptions), 'input' (clicks, keystrokes, clipboard, app switches), 'accessibility' (accessibility tree text, preferred for screen content), 'all'. Default: 'all'.",
                     default: "all",
                 },
                 limit: {
@@ -119,12 +123,12 @@ const BASE_TOOLS = [
                 start_time: {
                     type: "string",
                     format: "date-time",
-                    description: "ISO 8601 UTC start time (e.g., 2024-01-15T10:00:00Z)",
+                    description: "Start time: ISO 8601 UTC (e.g., 2024-01-15T10:00:00Z) or relative (e.g., '16h ago', '2d ago', 'now')",
                 },
                 end_time: {
                     type: "string",
                     format: "date-time",
-                    description: "ISO 8601 UTC end time (e.g., 2024-01-15T18:00:00Z)",
+                    description: "End time: ISO 8601 UTC (e.g., 2024-01-15T18:00:00Z) or relative (e.g., 'now', '1h ago')",
                 },
                 app_name: {
                     type: "string",
@@ -155,6 +159,10 @@ const BASE_TOOLS = [
                     type: "string",
                     description: "Filter audio by speaker name (case-insensitive partial match)",
                 },
+                max_content_length: {
+                    type: "integer",
+                    description: "Truncate each result's text/transcription to this many characters using middle-truncation (keeps first half + last half). Useful for limiting token usage with small-context models.",
+                },
             },
         },
     },
@@ -162,7 +170,7 @@ const BASE_TOOLS = [
         name: "export-video",
         description: "Export a video of screen recordings for a specific time range. " +
             "Creates an MP4 video from the recorded frames between the start and end times.\n\n" +
-            "IMPORTANT: Use ISO 8601 UTC timestamps (e.g., 2024-01-15T10:00:00Z)\n\n" +
+            "IMPORTANT: Use ISO 8601 UTC timestamps (e.g., 2024-01-15T10:00:00Z) or relative times (e.g., '16h ago', 'now')\n\n" +
             "EXAMPLES:\n" +
             "- Last 30 minutes: Calculate timestamps from current time\n" +
             "- Specific meeting: Use the meeting's start and end times in UTC",
@@ -176,12 +184,12 @@ const BASE_TOOLS = [
                 start_time: {
                     type: "string",
                     format: "date-time",
-                    description: "Start time in ISO 8601 format UTC. MUST include timezone (Z for UTC). Example: '2024-01-15T10:00:00Z'",
+                    description: "Start time: ISO 8601 UTC (e.g., '2024-01-15T10:00:00Z') or relative (e.g., '16h ago', 'now')",
                 },
                 end_time: {
                     type: "string",
                     format: "date-time",
-                    description: "End time in ISO 8601 format UTC. MUST include timezone (Z for UTC). Example: '2024-01-15T10:30:00Z'",
+                    description: "End time: ISO 8601 UTC (e.g., '2024-01-15T10:30:00Z') or relative (e.g., 'now', '1h ago')",
                 },
                 fps: {
                     type: "number",
@@ -192,6 +200,152 @@ const BASE_TOOLS = [
             required: ["start_time", "end_time"],
         },
     },
+    {
+        name: "list-meetings",
+        description: "List detected meetings with duration, app, and attendees. " +
+            "Returns meetings detected via app focus (Zoom, Meet, Teams) and audio. " +
+            "Only available when screenpipe runs in smart transcription mode.",
+        annotations: {
+            title: "List Meetings",
+            readOnlyHint: true,
+        },
+        inputSchema: {
+            type: "object",
+            properties: {
+                start_time: {
+                    type: "string",
+                    format: "date-time",
+                    description: "Start filter: ISO 8601 UTC (e.g., 2024-01-15T10:00:00Z) or relative (e.g., '16h ago', 'now')",
+                },
+                end_time: {
+                    type: "string",
+                    format: "date-time",
+                    description: "End filter: ISO 8601 UTC (e.g., 2024-01-15T18:00:00Z) or relative (e.g., 'now', '1h ago')",
+                },
+                limit: {
+                    type: "integer",
+                    description: "Max results. Default: 20",
+                    default: 20,
+                },
+                offset: {
+                    type: "integer",
+                    description: "Skip N results for pagination. Default: 0",
+                    default: 0,
+                },
+            },
+        },
+    },
+    {
+        name: "activity-summary",
+        description: "Get a lightweight compressed activity overview for a time range (~200-500 tokens). " +
+            "Returns app usage (name, frame count, active minutes, first/last seen), recent accessibility texts, and audio speaker summary. " +
+            "Minutes are based on active session time (consecutive frames with gaps < 5min count as active). " +
+            "first_seen/last_seen show the wall-clock span per app. " +
+            "Use this FIRST for broad questions like 'what was I doing?' before drilling into search-content or search-elements. " +
+            "Much cheaper than search-content for getting an overview.",
+        annotations: {
+            title: "Activity Summary",
+            readOnlyHint: true,
+        },
+        inputSchema: {
+            type: "object",
+            properties: {
+                start_time: {
+                    type: "string",
+                    format: "date-time",
+                    description: "Start of time range: ISO 8601 UTC (e.g., 2024-01-15T10:00:00Z) or relative (e.g., '16h ago', 'now')",
+                },
+                end_time: {
+                    type: "string",
+                    format: "date-time",
+                    description: "End of time range: ISO 8601 UTC (e.g., 2024-01-15T18:00:00Z) or relative (e.g., 'now', '1h ago')",
+                },
+                app_name: {
+                    type: "string",
+                    description: "Optional app name filter (e.g., 'Google Chrome', 'VS Code')",
+                },
+            },
+            required: ["start_time", "end_time"],
+        },
+    },
+    {
+        name: "search-elements",
+        description: "Search structured UI elements (accessibility tree nodes and OCR text blocks). " +
+            "Returns ~100-500 bytes per element — much lighter than search-content for targeted lookups. " +
+            "Each element has: id, frame_id, source (accessibility/ocr), role (AXButton, AXStaticText, AXLink, etc.), text, bounds, depth.\n\n" +
+            "Use for: finding specific buttons, links, text fields, or UI components. " +
+            "Prefer this over search-content when you need structural UI detail rather than full screen text.",
+        annotations: {
+            title: "Search Elements",
+            readOnlyHint: true,
+        },
+        inputSchema: {
+            type: "object",
+            properties: {
+                q: {
+                    type: "string",
+                    description: "Full-text search query across element text. Optional.",
+                },
+                frame_id: {
+                    type: "integer",
+                    description: "Filter to elements from a specific frame",
+                },
+                source: {
+                    type: "string",
+                    enum: ["accessibility", "ocr"],
+                    description: "Filter by element source: 'accessibility' (structured tree) or 'ocr' (text blocks)",
+                },
+                role: {
+                    type: "string",
+                    description: "Filter by element role (e.g., 'AXButton', 'AXStaticText', 'AXLink', 'AXTextField', 'line')",
+                },
+                start_time: {
+                    type: "string",
+                    format: "date-time",
+                    description: "Start time: ISO 8601 UTC or relative (e.g., '16h ago', 'now')",
+                },
+                end_time: {
+                    type: "string",
+                    format: "date-time",
+                    description: "End time: ISO 8601 UTC or relative (e.g., 'now', '1h ago')",
+                },
+                app_name: {
+                    type: "string",
+                    description: "Filter by app name",
+                },
+                limit: {
+                    type: "integer",
+                    description: "Max results. Default: 50",
+                    default: 50,
+                },
+                offset: {
+                    type: "integer",
+                    description: "Skip N results for pagination. Default: 0",
+                    default: 0,
+                },
+            },
+        },
+    },
+    {
+        name: "frame-context",
+        description: "Get accessibility text, parsed tree nodes, and extracted URLs for a specific frame. " +
+            "Falls back to OCR data for legacy frames without accessibility data. " +
+            "Use after finding a frame_id from search-content or search-elements to get full structural detail and URLs.",
+        annotations: {
+            title: "Frame Context",
+            readOnlyHint: true,
+        },
+        inputSchema: {
+            type: "object",
+            properties: {
+                frame_id: {
+                    type: "integer",
+                    description: "The frame ID to get context for (from search results)",
+                },
+            },
+            required: ["frame_id"],
+        },
+    },
 ];
 // List tools handler
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
@@ -262,16 +416,16 @@ server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (request) =
 ## Data Modalities
 
 Screenpipe captures four types of data:
-1. **OCR** - Screen text from screenshots
-2. **Audio** - Transcribed speech from microphone/system audio
-3. **Input** - Keyboard input, mouse clicks, app switches, clipboard (macOS)
-4. **Accessibility** - Accessibility tree text
+1. **Accessibility** - Screen text via accessibility APIs (primary, preferred for screen content)
+2. **OCR** - Screen text from screenshots (legacy fallback for apps without accessibility support)
+3. **Audio** - Transcribed speech from microphone/system audio
+4. **Input** - Keyboard input, mouse clicks, app switches, clipboard (macOS)
 
 ## Quick Start
 - **Get recent activity**: Call search-content with no parameters
-- **Search text**: \`{"q": "search term", "content_type": "ocr"}\`
+- **Search screen text**: \`{"q": "search term", "content_type": "all"}\`
 - **Get keyboard input**: \`{"content_type": "input"}\`
-- **Get accessibility text**: \`{"content_type": "accessibility"}\`
+- **Get audio only**: \`{"content_type": "audio"}\`
 
 ## search-content
 | Parameter | Description | Default |
@@ -279,16 +433,32 @@ Screenpipe captures four types of data:
 | q | Search query | (none - returns all) |
 | content_type | all/ocr/audio/input/accessibility | all |
 | limit | Max results | 10 |
-| start_time | ISO 8601 UTC | (no filter) |
-| end_time | ISO 8601 UTC | (no filter) |
+| start_time | ISO 8601 UTC or relative (e.g. '16h ago') | (no filter) |
+| end_time | ISO 8601 UTC or relative (e.g. 'now') | (no filter) |
 | app_name | Filter by app | (no filter) |
 | include_frames | Include screenshots | false |
 
+## Search Strategy (MANDATORY)
+1. First search: ONLY use time params (start_time/end_time). No q, no app_name, no content_type. This gives ground truth of what's recorded.
+2. Scan results to find correct app_name values and content patterns.
+3. Only THEN narrow with filters using exact observed values. App names are case-sensitive and may differ from user input (e.g. "Discord" vs "Discord.exe").
+4. The q param searches captured text (accessibility/OCR), NOT app names — an app can be visible without its name in the captured text.
+5. NEVER report "no data found" after one filtered search. Verify with unfiltered time-only search first.
+
+## Progressive Disclosure (Token-Efficient Strategy)
+1. **Start with activity-summary** (~200 tokens) for broad questions ("what was I doing?")
+2. **Narrow with search-content** (~500-1000 tokens) using filters from step 1
+3. **Drill into search-elements** (~200 tokens each) for structural UI detail (buttons, links)
+4. **Fetch frame-context** for URLs and accessibility tree of specific frames
+5. **Screenshots** (include_frames=true) only when text isn't enough
+
 ## Tips
 1. Read screenpipe://context first to get current timestamps
-2. Use content_type=input for "what did I type?" queries
-3. Use content_type=accessibility for accessibility tree text
-4. For large aggregations (e.g. "what apps did I use today?"), paginate with offset or suggest the user run raw SQL via \`curl -X POST http://localhost:3030/raw_sql\` for efficient GROUP BY queries
+2. Use activity-summary before search-content for broad overview questions
+3. Use search-elements instead of search-content for targeted UI lookups (10x lighter)
+4. Use content_type=input for "what did I type?" queries
+5. Use content_type=accessibility for accessibility tree text
+6. For large aggregations (e.g. "what apps did I use today?"), paginate with offset or suggest the user run raw SQL via \`curl -X POST http://localhost:3030/raw_sql\` for efficient GROUP BY queries
 
 ## Deep Links (Clickable References)
 When showing search results to users, create clickable links so they can jump to that exact moment.
@@ -434,7 +604,7 @@ Current time: ${dateInfo.isoDate}
 Use search-content with:
 - app_name: "${app}"
 ${query ? `- q: "${query}"` : "- No query filter"}
-- content_type: "ocr"
+- content_type: "all"
 - limit: 50`,
                         },
                     },
@@ -712,6 +882,156 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                     };
                 }
             }
+            case "list-meetings": {
+                const params = new URLSearchParams();
+                for (const [key, value] of Object.entries(args)) {
+                    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 meetings = await response.json();
+                if (!Array.isArray(meetings) || meetings.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "No meetings found. Make sure screenpipe is running in smart transcription mode.",
+                            },
+                        ],
+                    };
+                }
+                const formatted = meetings.map((m) => {
+                    const start = m.meeting_start;
+                    const end = m.meeting_end || "ongoing";
+                    const app = m.meeting_app;
+                    const title = m.title ? ` — ${m.title}` : "";
+                    const attendees = m.attendees ? `\nAttendees: ${m.attendees}` : "";
+                    return `[${m.detection_source}] ${app}${title}\n  ${start} → ${end}${attendees}`;
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Meetings: ${meetings.length}\n\n${formatted.join("\n---\n")}`,
+                        },
+                    ],
+                };
+            }
+            case "activity-summary": {
+                const params = new URLSearchParams();
+                for (const [key, value] of Object.entries(args)) {
+                    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 data = await response.json();
+                // Format apps
+                const appsLines = (data.apps || []).map((a) => {
+                    const timeSpan = a.first_seen && a.last_seen
+                        ? `, ${a.first_seen.slice(11, 16)}–${a.last_seen.slice(11, 16)} UTC`
+                        : "";
+                    return `  ${a.name}: ${a.minutes} min (${a.frame_count} frames${timeSpan})`;
+                });
+                // Format audio
+                const speakerLines = (data.audio_summary?.speakers || []).map((s) => `  ${s.name}: ${s.segment_count} segments`);
+                // Format recent texts
+                const textLines = (data.recent_texts || []).map((t) => `  [${t.app_name}] ${t.text}`);
+                const summary = [
+                    `Activity Summary (${data.time_range?.start} → ${data.time_range?.end})`,
+                    `Total frames: ${data.total_frames}`,
+                    "",
+                    "Apps:",
+                    ...(appsLines.length ? appsLines : ["  (none)"]),
+                    "",
+                    `Audio: ${data.audio_summary?.segment_count || 0} segments`,
+                    ...(speakerLines.length ? speakerLines : []),
+                    "",
+                    "Recent texts:",
+                    ...(textLines.length ? textLines.slice(0, 10) : ["  (none)"]),
+                ].join("\n");
+                return { content: [{ type: "text", text: summary }] };
+            }
+            case "search-elements": {
+                const params = new URLSearchParams();
+                for (const [key, value] of Object.entries(args)) {
+                    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 data = await response.json();
+                const elements = data.data || [];
+                const pagination = data.pagination || {};
+                if (elements.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "No elements found. Try: broader search, different role/source, or wider time range.",
+                            },
+                        ],
+                    };
+                }
+                const formatted = elements.map((e) => {
+                    const boundsStr = e.bounds
+                        ? ` [${e.bounds.left.toFixed(2)},${e.bounds.top.toFixed(2)} ${e.bounds.width.toFixed(2)}x${e.bounds.height.toFixed(2)}]`
+                        : "";
+                    return `[${e.source}] ${e.role} (frame:${e.frame_id}, depth:${e.depth})${boundsStr}\n  ${e.text || "(no text)"}`;
+                });
+                const header = `Elements: ${elements.length}/${pagination.total || "?"}` +
+                    (pagination.total > elements.length
+                        ? ` (use offset=${(pagination.offset || 0) + elements.length} for more)`
+                        : "");
+                return {
+                    content: [{ type: "text", text: header + "\n\n" + formatted.join("\n---\n") }],
+                };
+            }
+            case "frame-context": {
+                const frameId = args.frame_id;
+                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 data = await response.json();
+                const lines = [
+                    `Frame ${data.frame_id} (source: ${data.text_source})`,
+                ];
+                if (data.urls?.length) {
+                    lines.push("", "URLs:", ...data.urls.map((u) => `  ${u}`));
+                }
+                if (data.nodes?.length) {
+                    lines.push("", `Nodes: ${data.nodes.length}`);
+                    for (const node of data.nodes.slice(0, 50)) {
+                        const indent = "  ".repeat(Math.min(node.depth, 5));
+                        lines.push(`${indent}[${node.role}] ${node.text}`);
+                    }
+                    if (data.nodes.length > 50) {
+                        lines.push(`  ... and ${data.nodes.length - 50} more nodes`);
+                    }
+                }
+                if (data.text) {
+                    // Truncate to avoid massive outputs
+                    const truncated = data.text.length > 2000 ? data.text.substring(0, 2000) + "..." : data.text;
+                    lines.push("", "Full text:", truncated);
+                }
+                return { content: [{ type: "text", text: lines.join("\n") }] };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "screenpipe",
   "display_name": "Screenpipe",
-  "version": "0.8.0",
+  "version": "0.8.4",
   "description": "Search your screen recordings and audio transcriptions with AI",
   "long_description": "Screenpipe is a 24/7 screen and audio recorder that lets you search everything you've seen or heard. This extension connects Claude to your local screenpipe instance, enabling AI-powered search through your digital memory.",
   "author": {
@@ -33,6 +33,22 @@
     {
       "name": "export-video",
       "description": "Export screen recordings as MP4 video for a specific time range"
+    },
+    {
+      "name": "list-meetings",
+      "description": "List detected meetings with duration, app, and attendees"
+    },
+    {
+      "name": "activity-summary",
+      "description": "Lightweight compressed activity overview for a time range (apps, recent texts, audio summary)"
+    },
+    {
+      "name": "search-elements",
+      "description": "Search structured UI elements (accessibility tree nodes and OCR text blocks)"
+    },
+    {
+      "name": "frame-context",
+      "description": "Get accessibility text, parsed tree nodes, and extracted URLs for a specific frame"
     }
   ],
   "compatibility": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screenpipe-mcp",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "MCP server for screenpipe - search your screen recordings and audio transcriptions",
   "main": "dist/index.js",
   "bin": {

package/src/index.ts

@@ -48,7 +48,7 @@ const SCREENPIPE_API = `http://localhost:${port}`;
 const server = new Server(
   {
     name: "screenpipe",
-    version: "0.8.2",
+    version: "0.8.3",
   },
   {
     capabilities: {
@@ -64,10 +64,14 @@ const BASE_TOOLS: Tool[] = [
   {
     name: "search-content",
     description:
-      "Search screenpipe's recorded content: screen text (OCR), audio transcriptions, and UI elements. " +
+      "Search screenpipe's recorded content: screen text (accessibility APIs, with OCR fallback), audio transcriptions, and UI elements. " +
       "Returns timestamped results with app context. " +
       "Call with no parameters to get recent activity. " +
       "Use the 'screenpipe://context' resource for current time when building time-based queries.\n\n" +
+      "SEARCH STRATEGY: First search with ONLY time params (start_time/end_time) — no q, no app_name, no content_type. " +
+      "This gives ground truth of what's recorded. Scan results to find correct app_name values, then narrow with filters using exact observed values. " +
+      "App names are case-sensitive and may differ from user input (e.g. 'Discord' vs 'Discord.exe'). " +
+      "The q param searches captured text (accessibility/OCR), NOT app names. NEVER report 'no data' after one filtered search — verify with unfiltered time-only search first.\n\n" +
       "DEEP LINKS: When referencing specific moments, create clickable links using IDs from search results:\n" +
       "- OCR results (PREFERRED): [10:30 AM — Chrome](screenpipe://frame/12345) — use content.frame_id from the result\n" +
       "- Audio results: [meeting at 3pm](screenpipe://timeline?timestamp=2024-01-15T15:00:00Z) — use exact timestamp from result\n" +
@@ -86,7 +90,7 @@ const BASE_TOOLS: Tool[] = [
         content_type: {
           type: "string",
           enum: ["all", "ocr", "audio", "input", "accessibility"],
-          description: "Content type filter: 'ocr' (screen text), 'audio' (transcriptions), 'input' (clicks, keystrokes, clipboard, app switches), 'accessibility' (accessibility tree text), 'all'. Default: 'all'.",
+          description: "Content type filter: 'ocr' (screen text via OCR, legacy fallback), 'audio' (transcriptions), 'input' (clicks, keystrokes, clipboard, app switches), 'accessibility' (accessibility tree text, preferred for screen content), 'all'. Default: 'all'.",
           default: "all",
         },
         limit: {
@@ -102,12 +106,12 @@ const BASE_TOOLS: Tool[] = [
         start_time: {
           type: "string",
           format: "date-time",
-          description: "ISO 8601 UTC start time (e.g., 2024-01-15T10:00:00Z)",
+          description: "Start time: ISO 8601 UTC (e.g., 2024-01-15T10:00:00Z) or relative (e.g., '16h ago', '2d ago', 'now')",
         },
         end_time: {
           type: "string",
           format: "date-time",
-          description: "ISO 8601 UTC end time (e.g., 2024-01-15T18:00:00Z)",
+          description: "End time: ISO 8601 UTC (e.g., 2024-01-15T18:00:00Z) or relative (e.g., 'now', '1h ago')",
         },
         app_name: {
           type: "string",
@@ -138,6 +142,10 @@ const BASE_TOOLS: Tool[] = [
           type: "string",
           description: "Filter audio by speaker name (case-insensitive partial match)",
         },
+        max_content_length: {
+          type: "integer",
+          description: "Truncate each result's text/transcription to this many characters using middle-truncation (keeps first half + last half). Useful for limiting token usage with small-context models.",
+        },
       },
     },
   },
@@ -146,7 +154,7 @@ const BASE_TOOLS: Tool[] = [
     description:
       "Export a video of screen recordings for a specific time range. " +
       "Creates an MP4 video from the recorded frames between the start and end times.\n\n" +
-      "IMPORTANT: Use ISO 8601 UTC timestamps (e.g., 2024-01-15T10:00:00Z)\n\n" +
+      "IMPORTANT: Use ISO 8601 UTC timestamps (e.g., 2024-01-15T10:00:00Z) or relative times (e.g., '16h ago', 'now')\n\n" +
       "EXAMPLES:\n" +
       "- Last 30 minutes: Calculate timestamps from current time\n" +
       "- Specific meeting: Use the meeting's start and end times in UTC",
@@ -161,13 +169,13 @@ const BASE_TOOLS: Tool[] = [
           type: "string",
           format: "date-time",
           description:
-            "Start time in ISO 8601 format UTC. MUST include timezone (Z for UTC). Example: '2024-01-15T10:00:00Z'",
+            "Start time: ISO 8601 UTC (e.g., '2024-01-15T10:00:00Z') or relative (e.g., '16h ago', 'now')",
         },
         end_time: {
           type: "string",
           format: "date-time",
           description:
-            "End time in ISO 8601 format UTC. MUST include timezone (Z for UTC). Example: '2024-01-15T10:30:00Z'",
+            "End time: ISO 8601 UTC (e.g., '2024-01-15T10:30:00Z') or relative (e.g., 'now', '1h ago')",
         },
         fps: {
           type: "number",
@@ -179,6 +187,156 @@ const BASE_TOOLS: Tool[] = [
       required: ["start_time", "end_time"],
     },
   },
+  {
+    name: "list-meetings",
+    description:
+      "List detected meetings with duration, app, and attendees. " +
+      "Returns meetings detected via app focus (Zoom, Meet, Teams) and audio. " +
+      "Only available when screenpipe runs in smart transcription mode.",
+    annotations: {
+      title: "List Meetings",
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        start_time: {
+          type: "string",
+          format: "date-time",
+          description: "Start filter: ISO 8601 UTC (e.g., 2024-01-15T10:00:00Z) or relative (e.g., '16h ago', 'now')",
+        },
+        end_time: {
+          type: "string",
+          format: "date-time",
+          description: "End filter: ISO 8601 UTC (e.g., 2024-01-15T18:00:00Z) or relative (e.g., 'now', '1h ago')",
+        },
+        limit: {
+          type: "integer",
+          description: "Max results. Default: 20",
+          default: 20,
+        },
+        offset: {
+          type: "integer",
+          description: "Skip N results for pagination. Default: 0",
+          default: 0,
+        },
+      },
+    },
+  },
+  {
+    name: "activity-summary",
+    description:
+      "Get a lightweight compressed activity overview for a time range (~200-500 tokens). " +
+      "Returns app usage (name, frame count, active minutes, first/last seen), recent accessibility texts, and audio speaker summary. " +
+      "Minutes are based on active session time (consecutive frames with gaps < 5min count as active). " +
+      "first_seen/last_seen show the wall-clock span per app. " +
+      "Use this FIRST for broad questions like 'what was I doing?' before drilling into search-content or search-elements. " +
+      "Much cheaper than search-content for getting an overview.",
+    annotations: {
+      title: "Activity Summary",
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        start_time: {
+          type: "string",
+          format: "date-time",
+          description: "Start of time range: ISO 8601 UTC (e.g., 2024-01-15T10:00:00Z) or relative (e.g., '16h ago', 'now')",
+        },
+        end_time: {
+          type: "string",
+          format: "date-time",
+          description: "End of time range: ISO 8601 UTC (e.g., 2024-01-15T18:00:00Z) or relative (e.g., 'now', '1h ago')",
+        },
+        app_name: {
+          type: "string",
+          description: "Optional app name filter (e.g., 'Google Chrome', 'VS Code')",
+        },
+      },
+      required: ["start_time", "end_time"],
+    },
+  },
+  {
+    name: "search-elements",
+    description:
+      "Search structured UI elements (accessibility tree nodes and OCR text blocks). " +
+      "Returns ~100-500 bytes per element — much lighter than search-content for targeted lookups. " +
+      "Each element has: id, frame_id, source (accessibility/ocr), role (AXButton, AXStaticText, AXLink, etc.), text, bounds, depth.\n\n" +
+      "Use for: finding specific buttons, links, text fields, or UI components. " +
+      "Prefer this over search-content when you need structural UI detail rather than full screen text.",
+    annotations: {
+      title: "Search Elements",
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: {
+          type: "string",
+          description: "Full-text search query across element text. Optional.",
+        },
+        frame_id: {
+          type: "integer",
+          description: "Filter to elements from a specific frame",
+        },
+        source: {
+          type: "string",
+          enum: ["accessibility", "ocr"],
+          description: "Filter by element source: 'accessibility' (structured tree) or 'ocr' (text blocks)",
+        },
+        role: {
+          type: "string",
+          description: "Filter by element role (e.g., 'AXButton', 'AXStaticText', 'AXLink', 'AXTextField', 'line')",
+        },
+        start_time: {
+          type: "string",
+          format: "date-time",
+          description: "Start time: ISO 8601 UTC or relative (e.g., '16h ago', 'now')",
+        },
+        end_time: {
+          type: "string",
+          format: "date-time",
+          description: "End time: ISO 8601 UTC or relative (e.g., 'now', '1h ago')",
+        },
+        app_name: {
+          type: "string",
+          description: "Filter by app name",
+        },
+        limit: {
+          type: "integer",
+          description: "Max results. Default: 50",
+          default: 50,
+        },
+        offset: {
+          type: "integer",
+          description: "Skip N results for pagination. Default: 0",
+          default: 0,
+        },
+      },
+    },
+  },
+  {
+    name: "frame-context",
+    description:
+      "Get accessibility text, parsed tree nodes, and extracted URLs for a specific frame. " +
+      "Falls back to OCR data for legacy frames without accessibility data. " +
+      "Use after finding a frame_id from search-content or search-elements to get full structural detail and URLs.",
+    annotations: {
+      title: "Frame Context",
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame_id: {
+          type: "integer",
+          description: "The frame ID to get context for (from search results)",
+        },
+      },
+      required: ["frame_id"],
+    },
+  },
 ];
 
 // List tools handler
@@ -255,16 +413,16 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 ## Data Modalities
 
 Screenpipe captures four types of data:
-1. **OCR** - Screen text from screenshots
-2. **Audio** - Transcribed speech from microphone/system audio
-3. **Input** - Keyboard input, mouse clicks, app switches, clipboard (macOS)
-4. **Accessibility** - Accessibility tree text
+1. **Accessibility** - Screen text via accessibility APIs (primary, preferred for screen content)
+2. **OCR** - Screen text from screenshots (legacy fallback for apps without accessibility support)
+3. **Audio** - Transcribed speech from microphone/system audio
+4. **Input** - Keyboard input, mouse clicks, app switches, clipboard (macOS)
 
 ## Quick Start
 - **Get recent activity**: Call search-content with no parameters
-- **Search text**: \`{"q": "search term", "content_type": "ocr"}\`
+- **Search screen text**: \`{"q": "search term", "content_type": "all"}\`
 - **Get keyboard input**: \`{"content_type": "input"}\`
-- **Get accessibility text**: \`{"content_type": "accessibility"}\`
+- **Get audio only**: \`{"content_type": "audio"}\`
 
 ## search-content
 | Parameter | Description | Default |
@@ -272,16 +430,32 @@ Screenpipe captures four types of data:
 | q | Search query | (none - returns all) |
 | content_type | all/ocr/audio/input/accessibility | all |
 | limit | Max results | 10 |
-| start_time | ISO 8601 UTC | (no filter) |
-| end_time | ISO 8601 UTC | (no filter) |
+| start_time | ISO 8601 UTC or relative (e.g. '16h ago') | (no filter) |
+| end_time | ISO 8601 UTC or relative (e.g. 'now') | (no filter) |
 | app_name | Filter by app | (no filter) |
 | include_frames | Include screenshots | false |
 
+## Search Strategy (MANDATORY)
+1. First search: ONLY use time params (start_time/end_time). No q, no app_name, no content_type. This gives ground truth of what's recorded.
+2. Scan results to find correct app_name values and content patterns.
+3. Only THEN narrow with filters using exact observed values. App names are case-sensitive and may differ from user input (e.g. "Discord" vs "Discord.exe").
+4. The q param searches captured text (accessibility/OCR), NOT app names — an app can be visible without its name in the captured text.
+5. NEVER report "no data found" after one filtered search. Verify with unfiltered time-only search first.
+
+## Progressive Disclosure (Token-Efficient Strategy)
+1. **Start with activity-summary** (~200 tokens) for broad questions ("what was I doing?")
+2. **Narrow with search-content** (~500-1000 tokens) using filters from step 1
+3. **Drill into search-elements** (~200 tokens each) for structural UI detail (buttons, links)
+4. **Fetch frame-context** for URLs and accessibility tree of specific frames
+5. **Screenshots** (include_frames=true) only when text isn't enough
+
 ## Tips
 1. Read screenpipe://context first to get current timestamps
-2. Use content_type=input for "what did I type?" queries
-3. Use content_type=accessibility for accessibility tree text
-4. For large aggregations (e.g. "what apps did I use today?"), paginate with offset or suggest the user run raw SQL via \`curl -X POST http://localhost:3030/raw_sql\` for efficient GROUP BY queries
+2. Use activity-summary before search-content for broad overview questions
+3. Use search-elements instead of search-content for targeted UI lookups (10x lighter)
+4. Use content_type=input for "what did I type?" queries
+5. Use content_type=accessibility for accessibility tree text
+6. For large aggregations (e.g. "what apps did I use today?"), paginate with offset or suggest the user run raw SQL via \`curl -X POST http://localhost:3030/raw_sql\` for efficient GROUP BY queries
 
 ## Deep Links (Clickable References)
 When showing search results to users, create clickable links so they can jump to that exact moment.
@@ -435,7 +609,7 @@ Current time: ${dateInfo.isoDate}
 Use search-content with:
 - app_name: "${app}"
 ${query ? `- q: "${query}"` : "- No query filter"}
-- content_type: "ocr"
+- content_type: "all"
 - limit: 50`,
             },
           },
@@ -763,6 +937,204 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
       }
 
+      case "list-meetings": {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(args)) {
+          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 meetings = await response.json();
+
+        if (!Array.isArray(meetings) || meetings.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No meetings found. Make sure screenpipe is running in smart transcription mode.",
+              },
+            ],
+          };
+        }
+
+        const formatted = meetings.map((m: Record<string, unknown>) => {
+          const start = m.meeting_start as string;
+          const end = (m.meeting_end as string) || "ongoing";
+          const app = m.meeting_app as string;
+          const title = m.title ? ` — ${m.title}` : "";
+          const attendees = m.attendees ? `\nAttendees: ${m.attendees}` : "";
+          return `[${m.detection_source}] ${app}${title}\n  ${start} → ${end}${attendees}`;
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Meetings: ${meetings.length}\n\n${formatted.join("\n---\n")}`,
+            },
+          ],
+        };
+      }
+
+      case "activity-summary": {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(args)) {
+          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 data = await response.json();
+
+        // Format apps
+        const appsLines = (data.apps || []).map(
+          (a: { name: string; frame_count: number; minutes: number; first_seen?: string; last_seen?: string }) => {
+            const timeSpan = a.first_seen && a.last_seen
+              ? `, ${a.first_seen.slice(11, 16)}–${a.last_seen.slice(11, 16)} UTC`
+              : "";
+            return `  ${a.name}: ${a.minutes} min (${a.frame_count} frames${timeSpan})`;
+          }
+        );
+
+        // Format audio
+        const speakerLines = (data.audio_summary?.speakers || []).map(
+          (s: { name: string; segment_count: number }) =>
+            `  ${s.name}: ${s.segment_count} segments`
+        );
+
+        // Format recent texts
+        const textLines = (data.recent_texts || []).map(
+          (t: { text: string; app_name: string; timestamp: string }) =>
+            `  [${t.app_name}] ${t.text}`
+        );
+
+        const summary = [
+          `Activity Summary (${data.time_range?.start} → ${data.time_range?.end})`,
+          `Total frames: ${data.total_frames}`,
+          "",
+          "Apps:",
+          ...(appsLines.length ? appsLines : ["  (none)"]),
+          "",
+          `Audio: ${data.audio_summary?.segment_count || 0} segments`,
+          ...(speakerLines.length ? speakerLines : []),
+          "",
+          "Recent texts:",
+          ...(textLines.length ? textLines.slice(0, 10) : ["  (none)"]),
+        ].join("\n");
+
+        return { content: [{ type: "text", text: summary }] };
+      }
+
+      case "search-elements": {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(args)) {
+          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 data = await response.json();
+        const elements = data.data || [];
+        const pagination = data.pagination || {};
+
+        if (elements.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No elements found. Try: broader search, different role/source, or wider time range.",
+              },
+            ],
+          };
+        }
+
+        const formatted = elements.map(
+          (e: {
+            id: number;
+            frame_id: number;
+            source: string;
+            role: string;
+            text: string | null;
+            depth: number;
+            bounds: { left: number; top: number; width: number; height: number } | null;
+          }) => {
+            const boundsStr = e.bounds
+              ? ` [${e.bounds.left.toFixed(2)},${e.bounds.top.toFixed(2)} ${e.bounds.width.toFixed(2)}x${e.bounds.height.toFixed(2)}]`
+              : "";
+            return `[${e.source}] ${e.role} (frame:${e.frame_id}, depth:${e.depth})${boundsStr}\n  ${e.text || "(no text)"}`;
+          }
+        );
+
+        const header =
+          `Elements: ${elements.length}/${pagination.total || "?"}` +
+          (pagination.total > elements.length
+            ? ` (use offset=${(pagination.offset || 0) + elements.length} for more)`
+            : "");
+
+        return {
+          content: [{ type: "text", text: header + "\n\n" + formatted.join("\n---\n") }],
+        };
+      }
+
+      case "frame-context": {
+        const frameId = args.frame_id as number;
+        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 data = await response.json();
+
+        const lines = [
+          `Frame ${data.frame_id} (source: ${data.text_source})`,
+        ];
+
+        if (data.urls?.length) {
+          lines.push("", "URLs:", ...data.urls.map((u: string) => `  ${u}`));
+        }
+
+        if (data.nodes?.length) {
+          lines.push("", `Nodes: ${data.nodes.length}`);
+          for (const node of data.nodes.slice(0, 50)) {
+            const indent = "  ".repeat(Math.min(node.depth, 5));
+            lines.push(`${indent}[${node.role}] ${node.text}`);
+          }
+          if (data.nodes.length > 50) {
+            lines.push(`  ... and ${data.nodes.length - 50} more nodes`);
+          }
+        }
+
+        if (data.text) {
+          // Truncate to avoid massive outputs
+          const truncated = data.text.length > 2000 ? data.text.substring(0, 2000) + "..." : data.text;
+          lines.push("", "Full text:", truncated);
+        }
+
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }