@usercase/mcp 0.2.2 → 0.2.3-next.1

package/mcp/hub.js

@@ -459,6 +459,7 @@ class Hub {
     if (r.sentWithEnter) said.push("You pressed Enter to send it, as you would in a chat box.");
     if (r.heldEnter) said.push("The screen changed as you typed, so you did not press Enter — what you see is what typing alone did. If you would press Enter now, type the same text into that field again.");
     if (r.fileWindow) said.push(r.fileWindow);
+    if (r.backOut) said.push("This is the first page you opened on this site, so going back from here would take you off the site. You are still on the page you were on — if leaving the site is what you meant, leave; otherwise carry on here.");
     if (r.openedApp) said.push("That tried to open another app outside the browser (a share or app link). Nothing opened, and you are back on the page you were on.");
     if (r.swiped) said.push("It was cut off at the edge, so you swiped that row sideways to bring it into view, then tapped it.");
     // 개인정보 칸. 사이트가 막은 게 아니라 이 사람이 안 친 것이다 — 그렇게 알린다
@@ -521,7 +522,7 @@ class Hub {
     };
     ws.appendRun(row);
     // 대시보드로 — 키가 없으면 건너뛴다. 실패해도 방문은 끝낸다
-    const uploaded = await report.sendVisit(row, rec.person, rec.startedAt).catch((e) => `⚠ Could not upload to the dashboard (${e.message})`);
+    const uploaded = await report.sendVisit(row, rec.person, rec.startedAt, rec.visit ? rec.visit.screens : []).catch((e) => `⚠ Could not upload to the dashboard (${e.message})`);
     // 도구가 하지 못한 것들 — 우리 쪽 진단으로(사이트 글자 없음). 기본으로 켜져 있다, USERCASE_DIAGNOSTICS=off 로 끈다
     if (rec.visit && rec.visit.diag && rec.visit.diag.length) await report.sendDiagnostics(rec.visit.diag, rec.person.device).catch(() => 0);
     const doc = ws.loadPeople();

package/mcp/report.js

@@ -123,13 +123,32 @@ function payload(row, person, startedAt) {
   };
 }
 
+/**
+ * 문제가 있던 순간의 화면을 방문 id 로 먼저 올린다(서버 R2 screens/). 못 올린 걸음은 표시를 지운다 —
+ * 대시보드가 없는 사진 자리를 남기지 않게. 사진은 다시 보내지 않는다(outbox 에 넣지 않는다)
+ */
+async function sendScreens(item, screens) {
+  if (!screens || !screens.length) return item;
+  const failed = new Set();
+  for (const s of screens) {
+    try {
+      await call("POST", "/agent/screens", { id: item.id, step: s.step, image: s.image.toString("base64") }, 30000);
+    } catch {
+      failed.add(s.step);
+    }
+  }
+  const sent = new Set(screens.map((s) => s.step).filter((n) => !failed.has(n)));
+  return { ...item, steps: (item.steps || []).map((s) => (s && s.screen && !sent.has(s.step) ? { ...s, screen: undefined } : s)) };
+}
+
 /**
  * 방문 하나를 보내고, 전에 못 보낸 것도 같이 보낸다. 실패해도 방문은 막지 않는다 — 결과 한 줄만 돌려준다.
+ * @param screens  문제가 있던 순간의 화면 [{ step, image }] (Visit.screens)
  * @returns 요약에 붙일 한 줄, 키가 없으면 null
  */
