@useclickly/mcp-server 1.0.0 → 1.0.2

package/dist/cli.cjs

@@ -1,17 +1,632 @@
-'use strict';
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 
 // src/cli.ts
-var [, , cmd] = process.argv;
+var import_node_fs2 = __toESM(require("node:fs"), 1);
+var import_node_net = __toESM(require("node:net"), 1);
+var import_node_os2 = __toESM(require("node:os"), 1);
+var import_node_path2 = __toESM(require("node:path"), 1);
+
+// src/server.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_zod = require("zod");
+
+// src/store.ts
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_os = __toESM(require("node:os"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+var AnnotationStore = class {
+  sessions = /* @__PURE__ */ new Map();
+  /** sessionId → (annotationId → AnnotationRecord) */
+  annotations = /* @__PURE__ */ new Map();
+  /** Listeners waiting for new annotations in a session (SSE bridge) */
+  listeners = /* @__PURE__ */ new Map();
+  storePath;
+  constructor(options = {}) {
+    this.storePath = options.storePath ?? import_node_path.default.join(import_node_os.default.homedir(), ".clickly", "sessions.json");
+    this._load();
+  }
+  /* ── Sessions ─────────────────────────────────────────────────────── */
+  createSession(url) {
+    const id = crypto.randomUUID();
+    const session = { id, url, createdAt: Date.now(), seq: 0 };
+    this.sessions.set(id, session);
+    this.annotations.set(id, /* @__PURE__ */ new Map());
+    this._persist();
+    return session;
+  }
+  getSession(sessionId) {
+    return this.sessions.get(sessionId);
+  }
+  listSessions() {
+    return [...this.sessions.values()].sort((a, b) => b.createdAt - a.createdAt);
+  }
+  /* ── Annotations ──────────────────────────────────────────────────── */
+  addAnnotation(sessionId, annotation) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error(`Session not found: ${sessionId}`);
+    const bucket = this.annotations.get(sessionId);
+    const record = { ...annotation, sessionId };
+    bucket.set(annotation.id, record);
+    session.seq += 1;
+    const seq = session.seq;
+    this._persist();
+    this._emit(sessionId, record, seq);
+    return record;
+  }
+  getAnnotation(sessionId, annotationId) {
+    return this.annotations.get(sessionId)?.get(annotationId);
+  }
+  listAnnotations(sessionId) {
+    const bucket = this.annotations.get(sessionId);
+    if (!bucket) return [];
+    return [...bucket.values()].sort((a, b) => a.timestamp - b.timestamp);
+  }
+  updateAnnotation(sessionId, annotationId, patch) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error(`Session not found: ${sessionId}`);
+    const bucket = this.annotations.get(sessionId);
+    const existing = bucket?.get(annotationId);
+    if (!existing) throw new Error(`Annotation not found: ${annotationId}`);
+    const updated = { ...existing, ...patch, sessionId };
+    bucket.set(annotationId, updated);
+    session.seq += 1;
+    const seq = session.seq;
+    this._persist();
+    this._emit(sessionId, updated, seq);
+    return updated;
+  }
+  /* ── SSE subscriptions ────────────────────────────────────────────── */
+  subscribe(sessionId, cb) {
+    if (!this.listeners.has(sessionId)) {
+      this.listeners.set(sessionId, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(sessionId).add(cb);
+    return () => this.listeners.get(sessionId)?.delete(cb);
+  }
+  _emit(sessionId, annotation, seq) {
+    this.listeners.get(sessionId)?.forEach((cb) => cb(annotation, seq));
+  }
+  /* ── Persistence ──────────────────────────────────────────────────── */
+  _persist() {
+    try {
+      const dir = import_node_path.default.dirname(this.storePath);
+      if (!import_node_fs.default.existsSync(dir)) import_node_fs.default.mkdirSync(dir, { recursive: true });
+      const data = {
+        sessions: [...this.sessions.values()],
+        annotations: [...this.annotations.values()].flatMap((m) => [...m.values()])
+      };
+      import_node_fs.default.writeFileSync(this.storePath, JSON.stringify(data, null, 2), "utf-8");
+    } catch {
+    }
+  }
+  _load() {
+    try {
+      if (!import_node_fs.default.existsSync(this.storePath)) return;
+      const raw = import_node_fs.default.readFileSync(this.storePath, "utf-8");
+      const data = JSON.parse(raw);
+      for (const session of data.sessions ?? []) {
+        this.sessions.set(session.id, session);
+        this.annotations.set(session.id, /* @__PURE__ */ new Map());
+      }
+      for (const annotation of data.annotations ?? []) {
+        this.annotations.get(annotation.sessionId)?.set(annotation.id, annotation);
+      }
+    } catch {
+    }
+  }
+};
+
+// src/http-bridge.ts
+var import_node_http = __toESM(require("node:http"), 1);
+var VERSION = "1.0.0";
+function cors(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+}
+function json(res, status, body) {
+  cors(res);
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(payload)
+  });
+  res.end(payload);
+}
+function notFound(res) {
+  json(res, 404, { error: "not_found" });
+}
+function badRequest(res, message) {
+  json(res, 400, { error: "bad_request", message });
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = "";
+    req.on("data", (chunk) => raw += chunk);
+    req.on("end", () => {
+      try {
+        resolve(raw ? JSON.parse(raw) : {});
+      } catch {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+function route(req) {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const segments = url.pathname.replace(/^\//, "").split("/").filter(Boolean);
+  return { method: req.method?.toUpperCase() ?? "GET", segments };
+}
+function createHttpBridge(store, port) {
+  const server = import_node_http.default.createServer(async (req, res) => {
+    if (req.method === "OPTIONS") {
+      cors(res);
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    const r = route(req);
+    if (!r) return notFound(res);
+    const { method, segments } = r;
+    try {
+      if (method === "GET" && segments[0] === "health") {
+        return json(res, 200, { ok: true, version: VERSION });
+      }
+      if (method === "GET" && segments.length === 1 && segments[0] === "sessions") {
+        return json(res, 200, store.listSessions());
+      }
+      if (method === "POST" && segments.length === 1 && segments[0] === "sessions") {
+        const body = await readBody(req);
+        if (!body.url) return badRequest(res, "url is required");
+        const session = store.createSession(body.url);
+        return json(res, 201, { sessionId: session.id });
+      }
+      if (segments[0] === "sessions" && segments[1]) {
+        const sessionId = segments[1];
+        const session = store.getSession(sessionId);
+        if (!session) return json(res, 404, { error: "session_not_found" });
+        const sub = segments[2];
+        if (method === "GET" && sub === "annotations" && segments.length === 3) {
+          return json(res, 200, store.listAnnotations(sessionId));
+        }
+        if (method === "POST" && sub === "annotations" && segments.length === 3) {
+          const body = await readBody(req);
+          if (!body || typeof body !== "object") return badRequest(res, "body required");
+          const annotation = body;
+          if (!annotation.id || !annotation.comment || !annotation.elementPath) {
+            return badRequest(res, "id, comment, elementPath are required");
+          }
+          const record = store.addAnnotation(sessionId, annotation);
+          return json(res, 201, { ok: true, id: record.id });
+        }
+        if (method === "GET" && sub === "events" && segments.length === 3) {
+          cors(res);
+          res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+            "X-Accel-Buffering": "no"
+            // disable nginx buffering
+          });
+          res.write(`event: connected
+data: ${JSON.stringify({ seq: session.seq })}
+
+`);
+          const unsubscribe = store.subscribe(sessionId, (annotation, seq) => {
+            const payload = JSON.stringify({ annotation, seq });
+            res.write(`event: annotation
+data: ${payload}
+
+`);
+          });
+          const heartbeat = setInterval(() => {
+            res.write(`: heartbeat
+
+`);
+          }, 15e3);
+          req.on("close", () => {
+            clearInterval(heartbeat);
+            unsubscribe();
+          });
+          return;
+        }
+      }
+      notFound(res);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "internal_error";
+      json(res, 500, { error: "internal_error", message });
+    }
+  });
+  server.listen(port);
+  return {
+    port,
+    close: () => new Promise(
+      (resolve, reject) => server.close((err) => err ? reject(err) : resolve())
+    )
+  };
+}
+
+// src/server.ts
+var SessionIdSchema = {
+  sessionId: import_zod.z.string().describe("Session ID returned by the browser bridge")
+};
+var AnnotationIdSchema = {
+  ...SessionIdSchema,
+  annotationId: import_zod.z.string().describe("Annotation ID")
+};
+function errResult(message) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }]
+  };
+}
+function okResult(data) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof data === "string" ? data : JSON.stringify(data, null, 2)
+      }
+    ]
+  };
+}
+async function createServer(options = {}) {
+  const port = options.port ?? 4747;
+  const store = options.store ?? new AnnotationStore({ storePath: options.storePath });
+  const bridge = createHttpBridge(store, port);
+  const mcp = new import_mcp.McpServer(
+    { name: "clickly", version: "1.0.0" },
+    {
+      capabilities: { tools: {} },
+      instructions: "Clickly exposes UI annotations captured in a running React development app. Use these tools to read feedback, acknowledge issues, resolve them, or reply to start a conversation thread with the developer."
+    }
+  );
+  mcp.registerTool(
+    "clickly_list_sessions",
+    {
+      description: "List all Clickly annotation sessions. Each session corresponds to a page/URL where the developer opened the Clickly toolbar. Returns session IDs, URLs, creation timestamps, and annotation counts.",
+      inputSchema: {}
+    },
+    async () => {
+      const sessions = store.listSessions();
+      const rows = sessions.map((s) => ({
+        sessionId: s.id,
+        url: s.url,
+        createdAt: new Date(s.createdAt).toISOString(),
+        annotationCount: store.listAnnotations(s.id).length
+      }));
+      return okResult(rows);
+    }
+  );
+  mcp.registerTool(
+    "clickly_list_annotations",
+    {
+      description: "List all annotations in a session. Includes element path, position, React component tree, source file/line, feedback comment, and lifecycle status.",
+      inputSchema: SessionIdSchema
+    },
+    async ({ sessionId }) => {
+      const session = store.getSession(sessionId);
+      if (!session) return errResult(`Session not found: ${sessionId}`);
+      return okResult(store.listAnnotations(sessionId));
+    }
+  );
+  mcp.registerTool(
+    "clickly_get_annotation",
+    {
+      description: "Fetch a single annotation by ID. Returns the full AFS 1.1 record including element metadata, bounding box, React component chain, source location, and any thread messages.",
+      inputSchema: AnnotationIdSchema
+    },
+    async ({ sessionId, annotationId }) => {
+      const annotation = store.getAnnotation(sessionId, annotationId);
+      if (!annotation) {
+        return errResult(
+          `Annotation not found: ${annotationId} in session ${sessionId}`
+        );
+      }
+      return okResult(annotation);
+    }
+  );
+  mcp.registerTool(
+    "clickly_acknowledge",
+    {
+      description: "Mark an annotation as 'acknowledged' \u2014 you have seen it and are working on it. The developer's UI will show an acknowledged badge on the annotation pin.",
+      inputSchema: AnnotationIdSchema
+    },
+    async ({ sessionId, annotationId }) => {
+      try {
+        const updated = store.updateAnnotation(sessionId, annotationId, {
+          status: "acknowledged"
+        });
+        return okResult(
+          `Acknowledged annotation ${updated.id} in session ${sessionId}.`
+        );
+      } catch (err) {
+        return errResult(err instanceof Error ? err.message : String(err));
+      }
+    }
+  );
+  mcp.registerTool(
+    "clickly_resolve",
+    {
+      description: "Mark an annotation as 'resolved' \u2014 the issue has been fixed. Optionally include a resolution note. The pin will show as resolved in the developer's browser.",
+      inputSchema: {
+        ...AnnotationIdSchema,
+        note: import_zod.z.string().optional().describe("Optional resolution note to append to the thread")
+      }
+    },
+    async ({ sessionId, annotationId, note }) => {
+      try {
+        const existing = store.getAnnotation(sessionId, annotationId);
+        if (!existing) return errResult(`Annotation not found: ${annotationId}`);
+        const thread = existing.thread ? [...existing.thread] : [];
+        if (note) {
+          thread.push({
+            id: crypto.randomUUID(),
+            role: "agent",
+            content: note,
+            timestamp: Date.now()
+          });
+        }
+        const updated = store.updateAnnotation(sessionId, annotationId, {
+          status: "resolved",
+          resolvedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          resolvedBy: "agent",
+          ...note ? { thread } : {}
+        });
+        return okResult(
+          `Resolved annotation ${updated.id}.${note ? ` Note: "${note}"` : ""}`
+        );
+      } catch (err) {
+        return errResult(err instanceof Error ? err.message : String(err));
+      }
+    }
+  );
+  mcp.registerTool(
+    "clickly_dismiss",
+    {
+      description: "Mark an annotation as 'dismissed' \u2014 it is not actionable or is a duplicate. Dismissed annotations are hidden from the default list view.",
+      inputSchema: AnnotationIdSchema
+    },
+    async ({ sessionId, annotationId }) => {
+      try {
+        const updated = store.updateAnnotation(sessionId, annotationId, {
+          status: "dismissed"
+        });
+        return okResult(`Dismissed annotation ${updated.id}.`);
+      } catch (err) {
+        return errResult(err instanceof Error ? err.message : String(err));
+      }
+    }
+  );
+  mcp.registerTool(
+    "clickly_reply",
+    {
+      description: "Append a thread message to an annotation. Use this to ask a clarifying question, describe what you changed, or communicate back to the developer who left feedback.",
+      inputSchema: {
+        ...AnnotationIdSchema,
+        message: import_zod.z.string().describe("Your reply message")
+      }
+    },
+    async ({ sessionId, annotationId, message }) => {
+      try {
+        const existing = store.getAnnotation(sessionId, annotationId);
+        if (!existing) return errResult(`Annotation not found: ${annotationId}`);
+        const thread = [
+          ...existing.thread ?? [],
+          {
+            id: crypto.randomUUID(),
+            role: "agent",
+            content: message,
+            timestamp: Date.now()
+          }
+        ];
+        store.updateAnnotation(sessionId, annotationId, { thread });
+        return okResult(`Reply added to annotation ${annotationId}.`);
+      } catch (err) {
+        return errResult(err instanceof Error ? err.message : String(err));
+      }
+    }
+  );
+  const transport = new import_stdio.StdioServerTransport();
+  await mcp.connect(transport);
+  return {
+    port,
+    close: async () => {
+      await mcp.close();
+      await bridge.close();
+    }
+  };
+}
+
+// src/cli.ts
+var import_meta = {};
+var [, , cmd, ...args] = process.argv;
+function log(msg) {
+  process.stderr.write(msg + "\n");
+}
+function out(msg) {
+  process.stdout.write(msg + "\n");
+}
+function parseFlag(flag, fallback) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && args[idx + 1] != null ? args[idx + 1] : fallback;
+}
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const srv = import_node_net.default.createServer();
+    srv.once("error", () => resolve(false));
+    srv.once("listening", () => srv.close(() => resolve(true)));
+    srv.listen(port, "127.0.0.1");
+  });
+}
+async function cmdServer() {
+  const port = parseInt(parseFlag("--port", "4747"), 10);
+  const storePath = parseFlag("--store", import_node_path2.default.join(import_node_os2.default.homedir(), ".clickly", "sessions.json"));
+  log(`[clickly-mcp] Starting MCP server (stdio) + HTTP bridge on :${port}`);
+  log(`[clickly-mcp] Persistence: ${storePath}`);
+  log(`[clickly-mcp] Ready. Connect your AI agent via stdio.`);
+  const handle = await createServer({ port, storePath });
+  process.on("SIGINT", async () => {
+    log("\n[clickly-mcp] Shutting down\u2026");
+    await handle.close();
+    process.exit(0);
+  });
+  process.on("SIGTERM", async () => {
+    await handle.close();
+    process.exit(0);
+  });
+}
+async function cmdDoctor() {
+  let allOk = true;
+  const port = parseInt(parseFlag("--port", "4747"), 10);
+  const storePath = import_node_path2.default.join(import_node_os2.default.homedir(), ".clickly", "sessions.json");
+  out("clickly-mcp doctor\n");
+  const nodeVersion = process.versions.node;
+  const major = parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+  const nodeOk = major >= 18;
+  out(`  Node.js: ${nodeVersion} ${nodeOk ? "\u2713" : "\u2717 (need \u2265 18)"}`);
+  if (!nodeOk) allOk = false;
+  const portFree = await isPortFree(port);
+  out(`  Port ${port}: ${portFree ? "available \u2713" : "IN USE \u2717 (another process is running on this port)"}`);
+  if (!portFree) allOk = false;
+  const storeDir = import_node_path2.default.dirname(storePath);
+  let storeOk = false;
+  try {
+    import_node_fs2.default.mkdirSync(storeDir, { recursive: true });
+    const testFile = import_node_path2.default.join(storeDir, ".write-test");
+    import_node_fs2.default.writeFileSync(testFile, "ok");
+    import_node_fs2.default.unlinkSync(testFile);
+    storeOk = true;
+  } catch {
+    storeOk = false;
+  }
+  out(`  Store dir (${storeDir}): ${storeOk ? "writable \u2713" : "NOT writable \u2717"}`);
+  if (!storeOk) allOk = false;
+  if (import_node_fs2.default.existsSync(storePath)) {
+    try {
+      const data = JSON.parse(import_node_fs2.default.readFileSync(storePath, "utf-8"));
+      const count = (data.sessions ?? []).length;
+      out(`  Persisted sessions: ${count}`);
+    } catch {
+      out(`  Persisted sessions: (could not parse ${storePath})`);
+    }
+  } else {
+    out(`  Persisted sessions: none yet (store will be created on first use)`);
+  }
+  out(`
+  ${allOk ? "All checks passed \u2713" : "Some checks failed \u2717 \u2014 fix the issues above before starting"}`);
+  process.exit(allOk ? 0 : 1);
+}
+function cmdInit() {
+  const write = args.includes("--write");
+  const binPath = process.execPath;
+  const mcpBin = new URL("../dist/cli.js", import_meta.url).pathname;
+  const claudeSnippet = JSON.stringify(
+    {
+      mcpServers: {
+        clickly: {
+          command: "node",
+          args: [mcpBin, "server"],
+          env: {}
+        }
+      }
+    },
+    null,
+    2
+  );
+  const cursorSnippet = JSON.stringify(
+    {
+      mcpServers: {
+        clickly: {
+          command: "node",
+          args: [mcpBin, "server"]
+        }
+      }
+    },
+    null,
+    2
+  );
+  if (!write) {
+    out("# Clickly MCP \u2014 setup snippets\n");
+    out("## Claude Code  (~/.claude.json  or  claude_desktop_config.json)\n");
+    out(claudeSnippet);
+    out("\n## Cursor  (.cursor/mcp.json)\n");
+    out(cursorSnippet);
+    out(
+      "\nRun `clickly-mcp init --write` to automatically write the Claude Code config.\n"
+    );
+    out(`(node binary: ${binPath})`);
+    return;
+  }
+  const claudeConfigDir = import_node_path2.default.join(import_node_os2.default.homedir(), ".claude");
+  const claudeConfigPath = import_node_path2.default.join(claudeConfigDir, "claude_desktop_config.json");
+  try {
+    import_node_fs2.default.mkdirSync(claudeConfigDir, { recursive: true });
+    let existing = {};
+    if (import_node_fs2.default.existsSync(claudeConfigPath)) {
+      existing = JSON.parse(import_node_fs2.default.readFileSync(claudeConfigPath, "utf-8"));
+    }
+    const mcpServers = existing.mcpServers ?? {};
+    mcpServers.clickly = { command: "node", args: [mcpBin, "server"], env: {} };
+    existing.mcpServers = mcpServers;
+    import_node_fs2.default.writeFileSync(claudeConfigPath, JSON.stringify(existing, null, 2), "utf-8");
+    out(`\u2713 Written to ${claudeConfigPath}`);
+    out("  Restart Claude Code (or your agent) to pick up the new MCP server.");
+  } catch (err) {
+    out(`\u2717 Could not write config: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+}
 switch (cmd) {
   case "server":
+    cmdServer().catch((err) => {
+      log(`[clickly-mcp] Fatal: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    });
+    break;
   case "doctor":
+    cmdDoctor().catch((err) => {
+      log(`doctor error: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    });
+    break;
   case "init":
-    console.error(`clickly-mcp: "${cmd}" not yet implemented (Phase 2 scaffold)`);
-    process.exit(2);
+    cmdInit();
     break;
   default:
-    console.log("usage: clickly-mcp <server|doctor|init>");
+    out("clickly-mcp \u2014 MCP server for the Clickly annotation toolbar\n");
+    out("Usage: clickly-mcp <command> [options]\n");
+    out("Commands:");
+    out("  server   Start the MCP stdio server (+ HTTP bridge on :4747)");
+    out("           Options: --port <n>   HTTP bridge port (default: 4747)");
+    out("                    --store <path>  Persistence file (default: ~/.clickly/sessions.json)");
+    out("  doctor   Check environment (Node version, port, store writability)");
+    out("  init     Print config snippets for Claude Code / Cursor");
+    out("           Options: --write   Write directly to ~/.claude/claude_desktop_config.json");
     process.exit(cmd ? 1 : 0);
 }
 //# sourceMappingURL=cli.cjs.map
-//# sourceMappingURL=cli.cjs.map