screenpipe-mcp 0.10.0 → 0.12.0

package/dist/index.js

@@ -64,63 +64,67 @@ const server = new index_js_1.Server({
     },
 });
 // ---------------------------------------------------------------------------
-// Tools — minimal descriptions, no behavioral guidance (that belongs in resources)
+// Tools
 // ---------------------------------------------------------------------------
 const TOOLS = [
     {
         name: "search-content",
         description: "Search screen text, audio transcriptions, input events, and memories. " +
-            "Returns timestamped results with app context. Call with no params for recent activity.",
-        annotations: { title: "Search Content", readOnlyHint: true },
+            "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.",
+        annotations: { title: "Search Content", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
         inputSchema: {
             type: "object",
             properties: {
                 q: {
                     type: "string",
-                    description: "Full-text search query. Omit to return all content in time range.",
+                    description: "Full-text search query. Omit to return all content in time range. Avoid for audio — transcriptions are noisy, q filters too aggressively.",
                 },
                 content_type: {
                     type: "string",
                     enum: ["all", "ocr", "audio", "input", "accessibility", "memory"],
-                    description: "Filter by content type. Default: 'all'.",
+                    description: "Filter by content type. 'accessibility' is preferred for screen text (OS-native). 'ocr' is fallback for apps without accessibility support. Default: 'all'.",
                     default: "all",
                 },
-                limit: { type: "integer", description: "Max results (default 10)", default: 10 },
-                offset: { type: "integer", description: "Pagination offset", default: 0 },
+                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')",
+                    description: "ISO 8601 UTC or relative (e.g. '2h ago', '1d ago'). Always provide to avoid scanning entire history.",
                 },
                 end_time: {
                     type: "string",
-                    description: "ISO 8601 UTC or relative (e.g. 'now')",
+                    description: "ISO 8601 UTC or relative (e.g. 'now'). Defaults to now.",
                 },
-                app_name: { type: "string", description: "Filter by app name" },
-                window_name: { type: "string", description: "Filter by window title" },
-                min_length: { type: "integer", description: "Min content length" },
-                max_length: { type: "integer", description: "Max content length" },
+                app_name: { type: "string", description: "Filter by app name (e.g. 'Google Chrome', 'Slack', 'zoom.us'). Case-sensitive." },
+                window_name: { type: "string", description: "Filter by window title substring" },
+                min_length: { type: "integer", description: "Min content length in characters" },
+                max_length: { type: "integer", description: "Max content length in characters" },
                 include_frames: {
                     type: "boolean",
-                    description: "Include base64 screenshots (OCR only)",
+                    description: "Include base64 screenshots (OCR only). Warning: large response.",
                     default: false,
                 },
-                speaker_ids: { type: "string", description: "Comma-separated speaker IDs" },
-                speaker_name: { type: "string", description: "Filter audio by speaker name" },
+                speaker_ids: { type: "string", description: "Comma-separated speaker IDs to filter audio" },
+                speaker_name: { type: "string", description: "Filter audio by speaker name (case-insensitive partial match)" },
                 max_content_length: {
                     type: "integer",
-                    description: "Truncate each result via middle-truncation",
+                    description: "Truncate each result's text via middle-truncation. Use 200-500 to keep responses compact.",
                 },
             },
         },
     },
     {
         name: "list-meetings",
-        description: "List detected meetings (Zoom, Teams, Meet, etc.) with duration, app, and attendees.",
-        annotations: { title: "List Meetings", readOnlyHint: true },
+        description: "List detected meetings (Zoom, Teams, Meet, etc.) with duration, app, and attendees. " +
+            "Only available when screenpipe runs in smart transcription mode.",
+        annotations: { title: "List Meetings", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
         inputSchema: {
             type: "object",
             properties: {
-                start_time: { type: "string", description: "ISO 8601 UTC or relative" },
+                start_time: { type: "string", description: "ISO 8601 UTC or relative (e.g. '1d ago')" },
                 end_time: { type: "string", description: "ISO 8601 UTC or relative" },
                 limit: { type: "integer", description: "Max results (default 20)", default: 20 },
                 offset: { type: "integer", description: "Pagination offset", default: 0 },
@@ -130,14 +134,15 @@ const TOOLS = [
     {
         name: "activity-summary",
         description: "Lightweight activity overview (~200-500 tokens): app usage with active minutes, audio speakers, recent texts. " +
-            "Use for 'how long on X?', 'which apps?', 'what was I doing?' questions.",
-        annotations: { title: "Activity Summary", readOnlyHint: true },
+            "USE THIS FIRST for broad questions: 'what was I doing?', 'how long on X?', 'which apps?'. " +
+            "Only escalate to search-content if you need specific text content.",
+        annotations: { title: "Activity Summary", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
         inputSchema: {
             type: "object",
             properties: {
-                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: "Optional app name filter" },
+                start_time: { type: "string", description: "ISO 8601 UTC or relative (e.g. '3h ago')" },
+                end_time: { type: "string", description: "ISO 8601 UTC or relative (e.g. 'now')" },
+                app_name: { type: "string", description: "Optional app name filter to focus on one app" },
             },
             required: ["start_time", "end_time"],
         },
@@ -145,85 +150,89 @@ 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.",
-        annotations: { title: "Search Elements", readOnlyHint: true },
+            "Lighter than search-content for targeted UI lookups. " +
+            "Use when you need to find specific UI controls or page structure, not general content.",
+        annotations: { title: "Search Elements", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
         inputSchema: {
             type: "object",
             properties: {
                 q: { type: "string", description: "Full-text search on element text" },
-                frame_id: { type: "integer", description: "Filter to specific frame" },
+                frame_id: { type: "integer", description: "Filter to specific frame ID from search results" },
                 source: {
                     type: "string",
                     enum: ["accessibility", "ocr"],
-                    description: "Element source filter",
+                    description: "Element source. 'accessibility' is preferred (OS-native tree). 'ocr' for apps without a11y.",
                 },
-                role: { type: "string", description: "Element role (e.g. AXButton, AXLink)" },
+                role: { type: "string", description: "Element role filter (e.g. 'AXButton', 'AXLink', 'AXTextField')" },
                 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" },
-                limit: { type: "integer", description: "Max results (default 50)", default: 50 },
+                limit: { type: "integer", description: "Max results (default 50). Start with 10-20.", default: 50 },
                 offset: { type: "integer", description: "Pagination offset", default: 0 },
             },
         },
     },
     {
         name: "frame-context",
-        description: "Get accessibility text, parsed tree nodes, and URLs for a specific frame ID.",
-        annotations: { title: "Frame Context", readOnlyHint: true },
+        description: "Get full accessibility text, parsed tree nodes, and URLs for a specific frame ID. " +
+            "Use after search-content to get detailed context for a specific moment.",
+        annotations: { title: "Frame Context", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
         inputSchema: {
             type: "object",
             properties: {
-                frame_id: { type: "integer", description: "Frame ID from search results" },
+                frame_id: { type: "integer", description: "Frame ID from search-content results (content.frame_id field)" },
             },
             required: ["frame_id"],
         },
     },
     {
         name: "export-video",
-        description: "Export an MP4 video of screen recordings for a time range.",
-        annotations: { title: "Export Video", destructiveHint: true },
+        description: "Export an MP4 video of screen recordings for a time range. " +
+            "Returns the file path. Can take a few minutes for long ranges.",
+        annotations: { title: "Export Video", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
         inputSchema: {
             type: "object",
             properties: {
                 start_time: { type: "string", description: "ISO 8601 UTC or relative" },
                 end_time: { type: "string", description: "ISO 8601 UTC or relative" },
-                fps: { type: "number", description: "Output FPS (default 1.0)", default: 1.0 },
+                fps: { type: "number", description: "Output FPS (default 1.0). Higher = smoother but larger file.", default: 1.0 },
             },
             required: ["start_time", "end_time"],
         },
     },
     {
         name: "update-memory",
-        description: "Create, update, or delete a persistent memory (facts, preferences, decisions). " +
-            "Retrieve memories via search-content with content_type='memory'.",
-        annotations: { title: "Update Memory", destructiveHint: false },
+        description: "Create, update, or delete a persistent memory (facts, preferences, decisions the user wants to remember). " +
+            "To retrieve memories, use search-content with content_type='memory'. " +
+            "To create: provide content + tags. To update: provide id + fields to change. To delete: provide id + delete=true.",
+        annotations: { title: "Update Memory", readOnlyHint: false, destructiveHint: false, openWorldHint: false, idempotentHint: true },
         inputSchema: {
             type: "object",
             properties: {
-                id: { type: "integer", description: "Memory ID (omit to create new)" },
-                content: { type: "string", description: "Memory text" },
-                tags: { type: "array", items: { type: "string" }, description: "Categorization tags" },
-                importance: { type: "number", description: "0.0-1.0 (default 0.5)" },
-                source_context: { type: "object", description: "Optional source data links" },
-                delete: { type: "boolean", description: "Delete the memory identified by id" },
+                id: { type: "integer", description: "Memory ID — omit to create new, provide to update/delete" },
+                content: { type: "string", description: "Memory text (required for creation)" },
+                tags: { type: "array", items: { type: "string" }, description: "Categorization tags (e.g. ['work', 'project-x'])" },
+                importance: { type: "number", description: "0.0 (trivial) to 1.0 (critical). Default 0.5." },
+                source_context: { type: "object", description: "Optional metadata linking to source (app, timestamp, etc.)" },
+                delete: { type: "boolean", description: "Set true to delete the memory identified by id" },
             },
         },
     },
     {
         name: "send-notification",
-        description: "Send a notification to the screenpipe desktop UI with optional action buttons. " +
-            "Actions can re-run pipes with context, call API endpoints, or open deep links.",
-        annotations: { title: "Send Notification", destructiveHint: false },
+        description: "Send a notification to the screenpipe desktop UI. " +
+            "Use to alert the user about findings, completed tasks, or actions needing attention.",
+        annotations: { title: "Send Notification", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
         inputSchema: {
             type: "object",
             properties: {
-                title: { type: "string", description: "Notification title" },
+                title: { type: "string", description: "Notification title (short, descriptive)" },
                 body: { type: "string", description: "Notification body (markdown supported)" },
-                pipe_name: { type: "string", description: "Name of the pipe sending this notification" },
-                timeout_secs: { type: "integer", description: "Auto-dismiss seconds (default 20)", default: 20 },
+                pipe_name: { type: "string", description: "Name of the pipe/tool sending this notification" },
+                timeout_secs: { type: "integer", description: "Auto-dismiss after N seconds (default 20). Use 0 for persistent.", default: 20 },
                 actions: {
                     type: "array",
-                    description: "Up to 5 action buttons",
+                    description: "Up to 5 action buttons. Each needs id, label, type ('pipe'|'api'|'deeplink'|'dismiss').",
                     items: {
                         type: "object",
                         properties: {
@@ -232,6 +241,7 @@ const TOOLS = [
                             type: { type: "string", enum: ["pipe", "api", "deeplink", "dismiss"], description: "Action type" },
                             pipe: { type: "string", description: "Pipe name to run (type=pipe)" },
                             context: { type: "object", description: "Context passed to pipe (type=pipe)" },
+                            open_in_chat: { type: "boolean", description: "Open pipe run in chat UI instead of background (type=pipe)" },
                             url: { type: "string", description: "URL for api/deeplink actions" },
                         },
                         required: ["id", "label", "type"],
@@ -241,6 +251,162 @@ const TOOLS = [
             required: ["title", "pipe_name"],
         },
     },
+    {
+        name: "health-check",
+        description: "Check if screenpipe is running and healthy. Returns recording status, frame/audio stats, timestamps.",
+        annotations: { title: "Health Check", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "list-audio-devices",
+        description: "List available audio input/output devices for recording.",
+        annotations: { title: "List Audio Devices", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "list-monitors",
+        description: "List available monitors/screens for capture.",
+        annotations: { title: "List Monitors", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "add-tags",
+        description: "Add tags to a content item (vision frame or audio chunk) for organization and retrieval.",
+        annotations: { title: "Add Tags", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+        inputSchema: {
+            type: "object",
+            properties: {
+                content_type: { type: "string", enum: ["vision", "audio"], description: "Type of content to tag" },
+                id: { type: "integer", description: "Content item ID" },
+                tags: { type: "array", items: { type: "string" }, description: "Tags to add" },
+            },
+            required: ["content_type", "id", "tags"],
+        },
+    },
+    {
+        name: "search-speakers",
+        description: "Search for speakers by name prefix. Returns speaker ID, name, and metadata.",
+        annotations: { title: "Search Speakers", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Speaker name prefix to search for (case-insensitive)" },
+            },
+        },
+    },
+    {
+        name: "list-unnamed-speakers",
+        description: "List speakers that haven't been named yet. Useful for speaker identification workflow.",
+        annotations: { title: "List Unnamed Speakers", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "integer", description: "Max results (default 10)", default: 10 },
+                offset: { type: "integer", description: "Pagination offset", default: 0 },
+            },
+        },
+    },
+    {
+        name: "update-speaker",
+        description: "Rename a speaker or update their metadata.",
+        annotations: { title: "Update Speaker", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Speaker ID" },
+                name: { type: "string", description: "New speaker name" },
+                metadata: { type: "string", description: "JSON metadata string" },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "merge-speakers",
+        description: "Merge two speakers into one (e.g. when the same person was detected as different speakers).",
+        annotations: { title: "Merge Speakers", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+        inputSchema: {
+            type: "object",
+            properties: {
+                speaker_to_keep: { type: "integer", description: "Speaker ID to keep" },
+                speaker_to_merge: { type: "integer", description: "Speaker ID to merge into the kept one" },
+            },
+            required: ["speaker_to_keep", "speaker_to_merge"],
+        },
+    },
+    {
+        name: "start-meeting",
+        description: "Manually start a meeting recording session.",
+        annotations: { title: "Start Meeting", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+        inputSchema: {
+            type: "object",
+            properties: {
+                app: { type: "string", description: "App name (default 'manual')", default: "manual" },
+                title: { type: "string", description: "Meeting title" },
+                attendees: { type: "string", description: "Comma-separated attendee names" },
+            },
+        },
+    },
+    {
+        name: "stop-meeting",
+        description: "Stop the current manual meeting recording session.",
+        annotations: { title: "Stop Meeting", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "get-meeting",
+        description: "Get details of a specific meeting by ID, including transcription and attendees.",
+        annotations: { title: "Get Meeting", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Meeting ID" },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "keyword-search",
+        description: "Fast keyword search using FTS index. Faster than search-content for exact keyword matching. " +
+            "Returns frame IDs and matched text.",
+        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" },
+                limit: { type: "integer", description: "Max results (default 20)", default: 20 },
+                offset: { type: "integer", description: "Pagination offset", default: 0 },
+            },
+            required: ["q"],
+        },
+    },
+    {
+        name: "get-frame-elements",
+        description: "Get all UI elements for a specific frame. More targeted than search-elements when you already have a frame_id.",
+        annotations: { title: "Get Frame Elements", readOnlyHint: true, openWorldHint: false, idempotentHint: true },
+        inputSchema: {
+            type: "object",
+            properties: {
+                frame_id: { type: "integer", description: "Frame ID" },
+            },
+            required: ["frame_id"],
+        },
+    },
+    {
+        name: "control-recording",
+        description: "Start or stop audio/screen recording. Use to pause/resume capture.",
+        annotations: { title: "Control Recording", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: { type: "string", enum: ["start-audio", "stop-audio"], description: "Recording action" },
+            },
+            required: ["action"],
+        },
+    },
 ];
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
     return { tools: TOOLS };
@@ -255,6 +421,12 @@ const RESOURCES = [
         description: "Current date/time, timezone, and pre-computed timestamps for common time ranges",
         mimeType: "application/json",
     },
+    {
+        uri: "screenpipe://guide",
+        name: "Usage Guide",
+        description: "How to use screenpipe tools effectively — search strategy, progressive disclosure, and common patterns",
+        mimeType: "text/markdown",
+    },
 ];
 server.setRequestHandler(types_js_1.ListResourcesRequestSchema, async () => {
     return { resources: RESOURCES };
@@ -291,6 +463,51 @@ server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (request) =
             ],
         };
     }
+    if (uri === "screenpipe://guide") {
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: "text/markdown",
+                    text: `# Screenpipe Usage Guide
+
+## Progressive Disclosure — start light, escalate only when needed
+
+| Step | Tool | When to use |
+|------|------|-------------|
+| 1 | activity-summary | Broad questions: "what was I doing?", "which apps?", "how long on X?" |
+| 2 | search-content | Need specific text, transcriptions, or content |
+| 3 | search-elements | Need UI structure — buttons, links, form fields |
+| 4 | frame-context | Need full detail for a specific moment (use frame_id from step 2) |
+
+## Search Strategy
+
+- **Always provide start_time** — without it, search scans the entire history
+- **Start with limit=5** — increase only if you need more results
+- **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
+
+## Common Patterns
+
+- "What was I doing for the last 2 hours?" → activity-summary with start_time='2h ago'
+- "What did I discuss in my meeting?" → list-meetings to find it, then search-content with audio + that time range
+- "Find when I was on Twitter" → search-content with app_name='Arc' (or the browser name), q='twitter'
+- "Remember that I prefer X" → update-memory with content describing the preference
+- "What do you remember about X?" → search-content with content_type='memory', q='X'
+
+## Deep Links
+
+When referencing specific moments in results, create clickable links:
+- Frame: [10:30 AM — Chrome](screenpipe://frame/{frame_id}) — use frame_id from search results
+- Timeline: [meeting at 3pm](screenpipe://timeline?timestamp=2024-01-15T15:00:00Z) — use exact timestamp from results
+Never fabricate IDs or timestamps — only use values from actual results.
+`,
+                },
+            ],
+        };
+    }
     throw new Error(`Unknown resource: ${uri}`);
 });
 // ---------------------------------------------------------------------------
@@ -701,23 +918,246 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "send-notification": {
                 const notifBody = {
                     title: args.title,
-                    pipe_name: args.pipe_name,
+                    body: args.body || "",
+                    type: "pipe",
                 };
-                if (args.body)
-                    notifBody.body = args.body;
                 if (args.timeout_secs)
-                    notifBody.timeout_secs = args.timeout_secs;
+                    notifBody.timeout = Number(args.timeout_secs) * 1000;
                 if (args.actions)
                     notifBody.actions = args.actions;
-                const notifResponse = await fetchAPI("/notify", {
+                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}`);
                 const notifResult = await notifResponse.json();
                 return {
-                    content: [{ type: "text", text: `Notification sent (id: ${notifResult.id})` }],
+                    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 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 devices = await response.json();
+                if (!Array.isArray(devices) || devices.length === 0) {
+                    return { content: [{ type: "text", text: "No audio devices found." }] };
+                }
+                const formatted = devices.map((d) => `${d.is_default ? "* " : "  "}${d.name}${d.device_type ? ` (${d.device_type})` : ""}`);
+                return {
+                    content: [{ type: "text", text: `Audio devices:\n${formatted.join("\n")}` }],
+                };
+            }
+            case "list-monitors": {
+                const response = await fetchAPI("/vision/list");
+                if (!response.ok)
+                    throw new Error(`HTTP error: ${response.status}`);
+                const monitors = await response.json();
+                if (!Array.isArray(monitors) || monitors.length === 0) {
+                    return { content: [{ type: "text", text: "No monitors found." }] };
+                }
+                const formatted = monitors.map((m) => `${m.is_default ? "* " : "  "}Monitor ${m.id}${m.name ? `: ${m.name}` : ""}${m.width ? ` (${m.width}x${m.height})` : ""}`);
+                return {
+                    content: [{ type: "text", text: `Monitors:\n${formatted.join("\n")}` }],
+                };
+            }
+            case "add-tags": {
+                const contentType = args.content_type;
+                const id = args.id;
+                const tags = args.tags;
+                if (!contentType || !id || !tags) {
+                    return { content: [{ type: "text", text: "Error: content_type, id, and tags are required" }] };
+                }
+                const response = await fetchAPI(`/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(", ")}` }],
+                };
+            }
+            case "search-speakers": {
+                const nameQuery = args.name;
+                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 speakers = await response.json();
+                if (!Array.isArray(speakers) || speakers.length === 0) {
+                    return { content: [{ type: "text", text: "No speakers found." }] };
+                }
+                const formatted = speakers.map((s) => `#${s.id} ${s.name}${s.metadata ? ` — ${s.metadata}` : ""}`);
+                return {
+                    content: [{ type: "text", text: `Speakers:\n${formatted.join("\n")}` }],
+                };
+            }
+            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 speakers = await response.json();
+                if (!Array.isArray(speakers) || speakers.length === 0) {
+                    return { content: [{ type: "text", text: "No unnamed speakers found." }] };
+                }
+                const formatted = speakers.map((s) => `#${s.id} ${s.name}`);
+                return {
+                    content: [{ type: "text", text: `Unnamed speakers:\n${formatted.join("\n")}` }],
+                };
+            }
+            case "update-speaker": {
+                const speakerId = args.id;
+                if (!speakerId) {
+                    return { content: [{ type: "text", text: "Error: id is required" }] };
+                }
+                const body = { id: speakerId };
+                if (args.name !== undefined)
+                    body.name = args.name;
+                if (args.metadata !== undefined)
+                    body.metadata = args.metadata;
+                const response = await fetchAPI("/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.` }],
+                };
+            }
+            case "merge-speakers": {
+                const keepId = args.speaker_to_keep;
+                const mergeId = args.speaker_to_merge;
+                if (!keepId || !mergeId) {
+                    return { content: [{ type: "text", text: "Error: speaker_to_keep and speaker_to_merge are required" }] };
+                }
+                const response = await fetchAPI("/speakers/merge", {
+                    method: "POST",
+                    body: JSON.stringify({ speaker_to_keep: keepId, speaker_to_merge: mergeId }),
+                });
+                if (!response.ok)
+                    throw new Error(`HTTP error: ${response.status}`);
+                return {
+                    content: [{ type: "text", text: `Merged speaker ${mergeId} into ${keepId}.` }],
+                };
+            }
+            case "start-meeting": {
+                const body = {};
+                if (args.app)
+                    body.app = args.app;
+                if (args.title)
+                    body.title = args.title;
+                if (args.attendees)
+                    body.attendees = args.attendees;
+                const response = await fetchAPI("/meetings/start", {
+                    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}`);
+                return {
+                    content: [{ type: "text", text: "Meeting stopped." }],
+                };
+            }
+            case "get-meeting": {
+                const meetingId = args.id;
+                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 meeting = await response.json();
+                return {
+                    content: [{ type: "text", text: JSON.stringify(meeting, 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));
+                    }
+                }
+                const response = await fetchAPI(`/search/keyword?${params.toString()}`);
+                if (!response.ok)
+                    throw new Error(`HTTP error: ${response.status}`);
+                const data = await response.json();
+                const results = 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 || ""}`;
+                });
+                return {
+                    content: [{ type: "text", text: `Results: ${results.length}\n\n${formatted.join("\n---\n")}` }],
+                };
+            }
+            case "get-frame-elements": {
+                const frameId = args.frame_id;
+                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 elements = await response.json();
+                if (!Array.isArray(elements) || elements.length === 0) {
+                    return { content: [{ type: "text", text: `No elements found for frame ${frameId}.` }] };
+                }
+                const formatted = elements.map((e) => {
+                    const indent = "  ".repeat(Math.min(e.depth, 5));
+                    return `${indent}[${e.source}:${e.role}] ${e.text || "(no text)"}`;
+                });
+                return {
+                    content: [{ type: "text", text: `Frame ${frameId} elements (${elements.length}):\n${formatted.join("\n")}` }],
+                };
+            }
+            case "control-recording": {
+                const action = args.action;
+                if (!action) {
+                    return { content: [{ type: "text", text: "Error: action is required" }] };
+                }
+                let endpoint;
+                if (action === "start-audio")
+                    endpoint = "/audio/start";
+                else if (action === "stop-audio")
+                    endpoint = "/audio/stop";
+                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}`);
+                return {
+                    content: [{ type: "text", text: `Recording action '${action}' executed.` }],
                 };
             }
             default: