clickshot-mcp 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# clickshot-mcp
+
+Local MCP server for the **ClickShot** Chrome extension. It lets the Claude you're
+already running (Claude Code / Claude Desktop) see your recent browser activity —
+on your own subscription, with **no API key and no billing**. Everything stays on
+your machine.
+
+```
+ClickShot extension ──POST screenshot──> clickshot-mcp ──MCP──> your Claude
+```
+
+## Run
+
+```bash
+npx clickshot-mcp            # HTTP mode on 127.0.0.1:7333
+```
+
+Options:
+
+```
+clickshot-mcp [--stdio] [--port <n>]
+  (default)   HTTP mode with an /mcp endpoint (for Claude Code)
+  --stdio     stdio MCP (for Claude Desktop); still opens the ingest port
+  --port <n>  ingest / MCP port (default 7333, or $CLICKSHOT_PORT)
+```
+
+## Connect Claude Code (HTTP)
+
+```bash
+npx clickshot-mcp                                                  # leave running
+claude mcp add --transport http clickshot http://127.0.0.1:7333/mcp
+```
+
+## Connect Claude Desktop (stdio)
+
+Add to `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "clickshot": { "command": "npx", "args": ["-y", "clickshot-mcp", "--stdio"] }
+  }
+}
+```
+
+Restart Claude Desktop. The server starts automatically and also opens the
+extension ingest port.
+
+## Tools
+
+- `get_recent_activity(limit)` — last N clicks as annotated screenshots + a log
+  (URL, page title, clicked element, text)
+- `clear_activity()` — wipe the buffer
+
+## Ingest API (used by the extension)
+
+- `POST /capture` — `{ image: base64, mimeType, meta }`
+- `GET /health` — `{ ok, captures, mode }`
+
+Buffers the most recent 200 captures in memory. Binds to `127.0.0.1` only.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "clickshot-mcp",
+  "version": "0.1.0",
+  "description": "Local MCP server that feeds ClickShot screenshots into your running Claude (Code/Desktop) on your own subscription.",
+  "type": "module",
+  "bin": {
+    "clickshot-mcp": "server.js"
+  },
+  "files": [
+    "server.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node server.js"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "screenshots",
+    "workflow",
+    "browser",
+    "clickshot"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.2",
+    "zod": "^3.24.1"
+  }
+}

