clickshot-mcp 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clickshot-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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.0";
+const VERSION = "0.1.2";
+
+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,18 @@ const MAX_BUFFER = 200; // keep the most recent N captures in memory
 const captures = [];
 let nextId = 1;
 
+// Claude-initiated "watch" session state. The extension polls GET /watch 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 };
+
+function setWatch(on, task) {
+  watch.on = !!on;
+  watch.task = on ? task || null : null;
+  watch.since = on ? Date.now() : null;
+}
+
 // ---------------------------------------------------------------------------
 // MCP server definition (tools)
 // ---------------------------------------------------------------------------
@@ -91,22 +105,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 +132,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,20 +215,51 @@ 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 });
+  });
+
   return app;
 }
 
 // ---------------------------------------------------------------------------
 // Boot
 // ---------------------------------------------------------------------------
+// Bind the ingest port without letting a conflict crash the process.
+function listenIngest(app, { fatalOnError }) {
+  const srv = app.listen(PORT, "127.0.0.1", () => {
+    log(`ClickShot ingest on http://127.0.0.1:${PORT}/capture`);
+  });
+  srv.on("error", (err) => {
+    if (err && err.code === "EADDRINUSE") {
+      if (fatalOnError) {
+        log(`Port ${PORT} is already in use — another ClickShot server is running. Stop it, or set CLICKSHOT_PORT to a free port.`);
+        process.exit(1);
+      }
+      log(`Port ${PORT} already in use — another ClickShot server is handling ingest. Continuing with MCP over stdio.`);
+    } else {
+      log("Ingest server error:", err && err.message ? err.message : err);
+      if (fatalOnError) process.exit(1);
+    }
+  });
+  return srv;
+}
+
 async function main() {
   if (STDIO) {
     // Claude Desktop launches this; talk MCP over stdio, ingest over HTTP.
-    const app = buildIngestApp();
-    app.listen(PORT, "127.0.0.1", () => {
-      log(`ClickShot ingest on http://127.0.0.1:${PORT}/capture (stdio MCP mode)`);
-    });
+    // A port conflict must NOT kill the MCP connection.
+    listenIngest(buildIngestApp(), { fatalOnError: false });
     const server = buildMcpServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
@@ -191,13 +290,21 @@ async function main() {
     app.get("/mcp", methodNotAllowed);
     app.delete("/mcp", methodNotAllowed);
 
-    app.listen(PORT, "127.0.0.1", () => {
+    const srv = app.listen(PORT, "127.0.0.1", () => {
       log(`ClickShot MCP server on http://127.0.0.1:${PORT}`);
       log(`  • extension ingest: POST http://127.0.0.1:${PORT}/capture`);
       log(`  • MCP endpoint:     http://127.0.0.1:${PORT}/mcp`);
       log(`Register in Claude Code:`);
       log(`  claude mcp add --transport http clickshot http://127.0.0.1:${PORT}/mcp`);
     });
+    srv.on("error", (err) => {
+      if (err && err.code === "EADDRINUSE") {
+        log(`Port ${PORT} is already in use — another ClickShot server is running. Stop it, or set CLICKSHOT_PORT to a free port.`);
+      } else {
+        log("Server error:", err && err.message ? err.message : err);
+      }
+      process.exit(1);
+    });
   }
 }