screenpipe-mcp 0.20.0 → 0.20.3

package/src/http-server.test.ts

@@ -185,6 +185,69 @@ describe("isAuthorized", () => {
 });
 
 describe("buildHttpServer", () => {
+  it.each([
+    { name: "local API key", localKey: "upstream-secret", apiKey: "other-key", succeeds: true },
+    { name: "API key fallback", localKey: "", apiKey: "upstream-secret", succeeds: true },
+    { name: "missing upstream key", localKey: "", apiKey: "", succeeds: false },
+    { name: "invalid upstream key", localKey: "wrong-key", apiKey: "", succeeds: false },
+  ])("authenticates upstream independently of the MCP bearer: $name", async ({ localKey, apiKey, succeeds }) => {
+    const requests: Array<{ path: string; authorization: string | undefined }> = [];
+    const api = createServer((request, response) => {
+      requests.push({ path: request.url!, authorization: request.headers.authorization });
+      response.setHeader("content-type", "application/json");
+      if (request.headers.authorization !== "Bearer upstream-secret") {
+        response.writeHead(403).end(JSON.stringify({ error: "unauthorized" }));
+        return;
+      }
+      response.end(JSON.stringify({
+        data: [{ starred: true, type: "OCR", content: { text: "synthetic authenticated result" } }],
+        pagination: { total: 1 },
+      }));
+    });
+    await new Promise<void>(resolve => api.listen(0, "127.0.0.1", resolve));
+    const apiPort = (api.address() as { port: number }).port;
+    vi.stubEnv("SCREENPIPE_API_URL", `http://127.0.0.1:${apiPort}`);
+    vi.stubEnv("SCREENPIPE_LOCAL_API_KEY", localKey);
+    vi.stubEnv("SCREENPIPE_API_KEY", apiKey);
+    const server = buildHttpServer({
+      mcpPort: 0,
+      screenpipePort: apiPort,
+      host: "127.0.0.1",
+      apiKey: "mcp-client-secret",
+    });
+    const client = new Client({ name: "integration-test", version: "1.0.0" });
+    try {
+      await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
+      const url = new URL(`http://127.0.0.1:${(server.address() as { port: number }).port}/mcp`);
+      await client.connect(new StreamableHTTPClientTransport(url, {
+        requestInit: { headers: { authorization: "Bearer mcp-client-secret" } },
+      }));
+      const call = client.callTool({ name: "search_content", arguments: { q: "fixture", limit: 1, starred_only: true } });
+      if (succeeds) {
+        const result = await call;
+        expect(JSON.stringify(result)).toContain("[Starred moment]");
+        expect(requests[0].path).toContain("starred_only=true");
+        expect(result.isError).not.toBe(true);
+        expect(result.content).toEqual([expect.objectContaining({
+          type: "text", text: expect.stringContaining("synthetic authenticated result"),
+        })]);
+        await vi.waitFor(() => expect(requests.some(request => request.path === "/internal/telemetry/mcp-value")).toBe(true));
+        expect(requests.every(request => request.authorization === "Bearer upstream-secret")).toBe(true);
+      } else {
+        await expect(call).rejects.toThrow("HTTP error: 403");
+        expect(requests).toHaveLength(1);
+      }
+      expect(requests[0].path).toBe("/search?q=fixture&limit=1&starred_only=true");
+      expect(requests.some(request => request.authorization === "Bearer mcp-client-secret")).toBe(false);
+    } finally {
+      await client.close();
+      server.closeAllConnections();
+      api.closeAllConnections();
+      await Promise.all([server, api].map(s => new Promise<void>(resolve => s.close(() => resolve()))));
+      vi.unstubAllEnvs();
+    }
+  });
+
   it("attributes retrievals per HTTP session and excludes empty or failed searches", async () => {
     const searches: Array<{ source: unknown; agent: unknown }> = [];
     const outcomes: unknown[] = [];
@@ -193,6 +256,11 @@ describe("buildHttpServer", () => {
       if (request.url?.startsWith("/search?")) {
         searches.push({ source: request.headers["x-screenpipe-client"], agent: request.headers["x-screenpipe-agent"] });
         const q = new URL(request.url, "http://fixture").searchParams.get("q");
+        if (q === "broad") {
+          response.statusCode = 400;
+          response.end(JSON.stringify({ error: "starred search covers more than 100 disjoint intervals; narrow start_time/end_time" }));
+          return;
+        }
         if (q === "failed") response.statusCode = 500;
         response.end(JSON.stringify({ data: q === "empty" ? [] : [{ type: "OCR", content: { text: "fixture result" } }] }));
       } else if (request.url === "/internal/telemetry/mcp-value") {
@@ -237,6 +305,7 @@ describe("buildHttpServer", () => {
       ]));
       await clients[0].callTool({ name: "search_content", arguments: { q: "empty" } });
       await expect(clients[0].callTool({ name: "search_content", arguments: { q: "failed" } })).rejects.toThrow();
+      await expect(clients[0].callTool({ name: "search_content", arguments: { q: "broad", starred_only: true } })).rejects.toThrow("narrow start_time/end_time");
       expect(outcomes).toHaveLength(3);
     } finally {
       await Promise.all(clients.map(client => client.close()));

package/src/http-server.ts

@@ -30,7 +30,10 @@ import {
   flushMcpTelemetry,
   initMcpTelemetry,
 } from "./telemetry";
+import { createCallObserver, currentMcpRequestId, observeSearchResult } from "./call-observation";
+import { formatSearchHit, searchContentCap, searchResultHeader } from "./search-result";
 import { PKG_VERSION } from "./version";
+import { BUNDLED_SKILLS_TOOL, readBundledSkills } from "./bundled-skills";
 import { normalizeTimeFields } from "./time-normalization";
 import { createMcpQualifiedValueReporter, resolveMcpClient, type McpClient } from "./qualified-value";
 
@@ -154,7 +157,7 @@ const TOOLS = [
     name: "search_content",
     description:
       "Search screenpipe's recorded content: screen text, audio transcriptions, input events, and parsed app data. " +
-      "Returns timestamped results with app context. " +
+      "Returns timestamped results with app context and starred markers. For starred work, set starred_only=true and a time range. " +
       "Call with no parameters to get recent activity.",
     inputSchema: {
       type: "object" as const,
@@ -171,6 +174,7 @@ const TOOLS = [
           default: "all",
         },
         limit: { type: "integer", description: "Max results. Default: 10" },
+        max_content_length: { type: "integer", minimum: 0, description: "Text characters per result; default 1000. Use 0 only for an explicitly scoped full-text read." },
         offset: { type: "integer", description: "Skip N results for pagination. Default: 0" },
         start_time: {
           type: "string",
@@ -180,6 +184,8 @@ const TOOLS = [
           type: "string",
           description: "ISO 8601, relative, or local calendar ('today', 'yesterday', 'tomorrow', 'YYYY-MM-DD')",
         },
+        starred_only: { type: "boolean", description: "Only captures inside starred intervals; applied before pagination. Omit for unrelated searches." },
+        starred_session_id: { type: "string", description: "Optional known session ID to restrict the search." },
         app_name: {
           type: "string",
           description: "Filter by app (e.g., 'Google Chrome', 'Slack', 'zoom.us')",
@@ -201,11 +207,14 @@ function makeFetchAPI(screenpipePort: number, client: () => McpClient) {
     /\/+$/,
     "",
   );
+  const apiKey = process.env.SCREENPIPE_LOCAL_API_KEY || process.env.SCREENPIPE_API_KEY;
   return async (endpoint: string, options: RequestInit = {}): Promise<Response> =>
     fetch(`${base}${endpoint}`, {
       ...options,
       headers: {
         "Content-Type": "application/json",
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        ...(currentMcpRequestId() ? { "x-screenpipe-request-id": currentMcpRequestId()! } : {}),
         "x-screenpipe-client": "mcp",
         "x-screenpipe-agent": client(),
         ...options.headers,
@@ -227,12 +236,15 @@ async function handleSearchContent(
 
   const response = await fetchAPI(`/search?${params.toString()}`);
   if (!response.ok) {
-    throw new Error(`HTTP error: ${response.status}`);
+    const body = await response.json().catch(() => ({}));
+    const detail = typeof body?.error === "string" ? `: ${body.error.slice(0, 500)}` : "";
+    throw Object.assign(new Error(`HTTP error: ${response.status}${detail}`), { status: response.status });
   }
 
   const data = await response.json();
   const results = data.data || [];
   const pagination = data.pagination || {};
+  observeSearchResult(results.length, false);
 
   if (results.length === 0) {
     return {
@@ -245,43 +257,12 @@ async function handleSearchContent(
     };
   }
 
-  const formattedResults: string[] = [];
-  for (const result of results) {
-    const content = result.content;
-    if (!content) continue;
-
-    if (result.type === "OCR") {
-      formattedResults.push(
-        `[OCR] ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
-          `${content.timestamp || ""}\n` +
-          `${content.text || ""}`
-      );
-    } else if (result.type === "Audio") {
-      formattedResults.push(
-        `[Audio] ${content.device_name || "?"}\n` +
-          `${content.timestamp || ""}\n` +
-          `${content.transcription || ""}`
-      );
-    } else if (result.type === "UI" || result.type === "Accessibility") {
-      formattedResults.push(
-        `[Accessibility] ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
-          `${content.timestamp || ""}\n` +
-          `${content.text || ""}`
-      );
-    } else if (result.type === "Parsed") {
-      formattedResults.push(
-        `[Parsed] ${content.app_name || "?"} | ${content.window_name || "?"} | frame ${content.frame_id || "?"}\n` +
-          `${content.timestamp || ""}\n` +
-          `${content.text || ""}`
-      );
-    }
-  }
-
-  const header =
-    `Results: ${results.length}/${pagination.total || "?"}` +
-    (pagination.total > results.length
-      ? ` (use offset=${(pagination.offset || 0) + results.length} for more)`
-      : "");
+  const cap = searchContentCap(args.max_content_length);
+  const hits = results.map((result: unknown) => formatSearchHit(result, cap))
+    .filter((hit: ReturnType<typeof formatSearchHit>) => hit !== null);
+  observeSearchResult(results.length, hits.some((hit: NonNullable<ReturnType<typeof formatSearchHit>>) => hit.truncated));
+  const formattedResults = hits.map((hit: NonNullable<ReturnType<typeof formatSearchHit>>) => hit.text);
+  const header = searchResultHeader(results.length, pagination);
 
   if (formattedResults.length > 0) qualifiedValue.searchResult();
 
@@ -317,14 +298,22 @@ function createMcpServer(screenpipePort: number): Server {
     client,
   );
 
-  s.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  s.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...TOOLS, BUNDLED_SKILLS_TOOL] }));
 
-  s.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const observeCall = createCallObserver({
+    tools: [...TOOLS.map(tool => tool.name), BUNDLED_SKILLS_TOOL.name], transport: "http", client,
+    send: async (payload, signal) => {
+      const response = await fetchAPI("/internal/telemetry/mcp-call", { method: "POST", body: JSON.stringify(payload), signal });
+      if (!response.ok) throw new Error("Telemetry unavailable");
+    },
+  });
+  s.setRequestHandler(CallToolRequestSchema, async (request) => observeCall(request.params.name, async () => {
     const { name, arguments: args } = request.params;
-    if (!args) throw new Error("Missing arguments");
+    if (name === BUNDLED_SKILLS_TOOL.name) return readBundledSkills(args);
+    if (!args) throw Object.assign(new Error("Missing arguments"), { status: 400 });
     if (name === "search_content") return handleSearchContent(fetchAPI, args, qualifiedValue);
-    throw new Error(`Unknown tool: ${name}`);
-  });
+    throw Object.assign(new Error(`Unknown tool: ${name}`), { status: 400 });
+  }));
 
   return s;
 }

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/installers.test.ts

@@ -0,0 +1,143 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { createServer, type Server } from "node:http";
+import { unzipSync } from "fflate";
+import { VERSIONED_MANIFEST_SCHEMAS } from "@anthropic-ai/mcpb/schemas";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const root = path.resolve(__dirname, "..");
+const sandbox = mkdtempSync(path.join(tmpdir(), "screenpipe-installer-test-"));
+let local: Record<string, Uint8Array>;
+let cloud: Record<string, Uint8Array>;
+let api: Server;
+let baseUrl: string;
+let status = 200;
+let seenAuth: string | undefined;
+let seenQuery: string | null;
+const parse = (archive: Record<string, Uint8Array>, file: string) =>
+  JSON.parse(Buffer.from(archive[file]).toString("utf8"));
+
+beforeAll(async () => {
+  execFileSync("bun", ["run", "build:installers"], { cwd: root, timeout: 120_000, stdio: "inherit" });
+  local = unzipSync(readFileSync(path.join(root, "installers/screenpipe-local.mcpb")));
+  cloud = unzipSync(readFileSync(path.join(root, "installers/screenpipe-cloud.zip")));
+  for (const [file, bytes] of Object.entries(local)) {
+    const target = path.join(sandbox, file);
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(target, bytes);
+  }
+  api = createServer((req, res) => {
+    const url = new URL(req.url!, "http://localhost");
+    if (url.pathname !== "/search") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end("{}");
+      return;
+    }
+    seenAuth = req.headers.authorization;
+    seenQuery = url.searchParams.get("q");
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(status === 200 ? {
+      data: [{ type: "OCR", content: { text: "synthetic installer evidence", timestamp: "2026-01-02T12:00:00Z", app_name: "Fixture", frame_id: 1 } }],
+      pagination: { total: 1, limit: 5, offset: 0 },
+    } : { error: "unauthorized" }));
+  });
+  await new Promise<void>((resolve) => api.listen(0, "127.0.0.1", resolve));
+  baseUrl = `http://127.0.0.1:${(api.address() as { port: number }).port}`;
+}, 130_000);
+
+afterAll(async () => {
+  if (api) await new Promise<void>((resolve) => api.close(() => resolve()));
+  rmSync(sandbox, { recursive: true, force: true });
+});
+
+async function withInstalledClient(run: (client: Client) => Promise<void>) {
+  const manifest = parse(local, "manifest.json");
+  const config = manifest.server.mcp_config;
+  const settings: Record<string, string> = { api_url: baseUrl, api_key: "sp-installer-fixture" };
+  const env: Record<string, string> = {
+    PATH: "", NODE_PATH: "", SCREENPIPE_DISABLE_TELEMETRY: "1",
+    SCREENPIPE_ENTERPRISE_TOKEN: "sk_ent_fixture", SCREENPIPE_TEAM_API_URL: baseUrl,
+  };
+  for (const [key, value] of Object.entries(config.env)) {
+    env[key] = String(value).replace(/\$\{user_config\.(\w+)\}/g, (_, name) => settings[name]);
+  }
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: config.args.map((arg: string) => arg.replace("${__dirname}", sandbox)),
+    cwd: sandbox, env, stderr: "pipe",
+  });
+  const client = new Client({ name: "installer-fixture", version: "1.0.0" });
+  try {
+    await client.connect(transport);
+    await run(client);
+  } finally {
+    await transport.close();
+  }
+}
+
+describe("installable MCP artifacts", () => {
+  it("ships a schema-valid local extension with only the required files", () => {
+    const manifest = parse(local, "manifest.json");
+    expect(VERSIONED_MANIFEST_SCHEMAS["0.3"].safeParse(manifest).success).toBe(true);
+    expect(Object.keys(local).sort()).toEqual([
+      "LICENSE.md", "README.md", "dist/index.js", "icon.png", "manifest.json", "package.json",
+    ]);
+    expect(manifest.version).toBe(JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).version);
+    expect(manifest.user_config.api_key.sensitive).toBe(true);
+    expect(manifest.user_config.api_key.default).toBeUndefined();
+    expect(manifest.user_config.api_key.required).toBe(false);
+    expect(manifest.user_config.api_url.default).toBe("http://127.0.0.1:3030");
+    expect(local[manifest.server.entry_point]).toBeDefined();
+  });
+
+  it("initializes and searches from the extracted archive with no runtime dependencies", async () => {
+    status = 200;
+    await withInstalledClient(async (client) => {
+      const list = await client.listTools();
+      expect(list.tools.some((tool) => tool.name === "search-content")).toBe(true);
+      const result = await client.callTool({ name: "search-content", arguments: {
+        q: "synthetic", start_time: "2026-01-02T00:00:00Z", end_time: "2026-01-03T00:00:00Z", limit: 5,
+      } });
+      expect(result.isError).not.toBe(true);
+      expect(JSON.stringify(result)).toContain("synthetic installer evidence");
+      expect(seenAuth).toBe("Bearer sp-installer-fixture");
+      expect(seenQuery).toBe("synthetic");
+    });
+  }, 15_000);
+
+  it("reports rejected authentication rather than successful retrieval", async () => {
+    status = 401;
+    await withInstalledClient(async (client) => {
+      const result = await client.callTool({ name: "search-content", arguments: { q: "synthetic", limit: 1 } });
+      expect(result.isError).toBe(true);
+      expect(JSON.stringify(result)).not.toContain("synthetic installer evidence");
+    });
+  }, 15_000);
+
+  it("keeps all cloud hosts on the same OAuth endpoint without embedding credentials", () => {
+    expect(Object.keys(cloud).sort()).toEqual([
+      ".claude-plugin/plugin.json", ".codex-plugin/plugin.json", ".mcp.json",
+      "LICENSE.md", "README.md", "assets/icon.png", "mcp.json", "plugin.json",
+    ]);
+    const portable = parse(cloud, "plugin.json");
+    const codex = parse(cloud, ".codex-plugin/plugin.json");
+    const claude = parse(cloud, ".claude-plugin/plugin.json");
+    for (const manifest of [portable, codex, claude]) {
+      expect(manifest.name).toBe("screenpipe-cloud");
+      expect(manifest.version).toBe(portable.version);
+    }
+    const endpoint = "https://screenpipe.com/api/user/data-sync/mcp";
+    expect(parse(cloud, "mcp.json").mcpServers).toEqual({ "screenpipe-cloud": { type: "streamable-http", url: endpoint } });
+    expect(parse(cloud, ".mcp.json").mcpServers).toEqual({ "screenpipe-cloud": { type: "http", url: endpoint } });
+    expect(codex.mcpServers).toBe("./.mcp.json");
+    expect(codex.interface.capabilities).toEqual(["Read"]);
+    expect(cloud[codex.interface.logo.replace(/^\.\//, "")]).toBeDefined();
+  });
+});

package/src/qualified-value.test.ts

@@ -55,6 +55,7 @@ describe("createMcpQualifiedValueReporter", () => {
     ["chatgpt", "ChatGPT", "chatgpt"],
     ["gemini", "gemini-cli", "gemini"],
     ["runner", "Runner", "runner"],
+    ["vscode", "vscode", "vscode"],
     ["grokbot", "Grok Bot", "grokbot"],
   ])("recognizes configured %s and its handshake name", (configured, protocol, expected) => {
     expect(resolveMcpClient(configured, "unrecognized-client")).toBe(expected);

package/src/qualified-value.ts

@@ -4,7 +4,7 @@
 
 const CLIENTS = [
   "claude", "chatgpt", "codex", "cursor", "gemini", "openclaw",
-  "hermes", "runner", "windsurf", "grok", "grokbot",
+  "hermes", "runner", "windsurf", "vscode", "grok", "grokbot",
 ] as const;
 export type McpClient = (typeof CLIENTS)[number] | "unknown";
 

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);
+});