package/server.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// ClickShot MCP server.
+//
+// Bridges the ClickShot browser extension to the user's own Claude. Everything
+// stays local — no API key, no billing. Two transport modes:
+//
+//   HTTP  (default)  — long-running server. Register in Claude Code:
+//                        claude mcp add --transport http clickshot http://127.0.0.1:7333/mcp
+//   stdio (--stdio)  — launched by Claude Desktop via its config. Also opens the
+//                        ingest port so the extension can still push screenshots.
+//
+// In both modes the extension POSTs screenshots to http://127.0.0.1:<port>/capture.
+
+import express from "express";
+import cors from "cors";
+import { z } from "zod";
+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";
+
+// stdout is the JSON-RPC channel in stdio mode, so all logging goes to stderr.
+const log = (...a) => console.error(...a);
+
+// ---- args ----
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  process.stdout.write(
+    `clickshot-mcp v${VERSION}\n\n` +
+      `Usage: clickshot-mcp [--stdio] [--port <n>]\n\n` +
+      `  (default)      HTTP mode on 127.0.0.1:<port> with an /mcp endpoint\n` +
+      `  --stdio        stdio MCP (for Claude Desktop); still opens the ingest port\n` +
+      `  --port <n>     port for the extension ingest / HTTP MCP (default 7333,\n` +
+      `                 or $CLICKSHOT_PORT)\n`
+  );
+  process.exit(0);
+}
+if (argv.includes("--version") || argv.includes("-v")) {
+  process.stdout.write(VERSION + "\n");
+  process.exit(0);
+}
+const portFlagIdx = argv.indexOf("--port");
+const PORT = Number(
+  (portFlagIdx !== -1 && argv[portFlagIdx + 1]) || process.env.CLICKSHOT_PORT || 7333
+);
+const STDIO = argv.includes("--stdio");
+
+const MAX_BUFFER = 200; // keep the most recent N captures in memory
+
+/** @type {Array<{id:number, image:string, mimeType:string, meta:object}>} */
+const captures = [];
+let nextId = 1;
+
+// ---------------------------------------------------------------------------
+// MCP server definition (tools)
+// ---------------------------------------------------------------------------
+function buildMcpServer() {
+  const server = new McpServer({ name: "clickshot", version: VERSION });
+
+  server.registerTool(
+    "get_recent_activity",
+    {
+      title: "Get recent browser activity",
+      description:
+        "Returns the user's most recent browser clicks as annotated screenshots " +
+        "plus a log of what was clicked (URL, page title, element, text). Use this " +
+        "to understand what the user has been doing in their browser.",
+      inputSchema: {
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(25)
+          .optional()
+          .describe("How many of the most recent clicks to return (default 10)."),
+      },
+    },
+    async ({ limit }) => {
+      const n = Math.min(limit || 10, 25);
+      const recent = captures.slice(-n);
+      if (recent.length === 0) {
+        return {
+          content: [
+            { type: "text", text: "No browser activity captured yet. The user may need to start recording in the ClickShot extension." },
+          ],
+        };
+      }
+
+      const content = [
+        {
+          type: "text",
+          text:
+            `Most recent ${recent.length} browser click(s), oldest first. ` +
+            `Each screenshot has a red marker at the click point.`,
+        },
+      ];
+
+      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}`,
+        });
+        content.push({ type: "image", data: c.image, mimeType: c.mimeType || "image/jpeg" });
+      }
+
+      return { content };
+    }
+  );
+
+  server.registerTool(
+    "clear_activity",
+    {
+      title: "Clear captured activity",
+      description: "Discards all buffered browser screenshots from the ClickShot server.",
+      inputSchema: {},
+    },
+    async () => {
+      const count = captures.length;
+      captures.length = 0;
+      return { content: [{ type: "text", text: `Cleared ${count} captured screenshot(s).` }] };
+    }
+  );
+
+  return server;
+}
+
+// ---------------------------------------------------------------------------
+// Ingest HTTP app (used in BOTH modes so the extension can push screenshots)
+// ---------------------------------------------------------------------------
+function buildIngestApp() {
+  const app = express();
+  app.use(cors()); // allow the extension (chrome-extension://) origin
+  app.use(express.json({ limit: "25mb" })); // screenshots are base64
+
+  app.post("/capture", (req, res) => {
+    const { image, mimeType, meta } = req.body || {};
+    if (!image) return res.status(400).json({ error: "missing image" });
+    captures.push({ id: nextId++, image, mimeType: mimeType || "image/jpeg", meta: meta || {} });
+    if (captures.length > MAX_BUFFER) captures.splice(0, captures.length - MAX_BUFFER);
+    res.json({ ok: true, buffered: captures.length });
+  });
+
+  app.get("/health", (_req, res) => res.json({ ok: true, captures: captures.length, mode: STDIO ? "stdio" : "http" }));
+  return app;
+}
+
+// ---------------------------------------------------------------------------
+// Boot
+// ---------------------------------------------------------------------------
+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)`);
+    });
+    const server = buildMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log("ClickShot MCP ready over stdio.");
+  } else {
+    // Long-running HTTP server with both ingest and an /mcp endpoint.
+    const app = buildIngestApp();
+
+    app.post("/mcp", async (req, res) => {
+      try {
+        const server = buildMcpServer();
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on("close", () => {
+          transport.close();
+          server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+      } catch (err) {
+        if (!res.headersSent) {
+          res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null });
+        }
+      }
+    });
+
+    const methodNotAllowed = (_req, res) =>
+      res.status(405).json({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed." }, id: null });
+    app.get("/mcp", methodNotAllowed);
+    app.delete("/mcp", methodNotAllowed);
+
+    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`);
+    });
+  }
+}
+
+main().catch((e) => {
+  log("Fatal:", e);
+  process.exit(1);
+});