@loupekit/mcp 0.10.16 → 0.10.17

package/dist/index.js

@@ -7,7 +7,419 @@ import { pathToFileURL } from "url";
 import { realpathSync } from "fs";
 import { argv } from "process";
 import { z } from "zod";
-import { Buffer } from "buffer";
+import { Buffer as Buffer2 } from "buffer";
+
+// src/bridge/selection-store.ts
+var isNonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+var isStringMap = (v) => !!v && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
+var isBox = (v) => {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+  const b = v;
+  return ["x", "y", "w", "h"].every((k) => typeof b[k] === "number" && Number.isFinite(b[k]));
+};
+function validateSelection(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return { ok: false, error: "body must be a JSON object" };
+  }
+  const p = input;
+  for (const key of ["correlationId", "url", "tag"]) {
+    if (!isNonEmptyString(p[key])) return { ok: false, error: `${key} is required` };
+  }
+  for (const key of ["selector", "text", "at"]) {
+    if (p[key] !== void 0 && typeof p[key] !== "string") return { ok: false, error: `${key} must be a string` };
+  }
+  for (const key of ["testid", "id"]) {
+    if (p[key] !== void 0 && p[key] !== null && typeof p[key] !== "string") {
+      return { ok: false, error: `${key} must be a string or null` };
+    }
+  }
+  if (p.attrs !== void 0 && !isStringMap(p.attrs)) return { ok: false, error: "attrs must be a string map" };
+  if (p.styles !== void 0 && !isStringMap(p.styles)) return { ok: false, error: "styles must be a string map" };
+  if (p.box !== void 0 && !isBox(p.box)) return { ok: false, error: "box must be { x, y, w, h }" };
+  if (p.screenshot !== void 0 && typeof p.screenshot !== "string") {
+    return { ok: false, error: "screenshot must be a string" };
+  }
+  if (p.classes !== void 0 && (!Array.isArray(p.classes) || !p.classes.every((c) => typeof c === "string"))) {
+    return { ok: false, error: "classes must be a string array" };
+  }
+  return {
+    ok: true,
+    value: {
+      correlationId: p.correlationId,
+      url: p.url,
+      tag: p.tag,
+      selector: p.selector,
+      testid: p.testid ?? null,
+      text: p.text,
+      id: p.id ?? null,
+      classes: p.classes,
+      attrs: p.attrs,
+      styles: p.styles,
+      box: p.box,
+      screenshot: p.screenshot,
+      at: p.at
+    }
+  };
+}
+var SelectionStore = class {
+  items = [];
+  capacity;
+  // Declared and assigned explicitly rather than as a constructor parameter
+  // property: Node runs these files with type-stripping only, and
+  // `constructor(private x)` is not supported in strip-only mode.
+  constructor(capacity = 50) {
+    if (!Number.isInteger(capacity) || capacity < 1) throw new Error("capacity must be a positive integer");
+    this.capacity = capacity;
+  }
+  /** Add a selection, evicting the oldest once the ring is full. Newest last. */
+  add(selection) {
+    const stored = { ...selection, at: selection.at ?? (/* @__PURE__ */ new Date()).toISOString() };
+    this.items.push(stored);
+    if (this.items.length > this.capacity) this.items.splice(0, this.items.length - this.capacity);
+    return stored;
+  }
+  latest() {
+    return this.items.length ? this.items[this.items.length - 1] : null;
+  }
+  /** Newest first — the order a caller wants them in. */
+  history(limit = this.capacity) {
+    const n = Math.max(0, Math.min(limit, this.items.length));
+    return this.items.slice(-n).reverse();
+  }
+  get(correlationId) {
+    return this.items.find((s) => s.correlationId === correlationId) ?? null;
+  }
+  size() {
+    return this.items.length;
+  }
+  clear() {
+    this.items = [];
+  }
+};
+
+// src/bridge/agent-registry.ts
+var AGENT_STALE_MS = 3e4;
+var AGENT_SWEEP_MS = 1e4;
+function agentId(reg) {
+  const input = `${reg.type}\0${reg.workspace}\0${reg.name}`;
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return `ag_${h.toString(16).padStart(8, "0")}`;
+}
+var AgentRegistry = class {
+  agents = /* @__PURE__ */ new Map();
+  staleMs;
+  now;
+  // Explicit fields, not constructor parameter properties — Node's strip-only
+  // TypeScript mode rejects those, and these files run unbundled from source.
+  constructor(staleMs = AGENT_STALE_MS, now = Date.now) {
+    if (!Number.isFinite(staleMs) || staleMs <= 0) throw new Error("staleMs must be positive");
+    this.staleMs = staleMs;
+    this.now = now;
+  }
+  /** Register or refresh. Re-registering the same identity is a heartbeat. */
+  register(reg) {
+    const id = agentId(reg);
+    const info = { ...reg, id, lastSeen: this.now() };
+    this.agents.set(id, info);
+    return info;
+  }
+  /** Refresh an existing agent. Unknown ids are ignored — the next register revives it. */
+  heartbeat(id) {
+    const existing = this.agents.get(id);
+    if (!existing) return null;
+    const info = { ...existing, lastSeen: this.now() };
+    this.agents.set(id, info);
+    return info;
+  }
+  /** Live agents only, oldest registration order. */
+  list() {
+    return [...this.agents.values()];
+  }
+  unregister(id) {
+    return this.agents.delete(id);
+  }
+  /**
+   * Drop anything silent for the TTL. Returns what was evicted.
+   *
+   * Inclusive at the boundary: "30s of silence" means an agent that last spoke
+   * exactly 30s ago is gone, which is what anyone reading the constant expects.
+   */
+  sweep() {
+    const now = this.now();
+    const gone = [];
+    for (const [id, info] of this.agents) {
+      if (now - info.lastSeen >= this.staleMs) {
+        this.agents.delete(id);
+        gone.push(info);
+      }
+    }
+    return gone;
+  }
+  size() {
+    return this.agents.size;
+  }
+};
+
+// src/bridge/events.ts
+var EventBus = class {
+  subscribers = /* @__PURE__ */ new Set();
+  /** Returns an unsubscribe function; calling it twice is safe. */
+  subscribe(fn) {
+    this.subscribers.add(fn);
+    return () => {
+      this.subscribers.delete(fn);
+    };
+  }
+  count() {
+    return this.subscribers.size;
+  }
+  /**
+   * Broadcast to everyone. A subscriber that throws is dropped rather than allowed
+   * to break the loop — a dead SSE connection would otherwise silence every other
+   * client behind it.
+   */
+  publish(event) {
+    for (const fn of [...this.subscribers]) {
+      try {
+        fn(event);
+      } catch {
+        this.subscribers.delete(fn);
+      }
+    }
+  }
+  /** Publish a thread update. The seam the MCP tools use. */
+  publishThread(threadId, eventType, data) {
+    this.publish({ type: "thread", threadId, eventType, data, at: (/* @__PURE__ */ new Date()).toISOString() });
+  }
+  clear() {
+    this.subscribers.clear();
+  }
+};
+
+// src/bridge/http-bridge.ts
+import { createServer } from "http";
+var MAX_BODY_BYTES = 1024 * 1024;
+var SSE_KEEPALIVE_MS = 15e3;
+async function startHttpBridge(port, deps, opts = {}) {
+  const retries = opts.retries ?? 5;
+  const retryDelayMs = opts.retryDelayMs ?? 1500;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const server2 = createServer((req, res) => {
+      void handle(req, res, deps);
+    });
+    try {
+      await listen(server2, port);
+      const bound = server2.address()?.port ?? port;
+      return {
+        port: bound,
+        url: `http://127.0.0.1:${bound}`,
+        close: () => close(server2)
+      };
+    } catch (e) {
+      const code = e?.code;
+      if (code !== "EADDRINUSE" || attempt === retries) {
+        if (code === "EADDRINUSE") {
+          console.error(`[loupe] bridge port ${port} is busy after ${retries + 1} attempts \u2014 continuing without it`);
+          return null;
+        }
+        throw e;
+      }
+      await delay(retryDelayMs);
+    }
+  }
+  return null;
+}
+function listen(server2, port) {
+  return new Promise((resolve, reject) => {
+    const onError = (e) => {
+      server2.removeListener("listening", onListening);
+      reject(e);
+    };
+    const onListening = () => {
+      server2.removeListener("error", onError);
+      resolve();
+    };
+    server2.once("error", onError);
+    server2.once("listening", onListening);
+    server2.listen(port, "127.0.0.1");
+  });
+}
+function close(server2) {
+  return new Promise((resolve) => {
+    server2.close(() => resolve());
+    server2.closeAllConnections?.();
+  });
+}
+var delay = (ms) => new Promise((r) => setTimeout(r, ms));
+function allowedOrigin(origin) {
+  if (!origin) return null;
+  if (origin.startsWith("chrome-extension://")) return origin;
+  try {
+    const u = new URL(origin);
+    if (u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]") return origin;
+  } catch {
+    return null;
+  }
+  return null;
+}
+function cors(res, origin) {
+  const allowed = allowedOrigin(origin);
+  if (allowed) {
+    res.setHeader("Access-Control-Allow-Origin", allowed);
+    res.setHeader("Vary", "Origin");
+  }
+}
+function send(res, status, body, origin) {
+  cors(res, origin);
+  const text = JSON.stringify(body);
+  res.writeHead(status, { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(text) });
+  res.end(text);
+}
+function readBody(req) {
+  return new Promise((resolve) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        resolve({ ok: false, error: `body exceeds ${MAX_BODY_BYTES} bytes` });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve({ ok: true, text: Buffer.concat(chunks).toString("utf8") }));
+    req.on("error", () => resolve({ ok: false, error: "could not read the request body" }));
+  });
+}
+async function handle(req, res, deps) {
+  const origin = req.headers.origin;
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  const path = url.pathname.replace(/\/+$/, "") || "/";
+  const method = req.method ?? "GET";
+  if (method === "OPTIONS") {
+    cors(res, origin);
+    res.setHeader("Access-Control-Allow-Methods", "GET,POST,DELETE,OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+  try {
+    if (method === "GET" && (path === "/health" || path === "/")) {
+      return send(res, 200, {
+        ok: true,
+        selections: deps.store.size(),
+        agents: deps.registry.size(),
+        subscribers: deps.bus.count()
+      }, origin);
+    }
+    if (method === "POST" && path === "/selection") {
+      const body = await readBody(req);
+      if (!body.ok) return send(res, 400, { error: body.error }, origin);
+      let parsed;
+      try {
+        parsed = JSON.parse(body.text);
+      } catch {
+        return send(res, 400, { error: "body is not valid JSON" }, origin);
+      }
+      const valid = validateSelection(parsed);
+      if (!valid.ok) return send(res, 400, { error: valid.error }, origin);
+      const stored = deps.store.add(valid.value);
+      deps.bus.publish({ type: "selection", data: stored, at: stored.at });
+      return send(res, 201, { ok: true, correlationId: stored.correlationId, at: stored.at }, origin);
+    }
+    if (method === "GET" && path === "/selection/latest") {
+      const latest = deps.store.latest();
+      return send(res, 200, { selection: latest }, origin);
+    }
+    if (method === "GET" && path === "/selection/history") {
+      const limit = Number(url.searchParams.get("limit") ?? deps.store.size());
+      return send(res, 200, {
+        selections: deps.store.history(Number.isFinite(limit) ? limit : deps.store.size())
+      }, origin);
+    }
+    if (method === "GET" && path === "/selection") {
+      const correlationId = url.searchParams.get("correlationId") ?? "";
+      return send(res, 200, { selection: deps.store.get(correlationId) }, origin);
+    }
+    if (method === "DELETE" && path === "/selection") {
+      deps.store.clear();
+      return send(res, 200, { ok: true, selections: 0 }, origin);
+    }
+    if (method === "POST" && path === "/agents") {
+      const body = await readBody(req);
+      if (!body.ok) return send(res, 400, { error: body.error }, origin);
+      let parsed;
+      try {
+        parsed = JSON.parse(body.text);
+      } catch {
+        return send(res, 400, { error: "body is not valid JSON" }, origin);
+      }
+      const reg = parsed;
+      if (!reg || typeof reg !== "object" || !reg.name || !reg.type || !reg.workspace) {
+        return send(res, 400, { error: "name, type and workspace are required" }, origin);
+      }
+      const agent = deps.registry.register({ name: reg.name, type: reg.type, workspace: reg.workspace, cwd: reg.cwd });
+      deps.bus.publish({ type: "agents", data: deps.registry.list(), at: (/* @__PURE__ */ new Date()).toISOString() });
+      return send(res, 201, { ok: true, agent }, origin);
+    }
+    if (method === "GET" && path === "/agents") {
+      return send(res, 200, { agents: deps.registry.list() }, origin);
+    }
+    if (method === "POST" && path.startsWith("/agents/") && path.endsWith("/heartbeat")) {
+      const id = path.slice("/agents/".length, -"/heartbeat".length);
+      const agent = deps.registry.heartbeat(id);
+      if (!agent) return send(res, 404, { error: "unknown agent" }, origin);
+      return send(res, 200, { ok: true, agent }, origin);
+    }
+    if (method === "DELETE" && path.startsWith("/agents/")) {
+      const id = path.slice("/agents/".length);
+      return send(res, 200, { ok: deps.registry.unregister(id) }, origin);
+    }
+    if (method === "GET" && (path === "/events" || path === "/thread-updates")) {
+      return streamEvents(req, res, deps, path === "/thread-updates" ? "thread" : null, origin);
+    }
+    return send(res, 404, { error: `no route for ${method} ${path}` }, origin);
+  } catch (e) {
+    if (!res.headersSent) send(res, 500, { error: e instanceof Error ? e.message : "bridge error" }, origin);
+    else res.end();
+  }
+}
+function streamEvents(req, res, deps, only, origin) {
+  cors(res, origin);
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache, no-transform",
+    Connection: "keep-alive"
+  });
+  res.write(": loupe bridge\n\n");
+  const write = (chunk) => {
+    res.write(chunk);
+  };
+  const unsubscribe = deps.bus.subscribe((event) => {
+    if (only && event.type !== only) return;
+    write(`event: ${event.type}
+data: ${JSON.stringify(event)}
+
+`);
+  });
+  const keepAlive = setInterval(() => write(": ping\n\n"), SSE_KEEPALIVE_MS);
+  if (typeof keepAlive.unref === "function") keepAlive.unref();
+  const done = () => {
+    clearInterval(keepAlive);
+    unsubscribe();
+  };
+  req.on("close", done);
+  req.on("error", done);
+  res.on("close", done);
+}
+
+// index.ts
 import {
   CHANGE_TYPE_LABELS,
   CHANGE_TYPES,
@@ -24,6 +436,10 @@ var PRIORITY_ARG = z.string().describe(`Priority, most urgent first: ${COMMENT_P
 var CHANGE_TYPE_ARG = z.string().describe(`Change type: ${CHANGE_TYPES.join(" / ")}.`);
 var API = (process.env.LOUPE_API || "http://localhost:8787").replace(/\/$/, "");
 var PROJECT_KEY = process.env.LOUPE_PROJECT_KEY || "pk_demo_acme";
+var BRIDGE_PORT = Number(process.env.LOUPE_BRIDGE_PORT ?? 9800);
+var store = new SelectionStore(Number(process.env.LOUPE_SELECTION_CAP ?? 50));
+var registry = new AgentRegistry();
+var bus = new EventBus();
 var ADMIN = process.env.LOUPE_ADMIN_KEY || "";
 async function api(path, init) {
   const res = await fetch(`${API}${path}`, {
@@ -47,7 +463,7 @@ async function fetchImage(url) {
     if (!res.ok) return null;
     const mimeType = res.headers.get("content-type") || "image/png";
     if (!mimeType.startsWith("image/")) return null;
-    return { mimeType, data: Buffer.from(await res.arrayBuffer()).toString("base64") };
+    return { mimeType, data: Buffer2.from(await res.arrayBuffer()).toString("base64") };
   } catch {
     return null;
   }
@@ -157,6 +573,7 @@ async function getComment({ id }) {
 async function updateStatus({ id, status }) {
   const stage = normalizeStatus(status);
   await api(`/v1/comments/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify({ status: stage }) });
