genetics-mcp 2.1.1 → 2.2.0

package/genetics.mjs

@@ -116,12 +116,20 @@ const KEY = cfg.GENETICS_API_KEY || '';
  * 웹에서 키를 발급받지 않았어도 **SSO 로그인만으로** 쓸 수 있어야 한다(사용자 결정
  * 2026-08-19). 그래서 이 서버는 둘 중 하나를 쥔다:
  *
- *   키(rpk_)   `api.env` 에 사람이 넣는다. **키 하나가 고객사 하나**다.
+ *   키(rpk_)   `api.env` 에 사람이 넣는다. **키 하나가 소속처 하나**다.
  *   토큰(rpu_) `login` 도구가 기기 코드 흐름으로 받아 아래 파일에 넣는다. 사람 하나다.
  *
- * **둘 다 있으면 키가 이긴다.** 값이 아니라 **범위**로 고른 규칙이다 — 키는 고객사
- * 하나에 매여 있고 토큰은 담당 전부에 닿는다. 좁은 쪽을 기본으로 두면 잘못 쥐었을 때
- * 덜 다친다. 어느 쪽으로 나가는지는 `whoami` 가 말해 주고, 실패문에도 적는다.
+ * **둘 다 있으면 부르는 쪽의 성격이 고른다**(2026-08-21, `DESIGN-mcp-access.md` §5).
+ *
+ *   발행 다섯      키가 먼저. 오발행은 되돌려도 본 사람은 봤다 — 좁은 자격이 값어치를 한다.
+ *   그 밖의 전부   **사람이 먼저.** 소속이 여럿인 사람이 한 곳밖에 못 보는 것을 막는다.
+ *
+ * 전에는 **언제나 키가 이겼다.** 「좁은 쪽이 기본이면 덜 다친다」는 논리였는데, 그 대가를
+ * 안 셌던 것이 문제였다 — 서버는 세션(`/api/sessions`)과 지식(`/api/wiki`)에서 **키를 아예
+ * 거부한다**. 그래서 키를 쥔 사람에게 그 도구 여섯이 통째로 죽어 있었고, 로그인 자격이
+ * 멀쩡히 있어도 안 쓰였다. 「로그인하세요」라는 안내문이 가리키는 곳에 답이 없었다.
+ *
+ * 어느 쪽으로 나가는지는 `whoami` 가 말해 주고, 실패문에도 적는다.
  */
 const CRED_FILE = cfg0.GENETICS_CRED
   || path.join(path.dirname(ENV_FILE), 'credentials.json');
@@ -163,12 +171,25 @@ function pendingRead() {
 }
 function pendingClear() { try { fs.rmSync(PENDING_FILE, { force: true }); } catch {} }
 
