screenpipe-mcp 0.20.2 → 0.20.3

package/src/index.ts

@@ -32,8 +32,9 @@ import {
 } from "./qualified-value";
 import { discoverTeamConfig } from "./team-config";
 import { teamFrameContent, teamFramePath } from "./team-frame";
-import { WORKFLOW_TOOLS, readWorkflowTool, frameAutomationContent, inputEventContent } from "./workflow-tools";
+import { WORKFLOW_TOOLS, readWorkflowTool, frameAutomationContent } from "./workflow-tools";
 import { PKG_VERSION } from "./version";
+import { BUNDLED_SKILLS_TOOL, readBundledSkills } from "./bundled-skills";
 import { formatForElementPurpose } from "./element-format";
 import { buildActivitySummaryResult } from "./activity-summary-tool";
 import {
@@ -41,6 +42,8 @@ import {
   normalizeTime,
   normalizeTimeFields,
 } from "./time-normalization";
+import { createCallObserver, currentMcpRequestId, observeMcpError, observeSearchResult } from "./call-observation";
+import { formatSearchHit, searchContentCap, searchResultHeader } from "./search-result";
 import { resolveScreenpipeApiBase } from "./api-base";
 
 initMcpTelemetry({ transport: "stdio" });
@@ -323,10 +326,11 @@ const server = new Server(
 // ---------------------------------------------------------------------------
 const TOOLS: Tool[] = [
   ...WORKFLOW_TOOLS,
+  BUNDLED_SKILLS_TOOL,
   {
     name: "search-content",
     description:
-      "Search screen text, audio transcriptions, input events, memories, and parsed app data. Returns timestamped results with app context. " +
+      "Search screen text, audio transcriptions, input events, memories, and parsed app data. Returns timestamped results with app context and starred markers. For starred work, set starred_only=true and a time range; no session lookup needed. " +
       "USE WHEN: you need the actual text/content of a moment — quotes, screen text, transcript lines, or compact parsed messages, emails, tasks, documents, and code review — 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). " +
@@ -356,6 +360,8 @@ const TOOLS: Tool[] = [
           type: "string",
           description: "ISO 8601, relative time, or local calendar ('today', 'yesterday', 'tomorrow', 'YYYY-MM-DD'). Defaults to now.",
         },
+        starred_only: { type: "boolean", description: "Only captures inside starred intervals. Use for starred work; omit for ordinary searches. Applied before pagination." },
+        starred_session_id: { type: "string", description: "Optional exact session ID already known from activity-summary. Usually use starred_only instead." },
         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" },
         frame_id: { type: "integer", description: "With content_type='parsed', return parsed data attached to one frame." },
@@ -441,6 +447,7 @@ const TOOLS: Tool[] = [
   {
     name: "activity-summary",
     description:
+      "Includes up to ten recent starred intervals for this time range, even without captured content. Stars indicate user intent, not duration or completion. " +
       "Rich activity overview: authoritative active minutes, app/window time, edited document paths, key text, and audio transcriptions, with optional parsed task context when available. " +
       "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. " +
@@ -452,6 +459,7 @@ const TOOLS: Tool[] = [
       properties: {
         start_time: { type: "string", description: "ISO 8601, relative (e.g. '3h ago'), or local calendar ('today', 'yesterday', 'tomorrow', 'YYYY-MM-DD')" },
         end_time: { type: "string", description: "ISO 8601, relative (e.g. 'now'), or local calendar ('today', 'yesterday', 'tomorrow', 'YYYY-MM-DD')" },
+        include_starred: { type: "boolean", description: "Include bounded starred-session context (default true; omitted for app/data-restricted reads)." },
         app_name: { type: "string", description: "Optional app name filter to focus on one app" },
         include_parsed_context: {
           type: "boolean",
@@ -1318,6 +1326,7 @@ async function fetchAPI(
       headers: {
         "Content-Type": "application/json",
         ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        ...(currentMcpRequestId() ? { "x-screenpipe-request-id": currentMcpRequestId()! } : {}),
         "x-screenpipe-client": "mcp",
         "x-screenpipe-agent": currentMcpClient(),
         ...options.headers,
@@ -1399,11 +1408,18 @@ function screenTag(textSource: unknown): string {
 // ---------------------------------------------------------------------------
 // Tool handlers
 // ---------------------------------------------------------------------------
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+const observeCall = createCallObserver({
+  tools: [...TOOLS.map(tool => tool.name), ...TEAM_TOOLS.map(tool => tool.name), ...WORKFLOW_TOOLS.map(tool => tool.name), BUNDLED_SKILLS_TOOL.name],
+  transport: "stdio", client: currentMcpClient,
+  send: (payload, signal) => callAPI("/internal/telemetry/mcp-call", { method: "POST", body: JSON.stringify(payload), signal }),
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => observeCall(request.params.name, async () => {
   const { name, arguments: args } = request.params;
 
+  if (name === BUNDLED_SKILLS_TOOL.name) return readBundledSkills(args);
+
   if (!args) {
-    throw new Error("Missing arguments");
+    throw Object.assign(new Error("Missing arguments"), { status: 400 });
   }
 
   try {
@@ -1600,12 +1616,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         // 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 effectiveCap = searchContentCap(userCap);
         const params = new URLSearchParams();
         for (const [key, value] of Object.entries(normalized)) {
           if (value !== null && value !== undefined) {
@@ -1617,6 +1628,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const data = await response.json();
         const results = data.data || [];
         const pagination = data.pagination || {};
+        observeSearchResult(results.length, false);
 
         if (results.length === 0) {
           return {
@@ -1638,71 +1650,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
         const formattedResults: string[] = [];
         const images: Array<{ data: string; context: string }> = [];
+        let truncated = false;
 
         for (const result of results) {
           const content = result.content;
           if (!content) continue;
-
-          if (result.type === "OCR") {
-            const tagsStr = content.tags?.length ? `\nTags: ${content.tags.join(", ")}` : "";
-            // result.type is "OCR" by historical naming, but content.text_source
-            // tells us if the text actually came from the accessibility tree
-            // (primary path) or OCR (fallback). Use it to label honestly.
-            const tag = screenTag(content.text_source);
-            formattedResults.push(
-              `${tag} ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
-                `${content.timestamp || ""}\n` +
-                `${truncateMiddle(content.text || "", effectiveCap)}` +
-                tagsStr
-            );
-            if (includeFrames && content.frame) {
-              images.push({
-                data: content.frame,
-                context: `${content.app_name} at ${content.timestamp}`,
-              });
-            }
-          } else if (result.type === "Audio") {
-            const tagsStr = content.tags?.length ? `\nTags: ${content.tags.join(", ")}` : "";
-            formattedResults.push(
-              `[Audio] ${content.device_name || "?"}\n` +
-                `${content.timestamp || ""}\n` +
-                `${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` +
-                `${truncateMiddle(content.text || "", effectiveCap)}`
-            );
-          } else if (result.type === "Input") {
-            formattedResults.push(inputEventContent(content, effectiveCap));
-          } else if (result.type === "Memory") {
-            const tagsStr = content.tags?.length ? ` [${content.tags.join(", ")}]` : "";
-            const importance =
-              content.importance != null ? ` (importance: ${content.importance})` : "";
-            // frame_id links a memory back to the exact moment — jump there with
-            // frame-context / get-frame-elements (frame_id=N).
-            const frameRef = content.frame_id != null ? ` frame:${content.frame_id}` : "";
-            formattedResults.push(
-              `[Memory #${content.id}]${tagsStr}${importance}${frameRef}\n` +
-                `${content.created_at || ""}\n` +
-                `${truncateMiddle(content.content || "", effectiveCap)}`
-            );
-          } else if (result.type === "Parsed") {
-            formattedResults.push(
-              `[Parsed] ${content.app_name || "?"} | ${content.window_name || "?"} | frame ${content.frame_id || "?"}\n` +
-                `${content.timestamp || ""}\n` +
-                `${truncateMiddle(content.text || "", effectiveCap)}`
-            );
+          const hit = formatSearchHit(result, effectiveCap);
+          if (hit) { formattedResults.push(hit.text); truncated ||= hit.truncated; }
+          if (includeFrames && result.type === "OCR" && content.frame) {
+            images.push({ data: content.frame, context: `${content.app_name} at ${content.timestamp}` });
           }
         }
 
-        const header =
-          `Results: ${results.length}/${pagination.total || "?"}` +
-          (pagination.total > results.length
-            ? ` (use offset=${(pagination.offset || 0) + results.length} for more)`
-            : "");
+        observeSearchResult(results.length, truncated);
+        const header = searchResultHeader(results.length, pagination);
 
         // Co-occurring tags (only present when include_related=true + tags set).
         // Compact one-liner per namespace so it's cheap to read.
@@ -2432,6 +2393,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw new Error(`Unknown tool: ${name}`);
     }
   } catch (error) {
+    observeMcpError(error);
     const errorMessage = error instanceof Error ? error.message : "Unknown error";
     if (!(error instanceof BackendDownError) && !(error instanceof BackendHttpError)) {
       captureMcpMessage("tool call failed", "error", { phase: "tool_call", tool: name });
@@ -2443,7 +2405,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       content: [{ type: "text", text: `Error executing ${name}: ${errorMessage}` }],
     };
   }
-});
+}));
 
 // Run the server
 async function main() {
@@ -2453,6 +2415,16 @@ async function main() {
   console.error(`[screenpipe-mcp] v${PKG_VERSION} phase=connect target=${SCREENPIPE_API}`);
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  // The SDK does not close its transport on stdin EOF. An outstanding fetch
+  // can otherwise keep an abandoned helper alive indefinitely after its host
+  // exits. This process belongs to this one stdio client only.
+  process.stdin.once("end", () => {
+    const deadline = setTimeout(() => process.exit(0), 500);
+    void server.close()
+      .then(() => flushMcpTelemetry(250))
+      .catch(() => {})
+      .finally(() => { clearTimeout(deadline); process.exit(0); });
+  });
   console.error("[screenpipe-mcp] phase=connected transport=stdio");
   // Warm the API key in the background so the first tool call doesn't pay the
   // discovery latency. Never awaited here — key discovery must not gate attach.

package/src/search-result.test.ts

@@ -0,0 +1,22 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+import { expect, it } from "vitest";
+import { formatSearchHit, searchContentCap, searchResultHeader } from "./search-result";
+it("preserves real references through truncation, without inventing missing IDs", () => {
+  const hit = formatSearchHit({type:"OCR",content:{frame_id:72,text:"HEAD"+"x".repeat(3000)+"TAIL",text_source:"accessibility"}},10)!;
+  expect(hit.truncated).toBe(true); expect(hit.text).toContain("frame_id=72"); expect(hit.text).toContain("screenpipe://frame/72");
+  expect(hit.text).toContain("HEAD"); expect(hit.text).toContain("TAIL"); expect(hit.text.length).toBeLessThan(250);
+  expect(formatSearchHit({type:"OCR",content:{text:"no source"}},100)!.text).not.toContain("Source:");
+});
+it("keeps audio references and input text, including explicit unlimited reads", () => {
+  expect(formatSearchHit({type:"Audio",content:{chunk_id:31,timestamp:"2026-10-01T00:00:00Z",transcription:"speech"}},100)!.text).toContain("chunk_id=31");
+  const input={type:"Input",content:{frame_id:72,text_content:"long input"}};
+  expect(formatSearchHit(input,3)!.truncated).toBe(true);
+  expect(formatSearchHit(input,0)!.text).toContain("long input"); expect(formatSearchHit(input,0)!.truncated).toBe(false);
+});
+it("only suggests an offset when a next page exists", () => {
+  expect(searchResultHeader(5,{total:10,offset:5})).not.toContain("offset=");
+  expect(searchResultHeader(5,{total:10,offset:0})).toContain("offset=5");
+  expect(searchResultHeader(0,{total:10,offset:0})).not.toContain("offset=");
+  expect(searchContentCap(undefined)).toBe(1000); expect(searchContentCap(-1)).toBe(1000);
+});

package/src/search-result.ts

@@ -0,0 +1,75 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+import { inputEventContent } from "./workflow-tools";
+
+export const DEFAULT_SEARCH_CONTENT_TRUNCATE = 1000;
+
+export function searchContentCap(value: unknown): number {
+  const cap = typeof value === "number" ? value : Number(value);
+  return value !== undefined && Number.isFinite(cap) && cap >= 0
+    ? Math.floor(cap) : DEFAULT_SEARCH_CONTENT_TRUNCATE;
+}
+
+export function truncateSearchText(text: string, cap: number): string {
+  if (cap === 0 || text.length <= cap) return text;
+  const left = Math.floor(cap / 2);
+  return text.slice(0, left) + `…[${text.length - cap} chars truncated; inspect the source or narrow the search]…` + text.slice(text.length - (cap - left));
+}
+
+function numericId(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+/** Source identifiers come from the backend, never from result position or text. */
+export function formatSearchHit(result: any, cap: number): { text: string; truncated: boolean } | null {
+  const c = result.content;
+  if (!c || typeof c !== "object") return null;
+  const frame = numericId(c.frame_id);
+  const chunk = numericId(c.chunk_id);
+  const frameRef = frame === undefined ? "" : `\nSource: frame_id=${frame}; screenpipe://frame/${frame}`;
+  const tags = Array.isArray(c.tags) && c.tags.length ? `\nTags: ${c.tags.join(", ")}` : "";
+  let label: string, body: string, source = frameRef;
+  switch (result.type) {
+    case "OCR":
+      label = c.text_source === "accessibility" ? "[Screen·a11y]" : c.text_source === "ocr" ? "[Screen·ocr]" : "[Screen]";
+      label += ` ${c.app_name || "?"} | ${c.window_name || "?"}`;
+      body = c.text || "";
+      break;
+    case "UI": case "Accessibility":
+      label = `[Accessibility] ${c.app_name || "?"} | ${c.window_name || "?"}`;
+      body = c.text || "";
+      break;
+    case "Audio":
+      label = `[Audio] ${c.device_name || "?"}`;
+      body = c.transcription || "";
+      source = chunk === undefined ? "" : `\nSource: chunk_id=${chunk}`;
+      if (typeof c.timestamp === "string" && Number.isFinite(Date.parse(c.timestamp))) {
+        source += `${source ? "; " : "\nSource: "}screenpipe://timeline?timestamp=${encodeURIComponent(c.timestamp)}`;
+      }
+      break;
+    case "Parsed":
+      label = `[Parsed] ${c.app_name || "?"} | ${c.window_name || "?"} | frame ${frame ?? "?"}`;
+      body = c.text || "";
+      break;
+    case "Memory":
+      label = `[Memory #${c.id}]${c.importance != null ? ` (importance: ${c.importance})` : ""}`;
+      body = c.content || "";
+      break;
+    case "Input":
+      return { text: `${result.starred ? "[Starred moment]\n" : ""}${inputEventContent(c, cap === 0 ? Number.MAX_SAFE_INTEGER : cap)}${source}`, truncated: cap > 0 && typeof c.text_content === "string" && c.text_content.length > cap };
+    default: return null;
+  }
+  body = String(body);
+  return {
+    text: `${result.starred ? "[Starred moment]\n" : ""}${label}\n${c.timestamp || c.created_at || ""}${source}\n${truncateSearchText(body, cap)}${tags}`,
+    truncated: cap > 0 && body.length > cap,
+  };
+}
+
+export function searchResultHeader(count: number, pagination: any): string {
+  const total = typeof pagination.total === "number" ? pagination.total : undefined;
+  const offset = typeof pagination.offset === "number" ? pagination.offset : 0;
+  return `Results: ${count}/${total ?? "?"}` +
+    (count > 0 && total !== undefined && offset + count < total ? ` (use offset=${offset + count} for more)` : "");
+}

package/src/stdio-lifecycle.test.ts

@@ -0,0 +1,48 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+import { it, expect } from "vitest";
+import { spawn, execFileSync, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { createServer } from "node:http";
+import { once } from "node:events";
+import path from "node:path";
+const sleep=(ms:number)=>new Promise(resolve=>setTimeout(resolve,ms));
+async function until(predicate:()=>boolean, timeout=2000) {
+  const end=Date.now()+timeout;
+  while(!predicate() && Date.now()<end) await sleep(10);
+  expect(predicate()).toBe(true);
+}
+it("reaps a helper on EOF during a hung read while another client remains usable",async()=>{
+  const root=path.resolve(__dirname,"..");
+  execFileSync("bun",["run","build"],{cwd:root,stdio:"pipe",timeout:120000});
+  let hanging=false;
+  const api=createServer((req,res)=>{
+    if(req.url?.includes("q=hang")){hanging=true;return;}
+    res.setHeader("Content-Type","application/json");res.end(JSON.stringify({data:[],pagination:{total:0}}));
+  });
+  await new Promise<void>(resolve=>api.listen(0,"127.0.0.1",resolve));
+  const address=api.address();if(!address||typeof address==='string')throw new Error('fixture unavailable');
+  const port=address.port;
+  const children:ChildProcessWithoutNullStreams[]=[];
+  async function start(){
+    const child=spawn(process.execPath,[path.join(root,'dist/cli.js')],{env:{PATH:process.env.PATH||'',SCREENPIPE_LOCAL_API_KEY:'fixture',SCREENPIPE_LOCAL_API_URL:`http://127.0.0.1:${port}`,SCREENPIPE_DISABLE_TELEMETRY:'1'},stdio:'pipe'});
+    children.push(child);let output='';child.stdout.on('data',part=>output+=part);child.stderr.resume();
+    const send=(value:unknown)=>child.stdin.write(JSON.stringify(value)+'\n');
+    send({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1'}}});
+    await until(()=>output.includes('"id":1'));
+    send({jsonrpc:'2.0',method:'notifications/initialized'});
+    return {child,send,output:()=>output};
+  }
+  try{
+    const abandoned=await start(), live=await start();
+    abandoned.send({jsonrpc:'2.0',id:2,method:'tools/call',params:{name:'search-content',arguments:{q:'hang'}}});
+    await until(()=>hanging);abandoned.child.stdin.end();
+    await until(()=>abandoned.child.exitCode!==null);
+    expect(live.child.exitCode).toBeNull();
+    live.send({jsonrpc:'2.0',id:2,method:'tools/call',params:{name:'search-content',arguments:{}}});
+    await until(()=>live.output().includes('No results'));
+    live.child.stdin.end();await until(()=>live.child.exitCode!==null);
+  } finally {
+    for(const child of children)if(child.exitCode===null&&child.signalCode===null){child.kill('SIGKILL');await once(child,'exit');}
+    api.closeAllConnections();await new Promise<void>(resolve=>api.close(()=>resolve()));
+  }
+},15000);

package/src/workflow-transport.test.ts

@@ -20,7 +20,7 @@ it("discovers and retrieves workflow targeting context through the built MCP tra
     if(req.url?.startsWith("/workflows?")) res.end(JSON.stringify({data:[{id,title:"Invoice review"},{id:uuidId,title:"Maintained workflow"}]}));
     else if(req.url?.startsWith(`/workflows/${id}?`)) res.end(JSON.stringify({id,workflow:{stages:[{name:"Review"}]},automationEvidence:[{status:"no_captured_frame",actionTarget:"unknown"}]}));
     else if(req.url?.startsWith(`/workflows/${uuidId}?`)) res.end(JSON.stringify({id:uuidId,workflow:{stages:[{name:"Review maintained workflow"}]}}));
-    else if(req.url?.startsWith("/search?")) res.end(JSON.stringify({data:[{type:"Input",content:{id:8,event_type:"click",frame_id:7,x:40,y:60,element_role:"AXButton",element_name:"Approve"}}],pagination:{total:1,offset:0,limit:5}}));
+    else if(req.url?.startsWith("/search?")) res.end(JSON.stringify({data:[{starred:req.url.includes("starred_only=true"),type:"Input",content:{id:8,event_type:"click",frame_id:7,x:40,y:60,element_role:"AXButton",element_name:"Approve"}}],pagination:{total:1,offset:0,limit:5}}));
     else if(req.url === "/frames/7/context?include_empty=true") res.end(JSON.stringify({frame_id:7,text_source:"accessibility",nodes:[{role:"AXButton",text:"",bounds:{left:0.25,top:0.5,width:0.125,height:0.0625},properties:{automation_id:"approve"}}]}));
     else { res.writeHead(404);res.end("{}"); }
   });
@@ -33,6 +33,14 @@ it("discovers and retrieves workflow targeting context through the built MCP tra
     await client.connect(transport);
     const tools=await client.listTools();
     expect(tools.tools.map(t=>t.name)).toEqual(expect.arrayContaining(["list-workflows","get-workflow"]));
+    expect(tools.tools.some(t=>t.name === "list-starred-sessions")).toBe(false);
+    expect(tools.tools.find(t=>t.name === "search-content")?.inputSchema.properties).toHaveProperty("starred_only");
+    const before = requests.length;
+    const starred = await client.callTool({name:"search-content",arguments:{starred_only:true,start_time:"2026-10-02T00:00:00Z",end_time:"2026-10-03T00:00:00Z",limit:5}});
+    expect(starred.isError).not.toBe(true);
+    expect(JSON.stringify(starred)).toContain("[Starred moment]");
+    expect(requests.slice(before)).toHaveLength(1);
+    expect(requests.at(-1)).toContain("starred_only=true");
     const listed=await client.callTool({name:"list-workflows",arguments:{q:"invoice"}});
     expect(JSON.stringify(listed)).toContain(id);
     const detail=await client.callTool({name:"get-workflow",arguments:{id}});