+  bus.publishThread(id, stage === "resolved" ? "thread_resolved" : "status_changed", { status: stage });
   return wrap(`#${id} \u2192 ${STAGE_LABELS[stage]}`);
 }
 async function proposeChange({ id, html, css, notes }) {
@@ -168,9 +585,10 @@ async function proposeChange({ id, html, css, notes }) {
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   await api(`/v1/comments/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify({ proposal }) });
+  bus.publishThread(id, "preview_live", { author: proposal.author });
   return wrap(`Proposal saved for #${id}. The dev team can now review your modified HTML/CSS in the dashboard.`);
 }
-var server = new McpServer({ name: "loupe", version: "0.10.16" });
+var server = new McpServer({ name: "loupe", version: "0.10.17" });
 server.tool(
   "list_comments",
   "List Loupe product-feedback comments for the project as a task backlog. Each item carries its board stage, priority and change type, so you can start with the most urgent. Use this to see what a PM has flagged, then work through the items.",
@@ -215,8 +633,30 @@ function isEntrypoint() {
   }
 }
 if (isEntrypoint()) {
+  const bridge = BRIDGE_PORT ? await startHttpBridge(BRIDGE_PORT, { store, registry, bus }) : null;
+  const self = registry.register({
+    name: process.env.LOUPE_AGENT_NAME || "loupe-mcp",
+    type: process.env.LOUPE_AGENT_TYPE || "claude-code",
+    workspace: process.env.LOUPE_WORKSPACE || process.cwd(),
+    cwd: process.cwd()
+  });
+  const sweep = setInterval(() => {
+    if (registry.sweep().length) bus.publish({ type: "agents", data: registry.list(), at: (/* @__PURE__ */ new Date()).toISOString() });
+    registry.heartbeat(self.id);
+  }, AGENT_SWEEP_MS);
+  if (typeof sweep.unref === "function") sweep.unref();
+  const shutdown = async () => {
+    clearInterval(sweep);
+    registry.unregister(self.id);
+    await bridge?.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
   await server.connect(new StdioServerTransport());
-  console.error(`[loupe-mcp] connected \xB7 project=${PROJECT_KEY} \xB7 api=${API}`);
+  console.error(
+    `[loupe-mcp] connected \xB7 project=${PROJECT_KEY} \xB7 api=${API}` + (bridge ? ` \xB7 bridge=${bridge.url}` : " \xB7 bridge=disabled")
+  );
 }
 export {
   getComment,

package/package.json

@@ -5,7 +5,7 @@
     "email": "m.ashraf.saed@gmail.com",
     "url": "https://www.linkedin.com/in/mohamedashrafelsaed/"
   },
-  "version": "0.10.16",
+  "version": "0.10.17",
   "description": "MCP server that exposes Loupe comments to Claude Code as an actionable, fully-contextualized backlog.",
   "keywords": [
     "loupe",
@@ -46,6 +46,6 @@
     "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@loupekit/shared": "0.10.16"
+    "@loupekit/shared": "0.10.17"
   }
 }