clickshot-mcp 0.1.1 → 0.1.3

package/README.md

@@ -49,8 +49,12 @@ extension ingest port.
 
 ## Tools
 
-- `get_recent_activity(limit)` — last N clicks as annotated screenshots + a log
-  (URL, page title, clicked element, text)
+- `get_recent_activity(limit)` — last N frames as screenshots + a log (URL, page
+  title, clicked element/text; periodic frames are labeled)
+- `start_watching(task)` — Claude asks to watch the user perform a task. Turns on
+  recording + periodic frames in the extension (with a visible "Claude is watching"
+  indicator). The MCP client prompts the user to approve this.
+- `stop_watching()` — end the watch session
 - `clear_activity()` — wipe the buffer
 
 ## Ingest API (used by the extension)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clickshot-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local MCP server that feeds ClickShot screenshots into your running Claude (Code/Desktop) on your own subscription.",
   "type": "module",
   "bin": {

package/server.js

@@ -18,7 +18,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-const VERSION = "0.1.1";
+const VERSION = "0.1.3";
+
+const WATCH_INTERVAL_MS = 4000; // periodic-frame cadence the extension uses while watching
 
 // stdout is the JSON-RPC channel in stdio mode, so all logging goes to stderr.
 const log = (...a) => console.error(...a);
@@ -52,6 +54,49 @@ const MAX_BUFFER = 200; // keep the most recent N captures in memory
 const captures = [];
 let nextId = 1;
 
+// Claude-initiated "watch" session state. The extension holds an SSE stream
+// (GET /events) and starts recording (+ periodic frames) when `on` is true.
+// Turned on by the start_watching tool (which the MCP client gates with a user
+// approval prompt) and off by stop_watching or by the user via the extension.
+const watch = { on: false, task: null, since: null };
+
+// SSE clients (the extension's background worker). The stream keeps the MV3
+// service worker alive and lets the server push state changes + frame ticks.
+const sseClients = new Set();
+
+function sseSend(res, event, data) {
+  try {
+    res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+  } catch (e) {
+    /* client gone; cleaned up on 'close' */
+  }
+}
+
+function broadcast(event, data) {
+  for (const res of sseClients) sseSend(res, event, data);
+}
+
+function watchState() {
+  return { watching: watch.on, task: watch.task, since: watch.since, intervalMs: WATCH_INTERVAL_MS };
+}
+
+function setWatch(on, task) {
+  watch.on = !!on;
+  watch.task = on ? task || null : null;
+  watch.since = on ? Date.now() : null;
+  broadcast("state", watchState()); // push the change to the extension immediately
+}
+
+// One process-wide ticker drives the push channel:
+//   • every second: while watching, emit a frame tick on the 4s cadence
+//   • every ~12s: emit a state heartbeat so the worker stays alive even when idle
+let tick = 0;
+setInterval(() => {
+  tick++;
+  if (watch.on && tick % Math.round(WATCH_INTERVAL_MS / 1000) === 0) broadcast("frame", { t: tick });
+  if (tick % 12 === 0) broadcast("state", watchState());
+}, 1000);
+
 // ---------------------------------------------------------------------------
 // MCP server definition (tools)
 // ---------------------------------------------------------------------------
@@ -91,22 +136,26 @@ function buildMcpServer() {
         {
           type: "text",
           text:
-            `Most recent ${recent.length} browser click(s), oldest first. ` +
-            `Each screenshot has a red marker at the click point.`,
+            `Most recent ${recent.length} browser frame(s), oldest first. ` +
+            `Click frames have a red marker at the click point; periodic frames ` +
+            `(captured while watching) do not.`,
         },
       ];
 
       for (const c of recent) {
         const m = c.meta || {};
         const when = m.timestamp ? new Date(m.timestamp).toISOString() : "unknown time";
-        const what =
-          (m.tag ? `<${m.tag}>` : "element") +
-          (m.text ? ` "${m.text}"` : "") +
-          (m.selector ? ` [${m.selector}]` : "");
-        content.push({
-          type: "text",
-          text: `#${c.id} ${when} — ${m.title || ""}\n  ${m.url || ""}\n  clicked ${what}`,
-        });
+        let line;
+        if (m.kind === "interval") {
+          line = `#${c.id} ${when} — ${m.title || ""}\n  ${m.url || ""}\n  (periodic frame)`;
+        } else {
+          const what =
+            (m.tag ? `<${m.tag}>` : "element") +
+            (m.text ? ` "${m.text}"` : "") +
+            (m.selector ? ` [${m.selector}]` : "");
+          line = `#${c.id} ${when} — ${m.title || ""}\n  ${m.url || ""}\n  clicked ${what}`;
+        }
+        content.push({ type: "text", text: line });
         content.push({ type: "image", data: c.image, mimeType: c.mimeType || "image/jpeg" });
       }
 
@@ -114,6 +163,56 @@ function buildMcpServer() {
     }
   );
 
