@usercase/mcp 0.2.5 → 0.2.6-next.0

package/README.md

@@ -17,14 +17,18 @@ Open your repository in Claude Code and ask it to research your site. Claude rea
 
 ## Connect
 
-1. In the Usercase dashboard, open **Settings → Integrations → API keys** and create a key. It starts with `eb_sk_` and is shown once.
-2. In your repository folder, run:
+1. In your repository folder, run:
 
    ```sh
-   claude mcp add usercase -e USERCASE_API_KEY=eb_sk_... -- npx -y @usercase/mcp@latest
+   claude mcp add usercase -- npx -y @usercase/mcp@latest
    ```
 
    This is saved to your Claude Code settings (`~/.claude.json`), not to your repository. `@latest` picks up new versions each time Claude Code starts.
+2. Run any Usercase command, such as `/mcp__usercase__install`. Your browser opens on the Usercase dashboard: sign in, check that the code matches the one in your terminal, and pick the project (or create one). The key is made on your computer and saved in `~/.usercase/credentials.json`; only its hash is sent to Usercase. It shows up in **Settings → Integrations → API keys**, where you can revoke it.
+
+Each repository keeps its own connection, so different sites can go to different projects. To switch this repository to another project, run `/mcp__usercase__connect`.
+
+Prefer a key? Create one under **Settings → Integrations → API keys** and add `-e USERCASE_API_KEY=eb_sk_...` before `--`. A key you set this way is used first.
 
 ## Install the script
 