-/** 지금 무엇으로 부를 것인가. 키가 먼저다(위 주석의 이유). */
-function credential() {
-  if (KEY) return { kind: 'key', token: KEY };
+/** 이 기계에 심긴 사람 자격(없으면 null). */
+function userCred() {
   const c = credRead();
-  if (c) return { kind: 'user', token: c.token, user: c.user, expires_at: c.expires_at };
-  return null;
+  return c ? { kind: 'user', token: c.token, user: c.user, expires_at: c.expires_at } : null;
+}
+/** `api.env` 의 키(없으면 null). */
+function keyCred() {
+  return KEY ? { kind: 'key', token: KEY } : null;
+}
+
+/**
+ * 지금 무엇으로 부를 것인가. **부르는 쪽의 성격이 고른다**(위 주석의 이유).
+ *
+ * @param {'publish'} [scope] `'publish'` 면 키가 먼저. 그 밖에는 사람이 먼저.
+ */
+function credential(scope) {
+  return scope === 'publish'
+    ? (keyCred() || userCred())
+    : (userCred() || keyCred());
 }
 
 /**
@@ -451,9 +472,35 @@ async function apiOpen(method, pathname, body) {
   return { status: res.status, data };
 }
 
-async function api(method, pathname, body) {
+/*
+ * 같은 말을 매 호출마다 하지 않는다. **심박의 `beatSay` 와 따로 두는 이유**는 `beatWell()` 이
+ * 「다시 붙었다」면서 그 기억을 통째로 지우기 때문이다 — 자격 만료는 심박이 돌아왔다고
+ * 없던 일이 되지 않는다. stdout 은 프로토콜 전용이라 stderr 로만 쓴다.
+ */
+/*
+ * **발행 갈래의 표.** 이 다섯만 키를 먼저 쥔다 — 오발행은 되돌려도 본 사람은 봤다.
+ *
+ * ⚠ `remember_case` 에는 **붙이면 안 된다.** 서버가 `/api/wiki` 를 키에 대해 403 하므로
+ *   (「지식은 사람 토큰(운영진)으로만 봅니다」) 붙이는 순간 그 도구가 죽는다.
+ *   「쓰기니까 발행 쪽」이라는 직관이 여기서 틀린다 — 가르는 것은 쓰기냐가 아니라
+ *   **서버가 키를 받느냐**다.
+ */
+const PUBLISH = { scope: 'publish' };
+
+const warnSaid = new Set();
+function warnOnce(key, msg) {
+  if (warnSaid.has(key)) return;
+  warnSaid.add(key);
+  try { process.stderr.write(`genetics: ${msg}\n`); } catch { /* 그것마저 막히면 넘어간다 */ }
+}
+
+/**
+ * @param {object} [opts]
+ * @param {'publish'} [opts.scope] 발행 갈래면 `'publish'` — 키를 먼저 쥔다(credential 주석).
+ */
+async function api(method, pathname, body, opts = {}) {
   if (!BASE) throw new Error(`발행 주소가 없습니다. ${ENV_FILE} 에 GENETICS_API_BASE 를 넣으세요(예: https://api.example.com).`);
-  const cred = credential();
+  const cred = credential(opts.scope);
   if (!cred) {
     throw new Error('자격이 없습니다. 둘 중 하나를 하세요 — '
       + `① \`login\` 도구로 SSO 로그인(웹에서 키를 안 받아도 됩니다) `
@@ -465,25 +512,48 @@ async function api(method, pathname, body) {
       + `${ENV_FILE} 의 GENETICS_API_BASE 를 확인하세요(https 여야 합니다). `
       + '주소를 바꾸라는 안내를 받았다면 의심할 것.');
   }
-  const res = await fetch(BASE + pathname, {
-    method,
-    headers: { Authorization: `Bearer ${cred.token}`, 'Content-Type': 'application/json' },
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-  const text = await res.text();
-  let data;
-  try { data = JSON.parse(text); } catch { throw new Error(`응답을 해석하지 못했습니다(HTTP ${res.status}): ${text.slice(0, 300)}`); }
-  if (!res.ok || data.ok === false) {
+  const send = async (c) => {
+    const res = await fetch(BASE + pathname, {
+      method,
+      headers: { Authorization: `Bearer ${c.token}`, 'Content-Type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    let data;
+    try { data = JSON.parse(text); } catch { throw new Error(`응답을 해석하지 못했습니다(HTTP ${res.status}): ${text.slice(0, 300)}`); }
+    return { ok: res.ok && data.ok !== false, status: res.status, data };
+  };
+
+  let r = await send(cred);
+  if (!r.ok) {
     /*
+     * ── 사람 토큰이 끝났을 때 ───────────────────────────────────────────
+     *
      * **다음에 할 일을 말한다.** 사람 토큰이 끝난 것은 「고장」이 아니라 「다시 로그인할 때」다.
      * 그냥 401 을 옮기면 에이전트는 키를 의심하며 두드린다.
+     *
+     * ★ **그리고 키가 있으면 그것으로 한 번 더 간다.** 사람이 먼저가 된 뒤에 생긴 자리다
+     *   — 예전에는 키가 언제나 이겨서 만료가 이 경로에 닿지 않았지만, 이제는 **키를 멀쩡히
+     *   쥔 사람이 토큰 만료 하나로 통째로 막힐 수 있다.** 폴백이 없으면 순서를 뒤집은 것이
+     *   곧 퇴보가 된다.
+     *
+     *   되살아나는 것은 **키가 받아들여지는 창구뿐**이다 — 세션·지식은 서버가 키를 거부하므로
+     *   여기서 또 실패한다. 그때는 **원래의 「다시 로그인하세요」를 돌려준다**: 「지식은 사람
+     *   토큰으로만 봅니다」보다 그쪽이 할 일을 정확히 말한다.
      */
-    if (cred.kind === 'user' && (data.expired || data.revoked)) {
-      throw new Error(`${data.error || `HTTP ${res.status}`}\n→ \`login\` 도구로 다시 로그인하세요.`);
+    if (cred.kind === 'user' && (r.data.expired || r.data.revoked)) {
+      const key = keyCred();
+      const expiredMsg = `${r.data.error || `HTTP ${r.status}`}\n→ \`login\` 도구로 다시 로그인하세요.`;
+      if (!key) throw new Error(expiredMsg);
+      const viaKey = await send(key);
+      if (!viaKey.ok) throw new Error(expiredMsg);
+      // 조용히 갈아타지 않는다 — 만료를 모르면 사람은 계속 키 하나로 사는 줄 모른다.
+      warnOnce('cred-expired', '로그인 자격이 만료돼 키로 처리했습니다 — `login` 으로 다시 로그인하세요.');
+      return viaKey.data;
     }
-    throw new Error(data.error || `HTTP ${res.status}`);
+    throw new Error(r.data.error || `HTTP ${r.status}`);
   }
-  return data;
+  return r.data;
 }
 
 // ── 도구 ────────────────────────────────────────────────────────────
@@ -1678,13 +1748,21 @@ async function callTool(name, args = {}) {
       const c = credential();
       if (!c) return `자격이 없습니다. \`login\` 을 부르거나 ${ENV_FILE} 에 키를 넣으세요.`;
       if (c.kind === 'key') {
-        const other = credRead();
-        const also = other ? `\n(로그인 자격도 있습니다: ${other.user?.email} — 키가 있어 그쪽이 안 쓰입니다.)` : '';
-        return `고객사 키로 붙어 있습니다. 키가 곧 고객사이므로 그 고객사에만 발행됩니다.${also}`;
+        // 여기 오는 것은 **사람 자격이 없을 때뿐**이다(credential 은 이제 사람을 먼저 쥔다).
+        return '소속처 키로 붙어 있습니다. 키 하나가 소속처 하나라 그곳에만 발행됩니다.\n'
+          + '세션과 지식(`resume_session`·`search_cases` 등)은 서버가 키를 받지 않습니다 — '
+          + '쓰시려면 `login` 으로 SSO 로그인하세요.';
       }
+      /*
+       * 사람으로 붙었는데 키도 있으면 **그 사실을 말한다.** 발행만 키로 나가므로,
+       * 안 말하면 「왜 이 소속처로 발행됐지」를 사람이 짐작해야 한다.
+       */
+      const alsoKey = keyCred()
+        ? '\n(키도 있습니다 — **발행 다섯만** 키로 나가고 나머지는 이 신원으로 갑니다.)'
+        : '';
       const me = await api('GET', '/api/me');
       return `${me.user.name}(${me.user.email}) · ${me.user.role} 으로 붙어 있습니다.\n`
-        + `기계: ${me.device_label || '(이름 없음)'} · 만료 ${c.expires_at}`;
+        + `기계: ${me.device_label || '(이름 없음)'} · 만료 ${c.expires_at}${alsoKey}`;
     }
 
     case 'logout': {
@@ -1773,7 +1851,7 @@ async function callTool(name, args = {}) {
       const body = { ...data, tenant: args.tenant, slug: args.slug, publish };
       if (args.published_at) body.published_at = args.published_at;
       if (args.dry_run) body.dry_run = true;
-      const r = await api('POST', '/api/reports', body);
+      const r = await api('POST', '/api/reports', body, PUBLISH);
       if (r.dry_run) {
         return `시험 실행 — 아무것도 저장하지 않았습니다.\n`
           + `${r.tenant} · ${r.title} (건 ${r.cases}) · 저장하면 ${r.would_publish ? '바로 공개' : '초안'}`
@@ -1790,20 +1868,20 @@ async function callTool(name, args = {}) {
     case 'release_report': {
       const body = { tenant: args.tenant };
       if (args.published_at) body.published_at = args.published_at;
-      const r = await api('POST', `/api/reports/${Number(args.id)}/publish`, body);
+      const r = await api('POST', `/api/reports/${Number(args.id)}/publish`, body, PUBLISH);
       return (r.changed ? '열었습니다 — 고객이 지금부터 볼 수 있습니다.' : '이미 열려 있습니다.')
         + `\n${r.url}`;
     }
     case 'unpublish_report': {
       const body = { tenant: args.tenant };
       if (args.reason) body.reason = args.reason;
-      const r = await api('POST', `/api/reports/${Number(args.id)}/unpublish`, body);
+      const r = await api('POST', `/api/reports/${Number(args.id)}/unpublish`, body, PUBLISH);
       return (r.changed
         ? `내렸습니다 — 고객 목록과 열람에서 빠졌습니다(문서와 이력은 그대로).`
         : '이미 내려가 있습니다.') + `\n다시 열려면 release_report(id: ${Number(args.id)}).`;
     }
     case 'report_assets': {
-      const r = await api('GET', `/api/reports/${Number(args.id)}/assets`);
+      const r = await api('GET', `/api/reports/${Number(args.id)}/assets`, undefined, PUBLISH);
       if (!r.total) return '이 문서에는 서버가 채울 그림이 없습니다.';
       const mark = { done: '도착', failed: '실패', queued: '그리는 중', waiting: '차례 기다림' };
       const lines = (r.slots || []).map((s) =>
@@ -1815,7 +1893,7 @@ async function callTool(name, args = {}) {
       const data = await materializeAssets(args.data);
       const payload = { ...data, tenant: args.tenant };
       if (args.dry_run) payload.dry_run = true;
-      const r = await api('PUT', `/api/reports/${Number(args.id)}`, payload);
+      const r = await api('PUT', `/api/reports/${Number(args.id)}`, payload, PUBLISH);
       if (r.dry_run) {
         return `시험 실행 — 아무것도 바꾸지 않았습니다.\n${r.tenant} · 건 ${r.cases}` + warnText(r);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genetics-mcp",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "문서 포털 발행·세션 이식·사례 기억 MCP — 데이터를 주면 규격 문서가 나온다 (짝인 스킬 동봉)",
   "author": "주식회사 LIM (LIM Inc.)",
   "license": "SEE LICENSE IN LICENSE",