+  server.registerTool(
+    "start_watching",
+    {
+      title: "Watch the user perform a task",
+      description:
+        "Begin observing the user's browser so you can see how they perform a task you've proposed. " +
+        "Use this AFTER suggesting a concrete task and getting the user's go-ahead: it turns on " +
+        "recording in their ClickShot extension (with a visible on-screen 'Claude is watching' " +
+        "indicator) and captures their clicks plus periodic screenshots. When the user says they're " +
+        "done, call get_recent_activity to review how they did it, then stop_watching. " +
+        "The user is shown an approval prompt for this action and can stop watching at any time.",
+      inputSchema: {
+        task: z.string().describe("The task you are about to watch the user perform, e.g. 'file an expense report'."),
+      },
+    },
+    async ({ task }) => {
+      setWatch(true, task);
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `Now watching for: "${task}".\n` +
+              `The ClickShot extension will start recording within a couple of seconds and show a ` +
+              `"Claude is watching" indicator. Ask the user to perform the task now. When they say ` +
+              `they're done, call get_recent_activity to review the steps, then stop_watching.`,
+          },
+        ],
+      };
+    }
+  );
+
+  server.registerTool(
+    "stop_watching",
+    {
+      title: "Stop watching",
+      description: "End the current watch session. The extension stops recording and hides the watching indicator.",
+      inputSchema: {},
+    },
+    async () => {
+      const was = watch.task;
+      setWatch(false);
+      return {
+        content: [
+          { type: "text", text: was ? `Stopped watching "${was}".` : "Watching was not active." },
+        ],
+      };
+    }
+  );
+
   server.registerTool(
     "clear_activity",
     {
@@ -147,7 +246,35 @@ function buildIngestApp() {
     res.json({ ok: true, buffered: captures.length });
   });
 
-  app.get("/health", (_req, res) => res.json({ ok: true, captures: captures.length, mode: STDIO ? "stdio" : "http" }));
+  app.get("/health", (_req, res) => res.json({ ok: true, captures: captures.length, mode: STDIO ? "stdio" : "http", watching: watch.on }));
+
+  // The extension polls this to know whether Claude has asked to watch.
+  app.get("/watch", (_req, res) =>
+    res.json({ watching: watch.on, task: watch.task, since: watch.since, intervalMs: WATCH_INTERVAL_MS })
+  );
+
+  // Lets the extension (the user's Stop button) revoke a watch session.
+  app.post("/watch", (req, res) => {
+    const on = !!(req.body && req.body.watching);
+    setWatch(on, req.body && req.body.task);
+    res.json({ ok: true, watching: watch.on });
+  });
+
+  // SSE push channel. The extension holds this open; it keeps the MV3 service
+  // worker alive and receives `state` (watch on/off) and `frame` (capture now)
+  // events. Replaces the old setInterval polling, which died when the worker slept.
+  app.get("/events", (req, res) => {
+    res.set({
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+    });
+    res.flushHeaders?.();
+    sseClients.add(res);
+    sseSend(res, "state", watchState()); // sync current state on connect
+    req.on("close", () => sseClients.delete(res));
+  });
+
   return app;
 }