@@ -34,7 +38,7 @@ The survey cards come from the Usercase script on your site. If it isn't there y
 /mcp__usercase__install
 ```
 
-Claude gets your project's script (from the API key), puts it once in your root layout or document head, shows you the diff, and opens your local site to check that it loads. It doesn't commit or deploy. Real visitors are recorded once you deploy the change.
+Claude gets your project's script (from the connected project), puts it once in your root layout or document head, shows you the diff, and opens your local site to check that it loads. It doesn't commit or deploy. Real visitors are recorded once you deploy the change.
 
 ## Run a research
 
@@ -130,7 +134,7 @@ Pass with `claude mcp add ... -e NAME=value`.
 
 | Name | What it does |
 |---|---|
-| `USERCASE_API_KEY` | Your project API key. Without it, visits stay on your machine only. |
+| `USERCASE_API_KEY` | A project API key, instead of connecting in the browser. Used before a saved connection. |
 | `USERCASE_AGENT_KEY` | Your firewall secret (see above). 16+ characters. |
 | `USERCASE_ALLOW_WRITE_PATHS` | Comma-separated path patterns where non-GET requests are allowed, for sites that load pages with `POST` after sign-in. Everything else stays blocked. |
 | `USERCASE_DIAGNOSTICS` | `off` stops sending diagnostics. On by default: when the tool cannot do something or misreads the screen (a button cut off or covered, a click that landed elsewhere, a change it did not notice), Usercase receives the kind of failure, the element's shape, the page path, the HTML around the element and a screenshot of that moment, to improve the tool. Only the Usercase team sees them; they are kept for 30 days. |

package/agents/install.md

@@ -6,7 +6,7 @@ You are in the site's repository. Add the Usercase script so the site starts sen
 
 ## 1. Get the script
 
-Call `install_snippet`. It returns the project this repository is connected to and the exact script tag. If it says there is no API key or the key is wrong, stop and show the user its message — they create a key in the dashboard and add the MCP server again with it.
+Call `install_snippet`. It returns the project this repository is connected to and the exact script tag. If it says it is not connected yet, show the user its message — a browser window opens where they pick the project — and call `install_snippet` again once they say they are done. If it says the key is wrong, stop and show the user its message.
 
 ## 2. Put it on every page
 

package/agents/research.md

@@ -9,7 +9,7 @@ You are the coordinator. Virtual users will visit the site in a real browser, on
 
 ## 0. Setup (once)
 
-Call `setup` first. If it says it installed or updated the agent, ask the user to restart Claude Code and run this again — until then the visitors would use the old one, or none.
+Call `setup` first. If it says it installed or updated the agent, ask the user to restart {{agent}} and run this again — until then the visitors would use the old one, or none.
 
 ## 1. Check the site
 
@@ -88,7 +88,8 @@ The goal is still the person's own reason for coming, in their words — never "
 
 ## 4. Send the visitors
 
-For each person, start a `{{visitor}}` sub-agent with a prompt like:
+{{warmup}}
+For each person, start a `{{visitor}}` sub-agent{{spawn}} with a prompt like:
 
 > Call open_visit with person "<id>" and live this visit as that person until you leave.
 

package/mcp/connect.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * 브라우저 연결 — 키를 복사해 붙여 넣지 않고 연결한다(10/28).
+ *
+ * MCP 가 키를 직접 만들고 그 sha256 만 서버에 맡긴다(POST /agent/connect). 브라우저로 대시보드 /connect/:id 를 열면
+ * 고객이 로그인해 프로젝트를 고르고, 대시보드가 그 해시로 키를 만든다. 키 원문은 이 컴퓨터를 떠나지 않는다.
+ * MCP 는 같은 키로 상태를 묻다가(GET /agent/connect/:id) 승인되면 ~/.usercase/credentials.json 에 둔다.
+ * 저장소 폴더마다 따로 둔다 — 사이트마다 저장소·프로젝트가 다르다. 저장소 A 에서 프로젝트를 바꿔도 B 는 그대로다.
+ * 처음 여는 저장소는 다른 저장소의 키를 빌리지 않고 연결부터 한다(엉뚱한 프로젝트로 올라가지 않게).
+ *
+ * 키를 고르는 순서: 직접 넣은 키(USERCASE_API_KEY) → 연결로 받은 키. 직접 넣은 키가 이번 세션에 거절되면 연결로 받은 키를 쓴다
+ * (MCP 는 사용자가 넣은 환경변수를 고칠 수 없다).
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+const { spawn } = require("child_process");
+
+const KEY_ENV = "USERCASE_API_KEY";
+const KEY_RE = /^eb_sk_[A-Za-z0-9]{32}$/;
+// 사람의 홈 폴더 — 저장소의 .usercase/ 에 두면 git 에 들어갈 수 있다
+const CRED_DIR = process.env.USERCASE_HOME || path.join(os.homedir(), ".usercase");
+const CRED = path.join(CRED_DIR, "credentials.json");
+// 이 MCP 를 띄운 폴더(에이전트가 연 저장소). Windows 는 대소문자를 가리지 않는다
+const FOLDER = (() => {
+  const p = path.resolve(process.cwd());
+  return process.platform === "win32" ? p.toLowerCase() : p;
+})();
+const POLL_MS = 3000;
+// 도구 한 번에 기다리는 시간. Codex 의 도구 시간 제한(기본 60초)보다 짧게 — 못 끝나면 다음 호출이 이어서 기다린다
+const WAIT_MS = 30000;
+
+let envRejected = false;
+let savedRejected = false; // 연결로 받은 키가 이번 세션에 거절됐다(대시보드에서 지웠다)
+let pending = null; // { id, code, url, key, expiresAt }
+
+/** 플러그인이 값을 못 채우면 `${user_config.api_key}` 같은 글자가 그대로 온다 — 빈 값으로 본다 */
+const envKey = () => {
+  const v = (process.env[KEY_ENV] || "").trim();
+  return v && !v.includes("${") ? v : "";
+};
+
+/** { v: 2, folders: { <폴더>: { key, projectId, title, savedAt } } } — 그 전(한 개만)이면 빈 것으로 본다 */
+function readAll() {
+  try {
+    const c = JSON.parse(fs.readFileSync(CRED, "utf8"));
+    return c && c.v === 2 && c.folders && typeof c.folders === "object" ? c : { v: 2, folders: {} };
+  } catch {
+    return { v: 2, folders: {} };
+  }
+}
+function writeAll(c) {
+  fs.mkdirSync(CRED_DIR, { recursive: true });
+  fs.writeFileSync(CRED, JSON.stringify(c, null, 2), { mode: 0o600 });
+}
+
+function readSaved() {
+  const c = readAll().folders[FOLDER];
+  return c && KEY_RE.test(c.key) ? c : null;
+}
+
+function saveKey(key, project) {
+  const c = readAll();
+  c.folders[FOLDER] = { key, projectId: project.id, title: project.title, savedAt: new Date().toISOString() };
+  writeAll(c);
+}
+
+/** 이 폴더의 연결만 지운다 */
+function dropSaved() {
+  const c = readAll();
+  if (!c.folders[FOLDER]) return;
+  delete c.folders[FOLDER];
+  writeAll(c);
+}
+
+/** 지금 쓸 키와 어디서 왔는지 */
+function current() {
+  const env = envKey();
+  if (env && !envRejected) return { key: env, source: "env" };
+  const saved = readSaved();
+  if (saved) return { key: saved.key, source: "saved", title: saved.title };
+  // 직접 넣은 키가 거절됐고 연결로 받은 키도 없다 — 연결부터
+  return { key: "", source: "none", envRejected: !!env, savedRejected };
+}
+
+/** 연결로 받은 키를 버린다 — 다른 프로젝트로 다시 연결할 때 */
+function forget() {
+  pending = null;
+  dropSaved();
+}
+
+/** 서버가 키를 거절했다(401). 연결로 받은 키면 지운다 — 다음 호출이 다시 연결한다 */
+function rejected(source) {
+  if (source === "env") envRejected = true;
+  if (source === "saved") {
+    savedRejected = true;
+    dropSaved();
+  }
+}
+
+function newKey() {
+  const A = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let out = "";
+  while (out.length < 32) for (const b of crypto.randomBytes(48)) if (b < 248 && out.length < 32) out += A[b % 62];
+  return `eb_sk_${out}`;
+}
+
+function openBrowser(url) {
+  try {
+    const [cmd, args] =
+      process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+    spawn(cmd, args, { stdio: "ignore", detached: true, windowsHide: true }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * 연결한다 — 진행 중인 연결이 있으면 이어서 기다리고, 없으면 새로 시작해 브라우저를 연다.
+ * @param api   (method, route, body, key) → json. report.js 의 fetch
+ * @param client 연결 화면에 보일 도구 이름(claude-code · codex …)
+ * @returns { status: "approved", title } | { status: "pending", url, code, opened } | { status: "denied" | "expired" }
+ */
+async function connect(api, client) {
+  if (pending && Date.now() > pending.expiresAt) pending = null;
+  let opened = false;
+  if (!pending) {
+    const key = newKey();
+    // 앞 10글자는 대시보드 키 목록에 보이는 부분 — 원문은 보내지 않는다
+    const r = await api("POST", "/agent/connect", { keyHash: crypto.createHash("sha256").update(key).digest("hex"), keyPrefix: key.slice(0, 10), client, host: os.hostname() });
+    pending = { id: r.id, code: r.code, url: r.url, key, expiresAt: Date.now() + (r.expiresIn || 900) * 1000 };
+    opened = openBrowser(r.url);
+    // 처음엔 기다리지 않는다 — 브라우저 화면이 "터미널의 코드와 맞는지 보라" 고 하니 코드가 먼저 터미널에 떠야 한다(10/28 Codex 시험).
+    // 사용자가 승인한 뒤 다음 호출이 이어서 확인한다
+    return { status: "pending", url: pending.url, code: pending.code, opened };
+  }
+  const until = Date.now() + WAIT_MS;
+  while (Date.now() < until) {
+    const s = await api("GET", `/agent/connect/${pending.id}`, null, pending.key).catch(() => null);
+    if (s && s.status === "approved") {
+      saveKey(pending.key, s.project);
+      savedRejected = false;
+      envRejected = !!envKey(); // 직접 넣은 키보다 방금 받은 키를 쓴다
+      pending = null;
+      return { status: "approved", title: s.project.title };
+    }
+    if (s && (s.status === "denied" || s.status === "expired")) {
+      pending = null;
+      return { status: s.status };
+    }
+    await sleep(POLL_MS);
+  }
+  return { status: "pending", url: pending.url, code: pending.code, opened };
+}
+
+/** 연결 결과를 사람(과 에이전트)에게 할 말로 */
+function describe(r) {
+  if (r.status === "approved") return `✓ Connected — visits go to the "${r.title}" project`;
+  if (r.status === "denied") return "Connecting was cancelled in the browser. Run the command again to connect";
+  if (r.status === "expired") return "The connect link expired. Run the command again to get a new one";
+  return [
+    `Not connected yet. Tell the user right away, before doing anything else: ${r.opened ? "a browser window opened" : "open this link"} to connect Usercase — ${r.url}`,
+    `The code on that page must be ${r.code}. They sign in, pick the project and press Connect.`,
+    "Then wait for the user to say they are done, and call this tool again — it picks up the same request.",
+  ].join("\n");
+}
+
+/** 연결을 기다리는 중인가 — 프로젝트 바꾸기를 다시 불러도 새로 시작하지 않고 이어서 기다리게 */
+const isPending = () => !!pending && Date.now() < pending.expiresAt;
+
+module.exports = { KEY_ENV, KEY_RE, CRED, FOLDER, current, rejected, forget, isPending, connect, describe };

package/mcp/report.js

@@ -10,31 +10,43 @@ const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
 const ws = require("./workspace.js");
+const conn = require("./connect.js");
 
-const KEY_ENV = "USERCASE_API_KEY";
+const KEY_ENV = conn.KEY_ENV;
 const URL_ENV = "USERCASE_API_URL";
 const DEFAULT_API = "https://app.usercase.io/koa";
-const KEY_RE = /^eb_sk_[A-Za-z0-9]{32}$/;
+const KEY_RE = conn.KEY_RE;
 const OUTBOX = path.join(ws.DIR, "outbox.jsonl");
 
-const apiKey = () => (process.env[KEY_ENV] || "").trim();
+/** 직접 넣은 키(USERCASE_API_KEY) 또는 브라우저 연결로 받은 키(connect.js) */
+const apiKey = () => conn.current().key;
 // 플러그인이면 키는 플러그인 설정에 있다(server.js 의 PLUGIN 과 같은 표시)
 const PLUGIN = process.env.USERCASE_PLUGIN === "1";
-const NO_KEY = () =>
-  PLUGIN
-    ? "No API key. Create one in the dashboard (Settings → Integrations → API keys), then enter it with /plugin → Installed → usercase → Configure"
-    : `No API key (${KEY_ENV}). Create one in the dashboard (Settings → Integrations → API keys), then add this MCP server again with -e ${KEY_ENV}=<key>`;
 const BAD_KEY = () =>
-  `${PLUGIN ? "The API key" : KEY_ENV} does not look right (38 characters starting with eb_sk_). Copy it again from the dashboard${PLUGIN ? " and enter it with /plugin → Installed → usercase → Configure" : ""}`;
+  `${PLUGIN ? "The API key" : KEY_ENV} does not look right (38 characters starting with eb_sk_). Copy it again from the dashboard${PLUGIN ? " and enter it with /plugin → Installed → usercase → Configure" : ""}, or leave it empty to connect in the browser`;
+// 직접 넣은 키는 MCP 가 고칠 수 없다 — 지워도 된다고만 알린다
+const ENV_REVOKED = () =>
+  `The API key you set (${PLUGIN ? "plugin settings" : KEY_ENV}) was rejected — it may have been revoked. You can remove it there.`;
 const apiBase = () => (process.env[URL_ENV] || DEFAULT_API).replace(/\/$/, "");
 
 /** 이 MCP 세션 하나 = 실행 하나. 대시보드가 실행별로 묶는다 */
 const RUN_REF = `run_${new Date().toISOString().slice(0, 10)}_${crypto.randomBytes(6).toString("hex")}`;
 
-async function call(method, route, body, timeoutMs = 15000) {
+// 어느 에이전트로 돌았나 — MCP 연결 때 클라이언트가 알려 준 이름(clientInfo.name). 대시보드는 claude-code 만 "Claude Code" 로 바꿔 보인다
+let client = "";
+const setClient = (name) => {
+  const n = String(name || "").trim();
+  client = /claude/i.test(n) ? "claude-code" : /codex/i.test(n) ? "codex" : n.slice(0, 40);
+};
+const toolName = () => client || (process.env.USERCASE_CLIENT === "codex" ? "codex" : "claude-code");
+
+/** @param key  이 키로 부른다(연결 API). 없으면 지금 쓰는 키 */
+async function call(method, route, body, timeoutMs = 15000, key) {
+  const cur = key === undefined ? conn.current() : null;
+  const k = key === undefined ? cur.key : key;
   const res = await fetch(`${apiBase()}${route}`, {
     method,
-    headers: { Authorization: `Bearer ${apiKey()}`, "Content-Type": "application/json" },
+    headers: { ...(k ? { Authorization: `Bearer ${k}` } : {}), "Content-Type": "application/json" },
     body: body ? JSON.stringify(body) : undefined,
     signal: AbortSignal.timeout(timeoutMs),
   });
@@ -43,39 +55,69 @@ async function call(method, route, body, timeoutMs = 15000) {
   try {
     json = JSON.parse(text);
   } catch {}
-  if (!res.ok) throw Object.assign(new Error((json && json.error) || `HTTP ${res.status}`), { status: res.status });
+  if (!res.ok) {
+    // 키가 거절됐다 — 연결로 받은 키면 지우고, 직접 넣은 키면 이번 세션엔 안 쓴다. 다음 호출이 브라우저 연결로 간다
+    if (res.status === 401 && cur && cur.source !== "none") {
+      conn.rejected(cur.source);
+      me = null;
+    }
+    throw Object.assign(new Error((json && json.error) || `HTTP ${res.status}`), { status: res.status });
+  }
   return json;
 }
 
-/** 키 상태 한 줄 — check_site 가 보여 준다. sdkProject 가 있으면 키의 프로젝트와 맞는지 본다 */
-async function describeKey(sdkProject) {
-  const key = apiKey();
-  if (!key) return `· No API key (${KEY_ENV}). Visits stay on this computer and are not sent to the dashboard. Create one in the dashboard: Settings → Integrations → API keys`;
-  if (!KEY_RE.test(key)) return `⚠ ${KEY_ENV} does not look right (38 characters starting with eb_sk_). Copy it again from the dashboard`;
+/** 연결 API — 키 없이(시작) 또는 새로 만든 키로(상태) 부른다 */
+const connectApi = (method, route, body, key) => call(method, route, body, 15000, key || "");
+
+/** 키가 없으면 브라우저로 연결한다. 연결 못 했으면 사람에게 할 말을 던진다 */
+async function ensureKey() {
+  const cur = conn.current();
+  if (cur.source !== "none") {
+    if (!KEY_RE.test(cur.key)) throw new Error(BAD_KEY());
+    return null;
+  }
+  const r = await conn.connect(connectApi, toolName());
+  const why = cur.envRejected ? ENV_REVOKED() + "\n" : cur.savedRejected ? "The connection was revoked in the dashboard.\n" : "";
+  const msg = why + conn.describe(r);
+  if (r.status !== "approved") throw new Error(msg);
+  return msg;
+}
+
+/** 이 키의 프로젝트 — outbox 가 다른 프로젝트의 기록을 보내지 않게. 세션에 한 번 */
+let me = null;
+async function getMe() {
+  if (!me) me = await call("GET", "/agent/me");
+  return me;
+}
+
+/** 연결 상태 한 줄 — check_site 가 보여 준다. 연결이 없으면 브라우저 연결을 시작한다. sdkProject 가 있으면 키의 프로젝트와 맞는지 본다 */
+async function describeKey(sdkProject, retried = false) {
+  // check_site 는 지금 상태를 본다 — 대시보드에서 키를 지웠을 수 있다
+  me = null;
+  let connected = null;
+  try {
+    connected = await ensureKey();
+  } catch (e) {
+    return `⚠ ${e.message}`;
+  }
   try {
-    const me = await call("GET", "/agent/me");
-    if (sdkProject && me.projectId !== sdkProject)
-      return `⚠ The API key belongs to the "${me.title}" project, but the SDK on this site sends to another project (${sdkProject}). Visits and card answers would land in different projects. Use the key for the right project`;
-    return `✓ API key — visits are sent to the "${me.title}" project`;
+    const m = await getMe();
+    if (sdkProject && m.projectId !== sdkProject)
+      return `⚠ Connected to the "${m.title}" project, but the SDK on this site sends to another project (${sdkProject}). Visits and card answers would land in different projects. Call the \`connect\` tool to pick the right project`;
+    return connected || `✓ Connected — visits are sent to the "${m.title}" project. To use another project, call the \`connect\` tool`;
   } catch (e) {
-    if (e.status === 401) return `⚠ The API key is wrong or revoked. Create a new one in the dashboard`;
+    // 키가 거절됐다 — call 이 지웠으니 한 번만 다시(브라우저 연결로)
+    if (e.status === 401 && !retried) return describeKey(sdkProject, true);
+    if (e.status === 401) return `⚠ The connection was rejected. Run check_site again to connect in the browser`;
     return `⚠ Could not reach the Usercase server (${e.message}). Visits can still run; records will be sent later`;
   }
 }
 
 /** 키의 프로젝트와 그 설치 스크립트(서버가 대시보드 설치 화면과 같은 글을 준다) — install_snippet 이 쓴다 */
 async function getInstall() {
-  const key = apiKey();
-  if (!key) throw new Error(NO_KEY());
-  if (!KEY_RE.test(key)) throw new Error(BAD_KEY());
-  try {
-    const me = await call("GET", "/agent/me");
-    if (!me.snippet) throw new Error("The Usercase server did not return a script. It may be an older server version");
-    return me;
-  } catch (e) {
-    if (e.status === 401) throw new Error("The API key is wrong or revoked. Create a new one in the dashboard");
-    throw e;
-  }
+  const m = await keyed("GET", "/agent/me");
+  if (!m.snippet) throw new Error("The Usercase server did not return a script. It may be an older server version");
+  return m;
 }
 
 function readOutbox() {
@@ -107,7 +149,7 @@ function payload(row, person, startedAt) {
   return {
     id: crypto.randomUUID(),
     run: RUN_REF,
-    tool: "claude-code",
+    tool: toolName(),
     site: row.site,
     person: person.id,
     personUid: person.uid,
@@ -156,23 +198,34 @@ async function sendScreens(item, screens) {
  */
 async function sendVisit(row, person, startedAt, screens = []) {
   if (!KEY_RE.test(apiKey())) return null;
-  const queue = [...readOutbox(), await sendScreens(payload(row, person, startedAt), screens)];
+  // 기록마다 어느 프로젝트로 가야 했는지 붙여 둔다 — 다시 연결하며 다른 프로젝트를 골라도 엉뚱한 곳에 들어가지 않게
+  const project = await getMe().then((m) => m.projectId).catch(() => null);
+  const fresh = { ...(await sendScreens(payload(row, person, startedAt), screens)), _project: project };
+  const queue = [...readOutbox(), fresh];
   const left = [];
   let sent = 0;
+  let other = 0;
   let lastErr = null;
   for (const item of queue) {
+    if (item._project && project && item._project !== project) {
+      other++;
+      left.push(item);
+      continue;
+    }
+    const { _project, ...body } = item;
     try {
-      await call("POST", "/agent/visits", item);
+      await call("POST", "/agent/visits", body);
       sent++;
     } catch (e) {
       lastErr = e;
-      // 키가 틀렸으면 다시 보내도 소용없다 — 그래도 버리지 않고 남겨 둔다(키를 고치면 다음에 간다)
-      left.push(item);
+      // 키가 틀렸으면 다시 보내도 소용없다 — 그래도 버리지 않고 남겨 둔다(다시 연결하면 다음에 간다)
+      left.push({ ...item, _project: _project || project });
     }
   }
   writeOutbox(left);
-  if (!left.length) return `· Sent to the dashboard${sent > 1 ? ` (${sent} including earlier ones)` : ""}`;
-  return `⚠ Could not upload to the dashboard (${lastErr?.status === 401 ? "API key rejected" : lastErr?.message}) — ${left.length} kept in ${OUTBOX}, will retry next time`;
+  const otherLine = other ? ` · ${other} from another project kept in ${OUTBOX} until you connect that project again` : "";
+  if (left.length === other) return `· Sent to the dashboard${sent > 1 ? ` (${sent} including earlier ones)` : ""}${otherLine}`;
+  return `⚠ Could not upload to the dashboard (${lastErr?.status === 401 ? "connection rejected — run check_site to connect again" : lastErr?.message}) — ${left.length - other} kept in ${OUTBOX}, will retry next time${otherLine}`;
 }
 
 /**
@@ -193,16 +246,30 @@ async function sendDiagnostics(events, device, shots = []) {
   }
 }
 
-/** 키가 있어야 하는 호출 — 없거나 틀렸으면 사용자에게 할 말로 바꿔 던진다 */
-async function keyed(method, route, body, timeoutMs) {
-  const key = apiKey();
-  if (!key) throw new Error(NO_KEY());
-  if (!KEY_RE.test(key)) throw new Error(BAD_KEY());
+/** 다른 프로젝트로 다시 연결한다 — 연결로 받은 키는 버리고 브라우저를 연다. 직접 넣은 키는 MCP 가 바꿀 수 없다 */
+async function reconnect() {
+  const cur = conn.current();
+  if (cur.source === "env") return `You set an API key (${PLUGIN ? "plugin settings" : KEY_ENV}), and it is used first. Remove it there to connect in the browser, or set the other project's key instead.`;
+  // 지금 연결은 새 연결이 승인될 때까지 둔다 — 브라우저에서 취소해도 원래대로 쓴다. 다시 부르면 진행 중인 연결을 이어서 기다린다
+  const before = cur.source === "saved" ? `Connected now: "${cur.title}" (this folder only).\n` : "";
+  try {
+    const r = await conn.connect(connectApi, toolName());
+    if (r.status === "approved") me = null;
+    return before + conn.describe(r) + (r.status === "approved" ? " — for this folder only" : "");
+  } catch (e) {
+    return before + e.message;
+  }
+}
+
+/** 키가 있어야 하는 호출 — 없으면 브라우저로 연결하고, 거절되면 한 번 다시 연결한다. 못 하면 사용자에게 할 말로 던진다 */
+async function keyed(method, route, body, timeoutMs, retried = false) {
+  await ensureKey();
   try {
     return await call(method, route, body, timeoutMs);
   } catch (e) {
-    if (e.status === 401) throw new Error("The API key is wrong or revoked. Create a new one in the dashboard");
-    if (e.status === 404) throw new Error(`${e.message}. Check the id — it must belong to the project of this API key`);
+    if (e.status === 401 && !retried) return keyed(method, route, body, timeoutMs, true);
+    if (e.status === 401) throw new Error("The connection was rejected. Call this tool again to connect in the browser");
+    if (e.status === 404) throw new Error(`${e.message}. Check the id — it must belong to the connected project`);
     throw e;
   }
 }
@@ -227,7 +294,9 @@ module.exports = {
   KEY_ENV,
   URL_ENV,
   RUN_REF,
+  setClient,
   describeKey,
+  reconnect,
   getInstall,
   sendVisit,
   sendDiagnostics,

package/mcp/server.js

@@ -32,8 +32,17 @@ const server = new McpServer({ name: "usercase", version: require("../package.js
 // 플러그인에서는 방문자 에이전트가 플러그인에 들어 있어 이름이 usercase:usercase-visitor 이고(도구도 mcp__plugin_usercase_usercase__*),
 // 명령은 /usercase:research 같은 스킬이다 — 스킬은 MCP 프롬프트를 못 부르니 instructions 도구로 같은 글을 받는다
 const PLUGIN = process.env.USERCASE_PLUGIN === "1";
-const VISITOR = PLUGIN ? "usercase:usercase-visitor" : "usercase-visitor";
-const cmd = (name) => (PLUGIN ? `/usercase:${name}` : `/mcp__usercase__${name}`);
+// Codex 로 떴는지(시험 중). Codex 는 MCP 프롬프트를 명령으로 안 보여 줘서 플러그인처럼 스킬($usercase-research)이 instructions 도구를 부르고,
+// 방문자는 ~/.codex/agents/usercase_visitor.toml 의 사용자 에이전트다
+const CODEX = process.env.USERCASE_CLIENT === "codex";
+// 그 밖의 MCP 클라이언트(Cursor, VS Code …) — 대시보드의 MCP 설정 칸이 USERCASE_CLIENT=other 를 준다. 프롬프트를 명령으로 안 보여 주는 곳이 있어 instructions 도구를 둔다
+const OTHER = process.env.USERCASE_CLIENT === "other";
+const VISITOR = PLUGIN ? "usercase:usercase-visitor" : CODEX ? "usercase_visitor" : "usercase-visitor";
+// 플러그인 스킬은 /usercase:이름. 직접 붙인 MCP 의 프롬프트는 목록에 /usercase:이름 (MCP) 로 보이지만 그렇게 치면 안 돌고 /mcp__usercase__이름 으로만 돈다(10/28 확인).
+// Codex 플러그인 스킬은 $usercase:이름
+const cmd = (name) => (CODEX ? `$usercase:${name}` : PLUGIN ? `/usercase:${name}` : `/mcp__usercase__${name}`);
+// Codex 의 spawn_agent 는 기본으로 부모 대화 전체(읽은 코드·다른 사람들)를 물려준다 — 방문자는 빈 상태로 시작해야 한다(10/28)
+const SPAWN = CODEX ? " (with `fork_turns` set to `none`, so it starts without this conversation)" : "";
 
 const text = (t) => ({ content: [{ type: "text", text: String(t) }] });
 /** 방문 화면 + 그 화면의 이름 없는 아이콘 그림(있으면). 방문자는 그림을 보고 모양으로 안다 */
@@ -81,7 +90,7 @@ server.registerTool(
   "install_snippet",
   {
     description:
-      "Get the Usercase script for the project this API key belongs to, with where to put it per framework. Use when check_site says the SDK is not running and you are in the site's repository: add the script once to the root layout/document, show the user the diff, then run check_site on the local site to confirm. Do not commit or deploy unless asked.",
+      "Get the Usercase script for the connected project, with where to put it per framework. If nothing is connected yet, it opens the browser to connect and says what to tell the user. Use when check_site says the SDK is not running and you are in the site's repository: add the script once to the root layout/document, show the user the diff, then run check_site on the local site to confirm. Do not commit or deploy unless asked.",
     inputSchema: {},
   },
   wrap(async () => {
@@ -199,6 +208,8 @@ server.registerTool(
         ...ids.incoming.map((p) => `- ${p.id} · ${personLine(p)}`),
         `${doc.people.length} in total (${doc.people.filter((x) => !x.usedAt).length} not visited yet)`,
         coverageLine(doc.people),
+        // 절차서에만 쓰면 건너뛴다(10/28 둘째 판) — 방문자를 띄우기 직전인 여기서 한 번 더
+        ...(CODEX && warmed.size < 2 ? [`\nBefore you start any visitor: ${WARMUP_STEP}`] : []),
       ].join("\n"),
     );
   }),
@@ -290,6 +301,43 @@ function removeOldAgent() {
   return removed;
 }
 
+// Codex 는 플러그인에 에이전트를 넣을 수 없다(10/28 확인) — setup 이 ~/.codex/agents/ 에 깐다. 지시문은 Claude 것과 같다
+const CODEX_AGENT_DEST = path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "agents", "usercase_visitor.toml");
+function codexAgentToml() {
+  const body = fs
+    .readFileSync(AGENT_SRC, "utf8")
+    .replace(/\r\n/g, "\n")
+    .replace(/^---\n[\s\S]*?\n---\n+/, "")
+    .replace(/^<!--[\s\S]*?-->\n+/m, "")
+    .trim();
+  if (body.includes("'''")) throw new Error("usercase-visitor.md contains ''' and cannot go into a TOML literal string");
+  return [
+    `name = "usercase_visitor"`,
+    `description = "One Usercase virtual user visiting a website in a real browser. Give it only the person's number (e.g. p3) from .usercase/people.json. It sees nothing but the screen."`,
+    `sandbox_mode = "read-only"`,
+    "",
+    "developer_instructions = '''",
+    body,
+    "",
+    "You may only use the usercase tools open_visit, act and answer_card. Never use any other tool.",
+    "'''",
+    "",
+    "[features]",
+    "shell_tool = false",
+    "",
+  ].join("\n");
+}
+/** 이 MCP 를 띄울 때 깔았나("installed")·바꿨나("updated") — 그럼 이 Codex 세션은 아직 그 에이전트를 모른다 */
+let codexAgentFresh = null;
+function installCodexAgent() {
+  const toml = codexAgentToml();
+  const had = fs.existsSync(CODEX_AGENT_DEST);
+  if (had && fs.readFileSync(CODEX_AGENT_DEST, "utf8") === toml) return "same";
+  fs.mkdirSync(path.dirname(CODEX_AGENT_DEST), { recursive: true });
+  fs.writeFileSync(CODEX_AGENT_DEST, toml);
+  return had ? "updated" : "installed";
+}
+
 /** 방문자 에이전트를 ~/.claude/agents/ 에 둔다. "installed" | "updated" | "same" */
 function installAgent() {
   const moved = removeOldAgent();
@@ -300,15 +348,34 @@ function installAgent() {
   return had || moved ? "updated" : "installed";
 }
 
+server.registerTool(
+  "connect",
+  {
+    description:
+      "Connect Usercase to a project in the browser, or switch to another project. Opens the Usercase dashboard where the user signs in and picks the project. Other tools connect by themselves when nothing is connected — use this only when the user wants another project, or check_site says the SDK sends to a different project.",
+    inputSchema: {},
+  },
+  wrap(async () => text(await report.reconnect())),
+);
+
 server.registerTool(
   "setup",
   {
     description:
-      "Install the usercase-visitor sub-agent definition into ~/.claude/agents/ (user-wide, nothing is added to the repository) so visitors can be started. Run once if that agent type is not available. The user may need to restart Claude Code afterwards.",
+      "Install the visitor sub-agent definition (Claude Code: ~/.claude/agents/, Codex: ~/.codex/agents/ — user-wide, nothing is added to the repository) so visitors can be started. Run once if that agent type is not available. The user may need to restart Claude Code afterwards.",
     inputSchema: {},
   },
   wrap(async () => {
     if (PLUGIN) return text(`Nothing to install — the visitor agent comes with the Usercase plugin as ${VISITOR}.`);
+    if (CODEX) {
+      // 이 세션을 띄울 때 깔았거나 바꿨으면 이 세션의 Codex 는 아직 모른다 — 일반 하위 에이전트로 대신 띄우면 코드를 본다
+      const c = codexAgentFresh || installCodexAgent();
+      return text(
+        c === "same"
+          ? `Already up to date — ${CODEX_AGENT_DEST}`
+          : `${c === "updated" ? "Updated" : "Installed"} → ${CODEX_AGENT_DEST}\nThis agent can only use the three Usercase tools (open_visit, act, answer_card) and cannot read files or run commands.\nCodex reads agents only when a session starts, so ${VISITOR} is not available in this session. Stop here and ask the user to start a new Codex session (quit and run codex again) and run the command again. Never start visitors as a general sub-agent instead — it would see the code.`,
+      );
+    }
     const r = installAgent();
     return text(
       r === "same"
@@ -569,6 +636,15 @@ server.registerTool(
 
 // ── 가상 사용자 서브에이전트용 ──
 
+// Codex 는 도구마다 처음 부를 때 허용을 묻는다. 방문 도중에 물으면 그동안 첫 화면에 가만히 있던 사람이 된다(10/28 첫 행동 130초).
+// 그래서 진행자가 방문 전에 visit_id "warmup" 으로 한 번씩 불러 허용을 미리 받는다 — 아무 일도 하지 않는다
+const WARMUP = "warmup";
+const WARMUP_TEXT = "Permission check only — nothing happened.";
+const WARMUP_STEP =
+  'call `act` and `answer_card` yourself, once each, with `visit_id` "warmup" and any other arguments (they do nothing). Codex then asks the user to allow these tools now — otherwise it asks in the middle of a visit, and the visitor stands still on the page until the user answers. Tell the user to allow them for good.';
+const warmed = new Set();
+const warm = (tool) => (warmed.add(tool), text(WARMUP_TEXT));
+
 server.registerTool(
   "open_visit",
   {
@@ -597,7 +673,9 @@ server.registerTool(
       times: z.number().int().min(1).max(5).optional().describe("For scroll, scroll_up or click: how many times in a row, quickly (scrolling down while skimming, clicking again because nothing happened). Default 1"),
     },
   },
-  wrap(async ({ visit_id, action, index, text: typed = "", why, done = false, times = 1 }) => screen(await hub.act(visit_id, { action, index, text: typed, why, done, times }), visit_id)),
+  wrap(async ({ visit_id, action, index, text: typed = "", why, done = false, times = 1 }) =>
+    visit_id === WARMUP ? warm("act") : screen(await hub.act(visit_id, { action, index, text: typed, why, done, times }), visit_id),
+  ),
 );
 
 server.registerTool(
@@ -616,7 +694,9 @@ server.registerTool(
     },
   },
   wrap(async ({ visit_id, bothered, bothered_why, action, choice_index, other_text = "", why }) =>
-    screen(await hub.answer(visit_id, { bothered, botheredWhy: bothered_why, action, choiceIndex: choice_index, otherText: other_text, why }), visit_id),
+    visit_id === WARMUP
+      ? warm("answer_card")
+      : screen(await hub.answer(visit_id, { bothered, botheredWhy: bothered_why, action, choiceIndex: choice_index, otherText: other_text, why }), visit_id),
   ),
 );
 
@@ -637,7 +717,7 @@ function researchPlan(count) {
     line: unlimited ? `unlimited — rounds of ${ROUND} until the user stops` : `${n} in total, in rounds of ${ROUND}`,
     rounds: [
       `Work in rounds of ${ROUND} people, ${until}.`,
-      `- **Round 1:** cast ${ROUND}, show the user the list, and tell them you will keep casting new people like this ${unlimited ? "until they press Esc" : `until ${n} have visited`}, and that every visit uses their Claude usage. Wait for the go-ahead, then run the round (step 4).`,
+      `- **Round 1:** cast ${ROUND}, show the user the list, and tell them you will keep casting new people like this ${unlimited ? "until they press Esc" : `until ${n} have visited`}, and that every visit uses their ${CODEX ? "Codex" : "Claude"} usage. Wait for the go-ahead, then run the round (step 4).`,
       "- **Next rounds:** do not ask again. Call `list_people` first and cast people unlike the ones already there — different goals, arrival paths, devices and states of mind, not variations of the same person. Run the round, then tell the user one short line (round number, who went, visits so far) and go on.",
       "- After each round, `results` tells you whether the run is finished. Until it says so, start the next round — do not write the report.",
       "- Stop early only if the site blocks us, or visits keep failing the same way before they start.",
@@ -663,7 +743,7 @@ function runStatus() {
   const next = run.total === null ? ROUND : Math.min(ROUND, run.total - done);
   return [
     `▶ The run is not finished — ${done} visited so far (${left}).`,
-    `Do not write the report and do not look into the code. Tell the user one short line about this round, then: call list_people, cast ${next} new people unlike the ones already there with save_people, start one ${VISITOR} for each, and call results again when they finish.`,
+    `Do not write the report and do not look into the code. Tell the user one short line about this round, then: call list_people, cast ${next} new people unlike the ones already there with save_people, start one ${VISITOR}${SPAWN} for each, and call results again when they finish.`,
   ].join("\n");
 }
 
@@ -708,7 +788,13 @@ const COMMANDS = {
         .replace("{{count_line}}", plan.line)
         .replace("{{rounds}}", plan.rounds)
         .replace("{{people_rules}}", rules)
-        .replaceAll("{{visitor}}", VISITOR);
+        .replaceAll("{{visitor}}", VISITOR)
+        .replace("{{spawn}}", SPAWN)
+        .replace("{{agent}}", CODEX ? "Codex" : "Claude Code")
+        .replace(
+          "{{warmup}}\n",
+          CODEX ? `**Required before the first round:** ${WARMUP_STEP}\n\n` : "",
+        );
     },
   },
   install: {
@@ -730,9 +816,23 @@ const COMMANDS = {
   },
   // 인자를 두지 않는다 — Claude Code 는 명령어 인자를 공백으로 나눠 문장을 못 싣는다. 무엇을 물을지는 대화로 묻는다
   question: {
-    description: "Make a Usercase question for a precise moment on your site — Claude suggests the moment, question and answers",
+    description: "Make a Usercase question for a precise moment on your site — your agent suggests the moment, question and answers",
     body: () => agentDoc("question.md"),
   },
+  // 프로젝트 바꾸기 — 연결은 저장소 폴더마다라 이 저장소만 바뀐다
+  connect: {
+    description: "Connect this repository to a Usercase project, or switch it to another one",
+    body: () =>
+      [
+        "# Connect this repository to a Usercase project",
+        "",
+        "Call the `connect` tool. It opens the Usercase dashboard in the browser, where the user signs in and picks the project (or creates one). Tell the user what it returns.",
+        "",
+        "If it says it is not connected yet, the browser is waiting for the user: wait until they say they are done, then call `connect` again — it carries on with the same request.",
+        "",
+        "Only this repository's folder changes. Other repositories keep their own project. Until the new project is approved, the current connection stays.",
+      ].join("\n"),
+  },
   steps: {
     description: "Write the steps for the question open in your dashboard (New question → Several steps)",
     argsSchema: { session: z.string().optional().describe("The window id shown in the dashboard command") },
@@ -740,12 +840,12 @@ const COMMANDS = {
   },
 };
 
-if (PLUGIN) {
+if (PLUGIN || CODEX || OTHER) {
   server.registerTool(
     "instructions",
     {
       description:
-        "The step-by-step instructions for a Usercase command (research, install, path, question, steps). The plugin's /usercase:* commands call this; follow what it returns as the user's request.",
+        "The step-by-step instructions for a Usercase command (research, install, path, question, steps, connect). The plugin's /usercase:* commands call this; follow what it returns as the user's request.",
       inputSchema: {
         command: z.enum(Object.keys(COMMANDS)),
         ...COMMANDS.research.argsSchema,
@@ -766,8 +866,15 @@ async function main() {
   // 예전에 깐 방문자 에이전트가 있으면 이 버전 것으로 바꿔 둔다 — setup 은 처음 한 번만 불려서 옛 지시문이 남는다.
   // 리서치를 한 번도 안 쓴 사람에게는 만들지 않는다
   try {
-    if (!PLUGIN && (fs.existsSync(AGENT_DEST) || fs.existsSync(AGENT_OLD)) && installAgent() === "updated") process.stderr.write(`Updated the visitor agent → ${AGENT_DEST}\n`);
+    if (!PLUGIN && !CODEX && (fs.existsSync(AGENT_DEST) || fs.existsSync(AGENT_OLD)) && installAgent() === "updated") process.stderr.write(`Updated the visitor agent → ${AGENT_DEST}\n`);
+    // Codex 는 세션을 시작할 때만 에이전트를 읽는다(10/28 확인 — 세션 도중 깐 것은 unknown agent_type). 그래서 없어도 띄울 때 바로 깐다
+    if (CODEX) {
+      const c = installCodexAgent();
+      if (c !== "same") codexAgentFresh = c;
+      if (c !== "same") process.stderr.write(`${c === "updated" ? "Updated" : "Installed"} the visitor agent → ${CODEX_AGENT_DEST}\n`);
+    }
   } catch {}
+  server.server.oninitialized = () => report.setClient((server.server.getClientVersion() || {}).name);
   await server.connect(new StdioServerTransport());
   process.stderr.write(`Usercase MCP ready — working folder ${ws.DIR}${hub.inject ? ` · local SDK injected (${hub.inject.project})` : ""}\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.5",
+  "version": "0.2.6-next.0",
   "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",