@usercase/mcp 0.2.4-next.8 → 0.2.5-next.0

package/agents/install.md

@@ -23,4 +23,4 @@ If the site is running locally (or the user can start it), call `check_site` wit
 ## 4. Tell the user what's next
 
 - Real visitors are recorded once this change is **deployed**. The dashboard's setup screen ticks itself off when the live site sends its first visit.
-- They don't have to wait for real visitors: offer to send a few virtual users now with the `research` prompt (`/mcp__usercase__research <url> 3`).
+- They don't have to wait for real visitors: offer to send a few virtual users now with the `research` prompt (`{{research_cmd}} <url> 3`).

package/agents/research.md

@@ -88,7 +88,7 @@ The goal is still the person's own reason for coming, in their words — never "
 
 ## 4. Send the visitors
 
-For each person, start an `usercase-visitor` sub-agent with a prompt like:
+For each person, start a `{{visitor}}` sub-agent with a prompt like:
 
 > Call open_visit with person "<id>" and live this visit as that person until you leave.
 

package/mcp/report.js

@@ -18,6 +18,14 @@ const KEY_RE = /^eb_sk_[A-Za-z0-9]{32}$/;
 const OUTBOX = path.join(ws.DIR, "outbox.jsonl");
 
 const apiKey = () => (process.env[KEY_ENV] || "").trim();
+// 플러그인이면 키는 플러그인 설정에 있다(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" : ""}`;
 const apiBase = () => (process.env[URL_ENV] || DEFAULT_API).replace(/\/$/, "");
 
 /** 이 MCP 세션 하나 = 실행 하나. 대시보드가 실행별로 묶는다 */