-async function sendVisit(row, person, startedAt) {
+async function sendVisit(row, person, startedAt, screens = []) {
   if (!KEY_RE.test(apiKey())) return null;
-  const queue = [...readOutbox(), payload(row, person, startedAt)];
+  const queue = [...readOutbox(), await sendScreens(payload(row, person, startedAt), screens)];
   const left = [];
   let sent = 0;
   let lastErr = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.2",
+  "version": "0.2.3-next.1",
   "description": "Virtual users that browse your website and tell you what they thought — an MCP server for Claude Code",
   "license": "UNLICENSED",
   "homepage": "https://usercase.io",

package/src/run/visit.js

@@ -42,6 +42,83 @@ const STEP_SCHEMA = {
 /** 같은 조작을 연달아 몇 번까지. 굴리며 훑기·안 눌려서 거듭 누르기 */
 const MAX_TIMES = { click: 4, scroll: 5, scroll_up: 5 };
 
+/**
+ * 문제가 있던 순간의 화면 — 대시보드가 그 걸음 아래에 보인다(서버 /agent/screens). **방문자(AI)에게는 안 보인다.**
+ * 걸음마다 찍지 않는다. 영상(세션 리플레이)은 봇의 움직임이 드러나 쓰지 않기로 했다(10/21)
+ *   no_change    눌렀는데 화면이 그대로
+ *   left_unhappy 원하던 걸 못 이루고 떠남(leave, done=false) — 마지막 화면
+ *   covered      사이트의 무언가(팝업 등)가 덮어 못 누름 — 우리 카드·위젯이 덮은 것은 뺀다
+ *   error        화면이 깨짐 — 문서가 오류로 옴(4xx·5xx), 오류 문구뿐인 화면.
+ *                끝내 안 열리는 화면은 못 찍는다 — 불러오는 중에는 브라우저가 화면을 안 내준다(10/22 시험)
+ * 우리 카드(Usercase 질문 카드)는 찍지 않는다 — 사이트 문제가 아니다. 카드가 떠 있는 동안도 안 찍는다(10/22)
+ * 누른 곳(box)은 사진에 그리지 않고 걸음에 비율(0~1)로 적는다. 대시보드가 위에 그린다
+ */
+const MAX_SCREENS = 6;
+// 서버 앞 nginx 의 기본 본문 한도가 1MB 다 — base64 로 커지니 원본은 600KB 아래로
+const MAX_SCREEN_BYTES = 600 * 1024;
+
+/**
+ * 오류 문구뿐인 화면인가 — 404·"not found"·"application error" 등. 글이 짧은 화면만 본다(기사 속 "404" 는 아니다).
+ * 클라이언트에서 그리는 404(Next.js 등)는 문서가 200 으로 와서 상태로는 모른다
+ */
+async function errorScreen(page) {
+  return page
+    .evaluate(() => {
+      const t = ((document.body && document.body.innerText) || "").replace(/s+/g, " ").trim();
+      if (t.length > 600) return false;
+      return /(404|500|502|503)|not found|page (doesn.?t|does not|could not|cannot) (exist|be found)|application error|something went wrong|internal server error/i.test(t);
+    })
+    .catch(() => false);
+}
+
+/** 요소가 화면에서 차지한 곳(화면 비율). 화면 밖이거나 사라졌으면 null */
+async function boxOf(page, el) {
+  const b = el ? await el.boundingBox().catch(() => null) : null;
+  const vp = page.viewportSize();
+  if (!b || !vp || b.width <= 0 || b.height <= 0) return null;
+  const x0 = Math.max(0, b.x);
+  const y0 = Math.max(0, b.y);
+  const x1 = Math.min(vp.width, b.x + b.width);
+  const y1 = Math.min(vp.height, b.y + b.height);
+  if (x1 <= x0 || y1 <= y0) return null;
+  const r = (n) => Math.round(n * 1000) / 1000;
+  return { x: r(x0 / vp.width), y: r(y0 / vp.height), w: r((x1 - x0) / vp.width), h: r((y1 - y0) / vp.height) };
+}
+
+/**
+ * 누르기 전후를 견줄 지문 — 주소, 페이지 전체 글(보이는 것만, 굴려도 같다), 보이는 입력칸·그림, 누른 요소의 상태(색만 바뀌는 좋아요·토글).
+ * 입력칸은 글(innerText)에 안 잡힌다 — 검색 아이콘을 눌러 검색칸이 열렸는데 "그대로" 로 찍혔다(10/22 실험실 e4)
+ * 글이 저절로 바뀌는 사이트(넘어가는 배너)에서는 "바뀌었다" 로 본다 — 그대로라고 잘못 찍는 것보다 낫다
+ */
+async function clickPrint(page, el) {
+  const doc = await page
+    .evaluate(() => {
+      const shown = (n) => {
+        const r = n.getBoundingClientRect();
+        return r.width > 0 && r.height > 0 && getComputedStyle(n).visibility !== "hidden";
+      };
+      const extra = [...document.querySelectorAll("input,textarea,select,[contenteditable=true],img,video,iframe,canvas")]
+        .filter(shown)
+        .map((n) => [n.tagName, n.getAttribute("placeholder"), n.getAttribute("aria-label"), n.getAttribute("src")].join(":"))
+        .join("|");
+      const t = ((document.body && document.body.innerText) || "") + "|" + extra;
+      let h = 5381;
+      for (let i = 0; i < t.length; i++) h = ((h << 5) + h + t.charCodeAt(i)) | 0;
+      return `${t.length}:${h}`;
+    })
+    .catch(() => null);
+  const own = el
+    ? await el
+        .evaluate((n) =>
+          n.isConnected
+            ? [n.className && String(n.className), ...["aria-pressed", "aria-expanded", "aria-checked", "aria-selected", "aria-current", "data-state"].map((a) => n.getAttribute(a)), n.checked, n.value, (n.textContent || "").slice(0, 200)].join("|")
+            : null,
+        )
+        .catch(() => null)
+    : null;
+  return { url: page.url(), doc, own };
+}
+
 /**
  * 클릭 뒤 화면이 자리 잡기를 기다린다. 사람도 눌렀으면 뜰 때까지 본다.
  * 안 기다리면 느린 화면이 "눌러도 안 열린다" 로 읽힌다 — 10/13 bluetags 에서 카드가 "안 열린다 → 조금 뒤 열렸다".
@@ -301,6 +378,15 @@ class Visit {
     // 손은 방문 내내 이어진다 — 커서가 있던 자리에서 다음 곳으로 간다
     this.handState = { rhythm, mouse: null };
     this.steps = [];
+    /** 이번 조작으로 받은 문서의 상태 코드(본 탭의 화면 이동만). 조작마다 비운다 */
+    this.docStatus = null;
+    page.on("response", (res) => {
+      try {
+        if (res.request().isNavigationRequest() && res.frame() === page.mainFrame()) this.docStatus = res.status();
+      } catch {}
+    });
+    /** 문제가 있던 순간의 화면 { step, image(JPEG) } — 방문이 끝나면 hub 가 서버로 올린다 */
+    this.screens = [];
     this.history = [];
     this.seenPaths = new Set();
     this.card = null; // 처리한 카드(한 방문에 하나)
@@ -453,9 +539,11 @@ class Visit {
     const externalBefore = this.external.length;
     this.fileWindow = null;
     this.lastAction = decision.action;
+    this.docStatus = null;
 
     if (decision.action === "leave") {
       record.done = !!decision.done;
+      if (!record.done) await this.shoot(record, "left_unhappy");
       this.steps.push(record);
       this.log(`${record.step}. left — ${decision.why}`);
       // 떠나는 모양도 사람처럼. 데스크톱은 커서가 창 위로 빠져나간다
@@ -475,6 +563,7 @@ class Visit {
 
     const net = watchNet(page);
     let diagEl = null; // 진단에 생김새를 남길 요소
+    let probe = null; // 누르기 전 지문 — 눌렀는데 그대로였나
     if (decision.action === "read") {
       // 가만히 읽는 시간. 사람은 계속 누르지 않는다 — 이게 없으면 "N초 머묾" 같은 조건이 영영 안 걸린다.
       // 기다리는 건 다음 조작 때(waitTurn). 그 사이 카드가 뜨면 다음 조작 전에 본다
@@ -582,6 +671,7 @@ class Visit {
           // 같은 사이트를 새 탭으로 여는 링크는 이 탭에서 열게 한다. 사람은 열린 탭에서 이어 보고, 방문은 한 탭이다.
           // 새 탭을 잡아 옮기는 건(hub) 브라우저가 새 탭을 늦게, 주소 없이 알려 줘서 놓쳤다 —
           // 방문자는 "안 열린다" 를 보고 다시 누르면 "없어졌다" 가 됐다(10/14 실험실 p3, 첫 화면 카드)
+          probe = { el, before: await clickPrint(page, el) };
           await el
             .evaluate((n) => {
               const a = n.closest("a[target]");
@@ -589,9 +679,13 @@ class Visit {
             })
             .catch(() => {});
           // 사람 손이라 빗나갈 수 있다. 빈 곳을 누르면 아무 일도 안 일어난다 — 그게 헛클릭이다
+          let ours = false;
           const clicked = await hand
             .clickLikePerson(page, this.handState, el)
-            .catch((e) => ((record.skipped = e.human || humanClickError(e)), { missed: false }));
+            .catch((e) => ((record.skipped = e.human || humanClickError(e)), (ours = /eb-insight|eb-plugin/.test(String(e.message))), { missed: false }));
+          // 사이트의 무언가가 덮어 못 눌렀다. 우리 카드·위젯이 덮은 것은 사이트 탓이 아니다
+          if (record.skipped && /on top of it/.test(record.skipped) && !/survey card/.test(record.skipped) && !ours)
+            await this.shoot(record, "covered", await boxOf(page, el));
           if (clicked.missed) {
             record.missed = true;
             this.history.push("Your click landed just outside it and nothing happened.");
@@ -621,8 +715,14 @@ class Visit {
     if (/^https?:/i.test(before) && !/^https?:/i.test(page.url())) {
       await page.goto(before, { waitUntil: "domcontentloaded", timeout: 30000 }).catch(() => {});
       await page.waitForLoadState("networkidle", { timeout: 8000 }).catch(() => {});
-      record.openedApp = true;
-      this.diag.push({ kind: "left_to_blank", action: decision.action, shape: null });
+      // 뒤로 가기가 빈 페이지로 간 것은 앱이 아니라 방문의 시작보다 앞으로 간 것이다(바로 들어온 첫 페이지).
+      // "다른 앱을 열려 했다" 고 알리면 방문자가 사이트 탓으로 적었다(10/22 실험실 q4)
+      if (decision.action === "back") {
+        record.backOut = true;
+      } else {
+        record.openedApp = true;
+        this.diag.push({ kind: "left_to_blank", action: decision.action, shape: null });
+      }
     }
 
     // 사이트 밖으로 가는 링크였다. 끊었으니 방문자는 그대로 이 화면에 있다.
@@ -652,9 +752,38 @@ class Visit {
     if (this.fileWindow) record.fileWindow = fileWindowNote(this.fileWindow);
     await this.noteDiag(record, decision, diagEl);
 
+    // 화면이 깨졌다 — 오류로 온 문서, 오류 문구뿐인 화면. 바깥 사이트·앱·빈 페이지로 간 것은 뺀다
+    if (
+      !record.offsite &&
+      !record.openedApp &&
+      !record.backOut &&
+      ((this.docStatus && this.docStatus >= 400) || (page.url() !== before && (await errorScreen(page))))
+    )
+      await this.shoot(record, "error");
+
+    // 눌렀는데 그대로. 우리 쪽 사정(빗나감·막은 요청·바깥 사이트·파일 창)으로 그대로인 것은 빼고, 같은 것은 한 번만
+    if (
+      probe &&
+      !record.skipped &&
+      !record.missed &&
+      !record.closedOverlay &&
+      !record.offsite &&
+      !record.notSent &&
+      !record.notSentQuiet &&
+      !record.external &&
+      !record.fileWindow &&
+      !record.openedApp &&
+      !record.backOut &&
+      !this.steps.some((s) => s.screen && s.screen.kind === "no_change" && s.label === record.label && s.path === record.path)
+    ) {
+      const after = await clickPrint(page, probe.el);
+      if (after.url === probe.before.url && after.doc && after.doc === probe.before.doc && after.own !== null && after.own === probe.before.own)
+        await this.shoot(record, "no_change", await boxOf(page, probe.el));
+    }
+
     this.steps.push(record);
     this.history.push(
-      `${decision.action}${times > 1 ? ` ×${times}` : ""}${item ? ` "${item.label}"` : ""} — ${decision.why}${record.skipped ? ` (${record.skipped})` : ""}${record.cappedTimes ? " (that is the most in one go)" : ""}${record.offsite ? ` (it leads to another website, ${record.offsite})` : ""}${record.notSent ? " (it would have sent something to the site; it was not sent)" : ""}${record.fileWindow ? " (a window to choose a file opened; you closed it without choosing)" : ""}${record.personalField !== undefined ? " (you chose not to enter personal details there)" : ""}${record.openedApp ? " (it tried to open another app; nothing opened)" : ""}`,
+      `${decision.action}${times > 1 ? ` ×${times}` : ""}${item ? ` "${item.label}"` : ""} — ${decision.why}${record.skipped ? ` (${record.skipped})` : ""}${record.cappedTimes ? " (that is the most in one go)" : ""}${record.offsite ? ` (it leads to another website, ${record.offsite})` : ""}${record.notSent ? " (it would have sent something to the site; it was not sent)" : ""}${record.fileWindow ? " (a window to choose a file opened; you closed it without choosing)" : ""}${record.personalField !== undefined ? " (you chose not to enter personal details there)" : ""}${record.openedApp ? " (it tried to open another app; nothing opened)" : ""}${record.backOut ? " (going back from here would have taken you off the site; you stayed)" : ""}`,
     );
     this.log(`${record.step}. ${decision.action}${item ? ` "${String(item.label).slice(0, 30)}"` : ""}${record.skipped ? ` · ${record.skipped}` : ""} — ${decision.why}`);
     this.lastView = null;
@@ -677,6 +806,31 @@ class Visit {
       this.diag.push({ kind: "reclick_same", action, shape: await diag.shapeOf(el) });
   }
 
+  /**
+   * 문제가 있던 화면을 찍어 이 걸음에 붙인다(record.screen). 보이는 만큼만(뷰포트). 크면 한 번 더 작게, 그래도 크면 안 찍는다
+   * 실패해도 방문은 그대로 간다
+   */
+  async shoot(record, kind, box = null) {
+    if (!record || record.screen || this.screens.length >= MAX_SCREENS) return;
+    // 우리 카드가 떠 있다. 눌렀는데 그대로인 것도 카드가 가로챈 것일 수 있다 — 사이트 탓으로 찍지 않는다
+    const card = await readCard(this.page).catch(() => null);
+    if (card && card.visible) return;
+    const image = await this.snap();
+    if (!image) return;
+    record.screen = { kind, box };
+    this.screens.push({ step: record.step, image });
+  }
+
+  /** 뷰포트 JPEG. 크면 한 번 더 작게, 그래도 크면 null */
+  async snap() {
+    let image = null;
+    for (const quality of [70, 45]) {
+      image = await this.page.screenshot({ type: "jpeg", quality, scale: "css", timeout: 5000 }).catch(() => null);
+      if (!image || image.length <= MAX_SCREEN_BYTES) break;
+    }
+    return image && image.length <= MAX_SCREEN_BYTES ? image : null;
+  }
+
   /** 카드 판단에 넘길 "이번 방문에 한 일" */
   pathText() {
     return this.history.length ? this.history.slice(-6).join(" / ") : "just arrived";