@@ -58,8 +66,8 @@ async function describeKey(sdkProject) {
 /** 키의 프로젝트와 그 설치 스크립트(서버가 대시보드 설치 화면과 같은 글을 준다) — install_snippet 이 쓴다 */
 async function getInstall() {
   const key = apiKey();
-  if (!key) throw new Error(`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>`);
-  if (!KEY_RE.test(key)) throw new Error(`${KEY_ENV} does not look right (38 characters starting with eb_sk_). Copy it again from the dashboard`);
+  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");
@@ -188,8 +196,8 @@ async function sendDiagnostics(events, device, shots = []) {
 /** 키가 있어야 하는 호출 — 없거나 틀렸으면 사용자에게 할 말로 바꿔 던진다 */
 async function keyed(method, route, body, timeoutMs) {
   const key = apiKey();
-  if (!key) throw new Error(`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>`);
-  if (!KEY_RE.test(key)) throw new Error(`${KEY_ENV} does not look right (38 characters starting with eb_sk_). Copy it again from the dashboard`);
+  if (!key) throw new Error(NO_KEY());
+  if (!KEY_RE.test(key)) throw new Error(BAD_KEY());
   try {
     return await call(method, route, body, timeoutMs);
   } catch (e) {

package/mcp/server.js

@@ -28,6 +28,13 @@ const { PathRecorder } = require("./path.js");
 const hub = new Hub();
 const server = new McpServer({ name: "usercase", version: require("../package.json").version });
 
+// Claude Code 플러그인(plugin/)으로 떴는지. 플러그인의 .mcp.json 이 USERCASE_PLUGIN=1 을 준다.
+// 플러그인에서는 방문자 에이전트가 플러그인에 들어 있어 이름이 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}`);
+
 const text = (t) => ({ content: [{ type: "text", text: String(t) }] });
 /** 방문 화면 + 그 화면의 이름 없는 아이콘 그림(있으면). 방문자는 그림을 보고 모양으로 안다 */
 const screen = (t, visitId) => {
@@ -301,6 +308,7 @@ server.registerTool(
     inputSchema: {},
   },
   wrap(async () => {
+    if (PLUGIN) return text(`Nothing to install — the visitor agent comes with the Usercase plugin as ${VISITOR}.`);
     const r = installAgent();
     return text(
       r === "same"
@@ -655,105 +663,110 @@ 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 usercase-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} for each, and call results again when they finish.`,
   ].join("\n");
 }
 
-server.registerPrompt(
-  "research",
-  {
-    description: "Research this site with Usercase virtual users",
-    argsSchema: {
-      url: z.string().optional(),
-      count: z.string().optional().describe('How many people (default 5), or "unlimited" to keep going until you stop it'),
-      focus: z.string().optional().describe("Only people who come for this part of the site, e.g. calendar, or comments and sharing"),
-    },
-  },
-  ({ url, count, focus }) => {
-    const plan = researchPlan(count);
-    run = { total: plan.total, since: Date.now() };
-    // 사람 만드는 규칙은 우리 AI 로 만들 때와 같은 원본(people.md)에서 가져온다 — 두 벌로 두지 않는다.
-    // 자유 탐방이라 원본이 말하는 "path" 는 "자기 목적으로 왔다" 뿐이다
-    const rules =
-      "(Here the \"path\" is simply: came to the site with something of their own to find out.)\n\n" +
-      fs
-        .readFileSync(path.join(__dirname, "..", "src", "prompts", "people.md"), "utf8")
-        .replace(/\r\n/g, "\n")
-        .replace(/^# Role:.*\n+/, "")
-        .replace(/^#/gm, "###");
-    // focus 가 있으면 그 기능에 올 사람만 — 바뀌는 단계만 따로 적은 글을 앞에 붙인다. 방문자는 모른다
-    const f = (focus || "").trim();
-    const focusPart = f
-      ? fs.readFileSync(path.join(__dirname, "..", "agents", "focus.md"), "utf8").replace(/\r\n/g, "\n").replaceAll("{{focus}}", f).trim() + "\n\n"
-      : "";
-    const body = fs
-      .readFileSync(path.join(__dirname, "..", "agents", "research.md"), "utf8")
-      .replace("{{focus}}\n", focusPart)
-      .replace("{{url}}", url || "(ask the user)")
-      .replace("{{count_line}}", plan.line)
-      .replace("{{rounds}}", plan.rounds)
-      .replace("{{people_rules}}", rules);
-    return { messages: [{ role: "user", content: { type: "text", text: body } }] };
-  },
-);
-
-server.registerPrompt(
-  "install",
-  { description: "Install the Usercase script on this site from its repository", argsSchema: { url: z.string().optional() } },
-  ({ url }) => {
-    const body = fs
-      .readFileSync(path.join(__dirname, "..", "agents", "install.md"), "utf8")
-      .replace(/\r\n/g, "\n")
-      .replace("{{url}}", url || "(the site in this repository)");
-    return { messages: [{ role: "user", content: { type: "text", text: body } }] };
-  },
-);
-
-server.registerPrompt(
-  "path",
-  {
-    description: "Record the expected path of a Usercase research's tasks",
-    // 대시보드 과제 화면의 명령은 과제 id 를 붙인다 — 그 과제만, 경로가 있어도 다시
-    argsSchema: { research: z.string().optional(), task: z.string().optional() },
-  },
-  ({ research, task }) => {
-    const body = fs
-      .readFileSync(path.join(__dirname, "..", "agents", "path.md"), "utf8")
-      .replace(/\r\n/g, "\n")
-      .replace("{{research}}", research || "(ask the user — the dashboard shows it)")
-      .replace("{{task}}", task ? `Task: ${task} — record this task only, and record it again even if it already has a path.` : "Task: all tasks of the research");
-    return { messages: [{ role: "user", content: { type: "text", text: body } }] };
-  },
-);
-
-/** 조건 쓰는 규칙은 question·steps 가 같이 쓴다 — 한 벌만 둔다 */
-const agentDoc = (name, vars = {}) => {
-  let body = fs.readFileSync(path.join(__dirname, "..", "agents", name), "utf8").replace(/\r\n/g, "\n");
-  const rules = fs.readFileSync(path.join(__dirname, "..", "agents", "condition.md"), "utf8").replace(/\r\n/g, "\n").trim();
-  body = body.replace("{{condition_rules}}", rules);
-  for (const [k, v] of Object.entries(vars)) body = body.replace(`{{${k}}}`, v);
-  return { messages: [{ role: "user", content: { type: "text", text: body } }] };
-};
-
-// 인자를 두지 않는다 — Claude Code 는 명령어 인자를 공백으로 나눠 문장을 못 싣는다. 무엇을 물을지는 대화로 묻는다
-server.registerPrompt("question", { description: "Make a Usercase question for a precise moment on your site — Claude suggests the moment, question and answers" }, () =>
-  agentDoc("question.md"),
-);
-
-server.registerPrompt(
-  "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") },
-  },
-  ({ session }) => agentDoc("steps.md", { session: session || "(missing — ask the user to copy the command from the dashboard)" }),
-);
-
+const doc = (name) => fs.readFileSync(path.join(__dirname, "..", "agents", name), "utf8").replace(/\r\n/g, "\n");
+/** 조건 쓰는 규칙은 question·steps 가 같이 쓴다 — 한 벌만 둔다 */
+const agentDoc = (name, vars = {}) => {
+  let body = doc(name).replace("{{condition_rules}}", doc("condition.md").trim());
+  for (const [k, v] of Object.entries(vars)) body = body.replace(`{{${k}}}`, v);
+  return body;
+};
+
+/**
+ * 명령 지시문. 따로 쓰면 MCP 프롬프트(/mcp__usercase__research), 플러그인이면 instructions 도구(/usercase:research 스킬이 부른다)로
+ * 같은 글이 나간다
+ */
+const COMMANDS = {
+  research: {
+    description: "Research this site with Usercase virtual users",
+    argsSchema: {
+      url: z.string().optional(),
+      count: z.string().optional().describe('How many people (default 5), or "unlimited" to keep going until you stop it'),
+      focus: z.string().optional().describe("Only people who come for this part of the site, e.g. calendar, or comments and sharing"),
+    },
+    body: ({ url, count, focus }) => {
+      const plan = researchPlan(count);
+      run = { total: plan.total, since: Date.now() };
+      // 사람 만드는 규칙은 우리 AI 로 만들 때와 같은 원본(people.md)에서 가져온다 — 두 벌로 두지 않는다.
+      // 자유 탐방이라 원본이 말하는 "path" 는 "자기 목적으로 왔다" 뿐이다
+      const rules =
+        "(Here the \"path\" is simply: came to the site with something of their own to find out.)\n\n" +
+        fs
+          .readFileSync(path.join(__dirname, "..", "src", "prompts", "people.md"), "utf8")
+          .replace(/\r\n/g, "\n")
+          .replace(/^# Role:.*\n+/, "")
+          .replace(/^#/gm, "###");
+      // focus 가 있으면 그 기능에 올 사람만 — 바뀌는 단계만 따로 적은 글을 앞에 붙인다. 방문자는 모른다
+      const f = (focus || "").trim();
+      const focusPart = f ? doc("focus.md").replaceAll("{{focus}}", f).trim() + "\n\n" : "";
+      return doc("research.md")
+        .replace("{{focus}}\n", focusPart)
+        .replace("{{url}}", url || "(ask the user)")
+        .replace("{{count_line}}", plan.line)
+        .replace("{{rounds}}", plan.rounds)
+        .replace("{{people_rules}}", rules)
+        .replaceAll("{{visitor}}", VISITOR);
+    },
+  },
+  install: {
+    description: "Install the Usercase script on this site from its repository",
+    argsSchema: { url: z.string().optional() },
+    body: ({ url }) =>
+      doc("install.md")
+        .replace("{{url}}", url || "(the site in this repository)")
+        .replace("{{research_cmd}}", cmd("research")),
+  },
+  path: {
+    description: "Record the expected path of a Usercase research's tasks",
+    // 대시보드 과제 화면의 명령은 과제 id 를 붙인다 — 그 과제만, 경로가 있어도 다시
+    argsSchema: { research: z.string().optional(), task: z.string().optional() },
+    body: ({ research, task }) =>
+      doc("path.md")
+        .replace("{{research}}", research || "(ask the user — the dashboard shows it)")
+        .replace("{{task}}", task ? `Task: ${task} — record this task only, and record it again even if it already has a path.` : "Task: all tasks of the research"),
+  },
+  // 인자를 두지 않는다 — Claude Code 는 명령어 인자를 공백으로 나눠 문장을 못 싣는다. 무엇을 물을지는 대화로 묻는다
+  question: {
+    description: "Make a Usercase question for a precise moment on your site — Claude suggests the moment, question and answers",
+    body: () => agentDoc("question.md"),
+  },
+  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") },
+    body: ({ session }) => agentDoc("steps.md", { session: session || "(missing — ask the user to copy the command from the dashboard)" }),
+  },
+};
+
+if (PLUGIN) {
+  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.",
+      inputSchema: {
+        command: z.enum(Object.keys(COMMANDS)),
+        ...COMMANDS.research.argsSchema,
+        ...COMMANDS.path.argsSchema,
+        ...COMMANDS.steps.argsSchema,
+      },
+    },
+    wrap(async ({ command, ...args }) => text(COMMANDS[command].body(args))),
+  );
+} else {
+  for (const [name, c] of Object.entries(COMMANDS)) {
+    const meta = c.argsSchema ? { description: c.description, argsSchema: c.argsSchema } : { description: c.description };
+    server.registerPrompt(name, meta, (args = {}) => ({ messages: [{ role: "user", content: { type: "text", text: c.body(args) } }] }));
+  }
+}
+
 async function main() {
   // 예전에 깐 방문자 에이전트가 있으면 이 버전 것으로 바꿔 둔다 — setup 은 처음 한 번만 불려서 옛 지시문이 남는다.
   // 리서치를 한 번도 안 쓴 사람에게는 만들지 않는다
   try {
-    if ((fs.existsSync(AGENT_DEST) || fs.existsSync(AGENT_OLD)) && installAgent() === "updated") process.stderr.write(`Updated the visitor agent → ${AGENT_DEST}\n`);
+    if (!PLUGIN && (fs.existsSync(AGENT_DEST) || fs.existsSync(AGENT_OLD)) && installAgent() === "updated") process.stderr.write(`Updated the visitor agent → ${AGENT_DEST}\n`);
   } catch {}
   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.4-next.8",
+  "version": "0.2.5-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",