deel-local-cli 1.12.0 → 1.13.0

package/src/backend/mcp.js

@@ -1,395 +1,407 @@
-/**
- * MCP(Model Context Protocol) 서버 붙이기 — stdio 규격.
- *
- * 무엇인가:
- *   도구를 **코드를 안 고치고** 밖에서 붙이는 규격이다. 사내 위키 검색기,
- *   사내 이슈 트래커, DB 조회기 같은 것을 각 팀이 MCP 서버로 만들어 두면
- *   deel 은 그걸 그대로 도구로 쓴다. 우리가 매번 도구를 새로 만들지 않아도 된다.
- *
- * 왜 의존성 없이 되나:
- *   stdio 규격은 자식 프로세스의 stdin/stdout 에 **줄 단위 JSON-RPC 2.0** 을
- *   주고받는 것이 전부다. child_process 와 JSON 이면 된다. SDK 가 필요 없다.
- *
- * ── 안전에 대해 ────────────────────────────────────────────────────────
- *
- * MCP 서버는 **남의 프로그램**이다. 이 프로젝트가 존재하는 이유가 '미승인 SW
- * 반입 금지' 인데, MCP 를 아무렇게나 켜면 그 선을 우리 손으로 무너뜨리는 셈이다.
- * 그래서:
- *
- *   1) **기본은 꺼져 있다.** .deel/mcp.json 에 사람이 직접 적어야만 뜬다.
- *   2) **--offline 이면 아예 안 띄운다.** 자식 프로세스가 어디로 나가는지
- *      우리는 못 막는다. 막을 수 없는 것을 막았다고 말하지 않는다.
- *   3) **감사기록에 남긴다.** 무엇을 띄웠고 무엇을 불렀는지.
- *   4) **작업 범위 밖이다.** MCP 서버는 우리 scope 를 안 지킨다 —
- *      제 마음대로 파일을 읽고 쓸 수 있다. /mcp 화면에서 그렇다고 말한다.
- */
-import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { VERSION } from '../version.js';
-
-// 붙는 데 이만큼 넘게 걸리면 포기한다. 시작이 느려지면 안 쓰게 된다.
-export const 붙기제한 = 8000;
-// 도구 하나 부르고 이만큼 기다린다.
-export const 부르기제한 = 60000;
-// 한 서버에서 받을 도구 수. 스키마가 통째로 매 요청에 실리므로 무한정 받으면
-// 컨텍스트가 조용히 줄어든다. 넘으면 **넘었다고 말하고** 자른다.
-export const 도구최대 = 24;
-// 한 줄(JSON 한 통)의 최대 크기. 미친 서버가 stdout 을 쏟아부어도 안 죽게.
-const 줄최대 = 4 * 1024 * 1024;
-
-export const 설정자리 = (root) => join(root, '.deel', 'mcp.json');
-
-/**
- * 설정을 읽는다. Claude Code 의 `mcpServers` 모양을 그대로 받는다 —
- * 이미 쓰던 설정을 복사해 붙일 수 있어야 한다.
- */
-export function 설정읽기(root) {
-  const p = 설정자리(root);
-  if (!existsSync(p)) return { 서버들: [], 자리: p, 있음: false };
-  let j;
-  try { j = JSON.parse(readFileSync(p, 'utf8')); } catch (e) {
-    return { 서버들: [], 자리: p, 있음: true, 오류: `mcp.json 을 못 읽었습니다: ${e.message}` };
-  }
-  const 표 = j.mcpServers ?? j.servers ?? {};
-  const 서버들 = [];
-  for (const [이름, v] of Object.entries(표)) {
-    if (v?.disabled === true) continue;
-    // stdio 만 받는다. http/sse 규격은 바깥으로 나가는 것이라 자물쇠와 부딪힌다.
-    if (v?.type && v.type !== 'stdio') continue;
-    if (!v?.command) continue;
-    서버들.push({
-      이름,
-      command: String(v.command),
-      args: Array.isArray(v.args) ? v.args.map(String) : [],
-      env: v.env && typeof v.env === 'object' ? v.env : null,
-      cwd: v.cwd ? String(v.cwd) : root,
-    });
-  }
-  return { 서버들, 자리: p, 있음: true };
-}
-
-/*
- * ── 지금 띄워 둔 서버들 ─────────────────────────────────────────────────
- *
- * 여기 왜 명부가 있나. MCP 서버는 붙인 쪽(repl·ACP)이 들고 있을 뿐이라,
- * 프로그램이 어느 길로든 끝나 버리면 **아무도 안 닫는다.** 그러면 사람
- * 컴퓨터에 서버 프로세스가 하나씩 쌓인다 — 작업 관리자를 열기 전에는
- * 모르는 종류의 탈이다.
- *
- * 일감(tools/jobs.js)과 언어 서버(lsp/client.js)에는 이미 이 그물이 있는데
- * 여기만 없었다. 같은 자리, 같은 규칙으로 둔다.
- */
-const 띄운것들 = new Set();
-
-/** 검사와 진단이 본다. 지금 살아 있는 서버 수. */
-export function 살아있는수() { return 띄운것들.size; }
-
-/**
- * 다 닫는다. 프로그램이 끝날 때와 검사 뒤에 부른다.
- * @returns {number} 닫은 개수
- */
-export function 모두닫기() {
-  const 것들 = [...띄운것들];
-  띄운것들.clear();
-  let n = 0;
-  for (const s of 것들) { try { s.닫기(); n++; } catch { /* 끝나는 중이라 할 수 있는 게 없다 */ } }
-  return n;
-}
-
-/*
- * 어떤 길로 끝나든 남기지 않는다. 붙인 쪽이 이미 닫았어도 무해하다.
- *
- * 이름 있는 함수를 그대로 건다 — 이름 없는 화살표로 걸면 그물이 걸려 있는지
- * 검사가 밖에서 확인할 길이 없다. 걷어내도 아무도 모르는 그물은 없는 것과 같다.
- */
-process.once('exit', 모두닫기);
-
-/**
- * 서버 하나와의 연결.
- *
- * 규격은 JSON-RPC 2.0 이다. 줄 하나에 통 하나 — 그래서 줄 단위로 자르면 된다.
- */
-export class MCP서버 {
-  constructor(설정) {
-    this.이름 = 설정.이름;
-    this.설정 = 설정;
-    this.kid = null;
-    this.다음번호 = 1;
-    this.기다리는것 = new Map();
-    this.찌꺼기 = '';
-    this.도구 = [];
-    this.정보 = null;
-    this.죽음 = null;      // 왜 죽었나 (사람에게 보여 줄 말)
-    this.잘림 = 0;         // 도구최대 를 넘어 자른 개수
-  }
-
-  살아있나() { return !!this.kid && this.kid.exitCode === null && !this.죽음; }
-
-  async 붙기({ timeout = 붙기제한 } = {}) {
-    try {
-      this.kid = spawn(this.설정.command, this.설정.args, {
-        cwd: this.설정.cwd,
-        // 설정에 적힌 env 만 얹는다. 우리 환경변수를 통째로 넘기면
-        // 게이트웨이 열쇠(DEEL_*)까지 남의 프로세스로 넘어간다.
-        env: { ...깨끗한환경(), ...(this.설정.env ?? {}) },
-        stdio: ['pipe', 'pipe', 'pipe'],
-        windowsHide: true,
-        shell: false,
-      });
-    } catch (e) {
-      this.죽음 = `띄우지 못했습니다: ${e.message}`;
-      return false;
-    }
-    // 띄운 순간부터 명부에 든다. 악수(initialize)를 못 마쳐도 아이는 이미
-    // 떠 있으므로, 여기서 안 적으면 그 아이는 아무도 안 거두는 아이가 된다.
-    띄운것들.add(this);
-
-    this.kid.on('error', (e) => this.끝냄(`오류: ${e.message}`));
-    this.kid.on('exit', (code, sig) => this.끝냄(`끝났습니다 (코드 ${code ?? sig})`));
-    this.kid.stdout.setEncoding('utf8');
-    this.kid.stdout.on('data', (d) => this.받음(d));
-    // 서버가 stderr 에 로그를 쏟는 일이 흔하다. 화면에 흘리면 대화가 뒤덮인다.
-    // 마지막 것만 들고 있다가 죽었을 때 원인으로 보여 준다.
-    this.kid.stderr.setEncoding('utf8');
-    this.kid.stderr.on('data', (d) => { this.마지막말 = String(d).trim().slice(-400); });
-
-    try {
-      const r = await this.보내고기다리기('initialize', {
-        protocolVersion: '2024-11-05',
-        capabilities: { tools: {} },
-        clientInfo: { name: 'deel', version: VERSION },
-      }, timeout);
-      this.정보 = r?.serverInfo ?? null;
-      this.알림('notifications/initialized', {});
-    } catch (e) {
-      this.끝냄(`규격 인사에 실패했습니다: ${e.message}`);
-      return false;
-    }
-
-    try {
-      const r = await this.보내고기다리기('tools/list', {}, timeout);
-      const 다 = Array.isArray(r?.tools) ? r.tools : [];
-      this.도구 = 다.slice(0, 도구최대);
-      this.잘림 = Math.max(0, 다.length - this.도구.length);
-    } catch (e) {
-      this.끝냄(`도구 목록을 못 받았습니다: ${e.message}`);
-      return false;
-    }
-    return true;
-  }
-
-  받음(덩이) {
-    this.찌꺼기 += 덩이;
-    if (this.찌꺼기.length > 줄최대) {
-      this.끝냄('한 통이 너무 큽니다 — 규격에 안 맞는 서버입니다');
-      return;
-    }
-    let i = this.찌꺼기.indexOf('\n');
-    while (i >= 0) {
-      const 줄 = this.찌꺼기.slice(0, i).trim();
-      this.찌꺼기 = this.찌꺼기.slice(i + 1);
-      if (줄) this.한통(줄);
-      i = this.찌꺼기.indexOf('\n');
-    }
-  }
-
-  한통(줄) {
-    let j;
-    try { j = JSON.parse(줄); } catch { return; }   // 규격 밖의 잡소리는 버린다
-    if (j.id == null) return;                        // 알림은 아직 안 쓴다
-    const 기다림 = this.기다리는것.get(j.id);
-    if (!기다림) return;
-    this.기다리는것.delete(j.id);
-    clearTimeout(기다림.타이머);
-    // 끝난 자리의 ESC 엿듣기는 떼어 낸다. 안 떼면 한 턴에 도구를 스무 번
-    // 부르는 사이 신호 하나에 스무 개가 매달린다 — 노드가 열 개 넘으면
-    // 「메모리가 새는 것 같다」 고 경고를 찍는데, 실제로 새는 것이 맞다.
-    기다림.끊기그만?.();
-    if (j.error) 기다림.실패(new Error(j.error.message ?? '알 수 없는 오류'));
-    else 기다림.성공(j.result);
-  }
-
-  /**
-   * 한 통 보내고 답을 기다린다.
-   *
-   * signal 은 사람이 누른 ESC 다. 안 받으면 도구 하나 부르는 데 최대 60초
-   * (부르기제한)를 기다리는데, 그 60초 동안 ESC 는 아무것도 안 한다 — 화면은
-   * 「멈추는 중…」 인데 남의 프로세스의 답을 계속 기다리고 있는 상태다.
-   * 그래서 시한과 같은 자리에서 같은 방식으로 푼다: 기다리는 표에서 빼고,
-   * 왜 끝났는지를 말로 남기고 끝낸다.
-   */
-  보내고기다리기(method, params, timeout = 부르기제한, signal = null) {
-    return new Promise((성공, 실패) => {
-      if (!this.kid || this.kid.exitCode !== null) return 실패(new Error(this.죽음 ?? '연결이 없습니다'));
-      // 이미 멈췄으면 보내지도 않는다. 보내 놓고 버리면 남의 서버는 그 일을 끝까지 한다.
-      if (signal?.aborted) return 실패(new Error('중단했습니다'));
-      const id = this.다음번호++;
-      const 타이머 = setTimeout(() => {
-        this.기다리는것.delete(id);
-        끊기그만();
-        실패(new Error(`${Math.round(timeout / 1000)}초 안에 답이 없습니다`));
-      }, timeout);
-      if (타이머.unref) 타이머.unref();
-      /*
-       * 기다리는 표에서 **반드시** 뺀다.
-       *
-       * 안 빼면 뒤늦게 온 답이 이미 끝난 약속을 또 푼다. 두 번째 풀기는
-       * 조용히 무시되므로 오류는 안 나지만, 표에 죽은 자리가 남아서
-       * 끝냄() 이 그것들을 다시 실패시킨다 — 아무도 안 듣는 실패다.
-       */
-      const 끊겼다 = () => {
-        clearTimeout(타이머);
-        this.기다리는것.delete(id);
-        실패(new Error('중단했습니다'));
-      };
-      signal?.addEventListener?.('abort', 끊겼다, { once: true });
-      const 끊기그만 = () => signal?.removeEventListener?.('abort', 끊겼다);
-      this.기다리는것.set(id, { 성공, 실패, 타이머, 끊기그만 });
-      try {
-        this.kid.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
-      } catch (e) {
-        clearTimeout(타이머);
-        this.기다리는것.delete(id);
-        끊기그만();
-        실패(e);
-      }
-    });
-  }
-
-  알림(method, params) {
-    try { this.kid?.stdin?.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'); } catch { /* 죽었으면 어차피 끝이다 */ }
-  }
-
-  async 부르기(도구이름, args, { timeout = 부르기제한, signal = null } = {}) {
-    const r = await this.보내고기다리기('tools/call', { name: 도구이름, arguments: args ?? {} }, timeout, signal);
-    // 규격상 결과는 content 배열이다. 글만 뽑아 모델에게 넘긴다.
-    const 조각 = Array.isArray(r?.content) ? r.content : [];
-    const 글 = 조각
-      .map((p) => (p?.type === 'text' ? p.text : p?.type ? `[${p.type}]` : ''))
-      .filter(Boolean).join('\n');
-    return { text: 글, isError: r?.isError === true };
-  }
-
-  끝냄(왜) {
-    if (this.죽음) return;
-    this.죽음 = this.마지막말 ? `${왜} — ${this.마지막말}` : 왜;
-    for (const [, 기다림] of this.기다리는것) {
-      clearTimeout(기다림.타이머);
-      기다림.끊기그만?.();
-      기다림.실패(new Error(this.죽음));
-    }
-    this.기다리는것.clear();
-  }
-
-  닫기() {
-    this.끝냄('닫았습니다');
-    띄운것들.delete(this);
-    try {
-      this.kid?.stdin?.end();
-      this.kid?.kill();
-      // 자식이 살아 있으면 우리 프로그램이 안 끝난다.
-      this.kid?.unref?.();
-    } catch { /* 이미 죽었다 */ }
-  }
-}
-
-/**
- * 우리 환경변수를 통째로 넘기지 않는다.
- *
- * DEEL_* 에는 게이트웨이 열쇠가 들어 있을 수 있고, 그 값이 남의 프로세스로
- * 넘어가면 어디로 가는지 우리가 알 수 없다. 프로그램이 도는 데 꼭 필요한
- * 것만 남긴다.
- */
-function 깨끗한환경() {
-  const 남길것 = ['PATH', 'Path', 'PATHEXT', 'HOME', 'USERPROFILE', 'TEMP', 'TMP', 'SystemRoot', 'windir', 'COMSPEC', 'LANG', 'LC_ALL', 'APPDATA', 'LOCALAPPDATA', 'ProgramFiles', 'ProgramData', 'NODE_PATH'];
-  const out = {};
-  for (const k of 남길것) if (process.env[k] != null) out[k] = process.env[k];
-  return out;
-}
-
-/**
- * 게이트웨이 열쇠 **하나만** 뺀 환경. Bash 와 Jobs 가 자식에게 넘길 것.
- *
- * 위 깨끗한환경 은 남의 프로그램(MCP 서버)에 주는 것이라 통째로 씻는다.
- * 여기는 다르다 — Bash 로 도는 것은 **사용자 제 프로젝트**다. PATH·NODE_ENV·
- * DEEL_HOME·사내 프록시 설정이 다 있어야 하고(사용자는 이 프로그램의 검사
- * 자체를 Bash 로 돌린다), 하나라도 빠지면 「내 터미널에서는 되는데」 가 된다.
- *
- * 그래서 딱 하나만 뺀다. 안 빼면 `env` 한 줄로 열쇠가 화면에 찍히고, 그 화면이
- * 대화에 실려 게이트웨이로 나가고 `.deel/sessions/*.jsonl` 로 디스크에도 남는다 —
- * 열쇠를 그 열쇠의 주인에게 보내는 셈이다(guard.js 가 막는 것과 같은 길).
- * 자식이 무엇을 하든 이 값이 필요할 일은 없다. 게이트웨이로 나가는 것은 우리다.
- */
-export function 열쇠뺀환경(env = process.env) {
-  const out = { ...env };
-  delete out.DEEL_API_KEY;
-  return out;
-}
-
-/** 우리 도구 이름과 안 부딪히게 앞에 서버 이름을 붙인다. Claude Code 와 같은 꼴이다. */
-export const 도구이름 = (서버, 도구) => `mcp__${서버}__${도구}`;
-
-/** 붙인 이름에서 서버와 도구를 도로 뗀다. */
-export function 이름풀기(전체) {
-  const m = /^mcp__([^_]+(?:_[^_]+)*?)__(.+)$/.exec(String(전체 ?? ''));
-  return m ? { 서버: m[1], 도구: m[2] } : null;
-}
-
-/**
- * 설정에 적힌 서버를 전부 띄운다.
- *
- * 하나가 안 떠도 나머지는 쓴다 — 서버 하나 때문에 프로그램이 못 뜨면 안 된다.
- * 안 뜬 것은 **안 떴다고 말한다.** 조용히 빠지면 "왜 그 도구가 없지" 를
- * 영영 알 수 없다.
- */
-export async function 다붙이기(root, { offline = false, timeout = 붙기제한, audit = null } = {}) {
-  const 설정 = 설정읽기(root);
-  if (설정.오류) return { 서버들: [], 못한것: [{ 이름: '(설정)', 왜: 설정.오류 }], 설정 };
-  if (!설정.서버들.length) return { 서버들: [], 못한것: [], 설정 };
-
-  // 자물쇠가 걸려 있으면 아예 안 띄운다. 자식 프로세스가 어디로 나가는지
-  // 우리는 못 막는다 — 막을 수 없는 것을 막았다고 말하지 않는다.
-  if (offline) {
-    return {
-      서버들: [],
-      못한것: 설정.서버들.map((s) => ({ 이름: s.이름, 왜: '오프라인 잠금 중에는 안 띄웁니다' })),
-      설정,
-      잠김: true,
-    };
-  }
-
-  const 붙은것 = [];
-  const 못한것 = [];
-  await Promise.all(설정.서버들.map(async (s) => {
-    const 서버 = new MCP서버(s);
-    const ok = await 서버.붙기({ timeout });
-    if (ok) {
-      붙은것.push(서버);
-      audit?.write?.('mcp', { 이름: s.이름, command: s.command, 도구: 서버.도구.length });
-    } else {
-      못한것.push({ 이름: s.이름, 왜: 서버.죽음 ?? '알 수 없는 이유' });
-      서버.닫기();
-    }
-  }));
-  붙은것.sort((a, b) => a.이름.localeCompare(b.이름));
-  return { 서버들: 붙은것, 못한것, 설정 };
-}
-
-/** 모델에게 넘길 도구 정의로 바꾼다. */
-export function 도구정의(서버들) {
-  const out = [];
-  for (const s of 서버들) {
-    for (const t of s.도구) {
-      out.push({
-        type: 'function',
-        function: {
-          name: 도구이름(s.이름, t.name),
-          description: `[${s.이름}] ${t.description ?? t.name}`,
-          parameters: t.inputSchema ?? { type: 'object', properties: {} },
-        },
-      });
-    }
-  }
-  return out;
-}
+/**
+ * MCP(Model Context Protocol) 서버 붙이기 — stdio 규격.
+ *
+ * 무엇인가:
+ *   도구를 **코드를 안 고치고** 밖에서 붙이는 규격이다. 사내 위키 검색기,
+ *   사내 이슈 트래커, DB 조회기 같은 것을 각 팀이 MCP 서버로 만들어 두면
+ *   deel 은 그걸 그대로 도구로 쓴다. 우리가 매번 도구를 새로 만들지 않아도 된다.
+ *
+ * 왜 의존성 없이 되나:
+ *   stdio 규격은 자식 프로세스의 stdin/stdout 에 **줄 단위 JSON-RPC 2.0** 을
+ *   주고받는 것이 전부다. child_process 와 JSON 이면 된다. SDK 가 필요 없다.
+ *
+ * ── 안전에 대해 ────────────────────────────────────────────────────────
+ *
+ * MCP 서버는 **남의 프로그램**이다. 이 프로젝트가 존재하는 이유가 '미승인 SW
+ * 반입 금지' 인데, MCP 를 아무렇게나 켜면 그 선을 우리 손으로 무너뜨리는 셈이다.
+ * 그래서:
+ *
+ *   1) **기본은 꺼져 있다.** .deel/mcp.json 에 사람이 직접 적어야만 뜬다.
+ *   2) **--offline 이면 아예 안 띄운다.** 자식 프로세스가 어디로 나가는지
+ *      우리는 못 막는다. 막을 수 없는 것을 막았다고 말하지 않는다.
+ *   3) **감사기록에 남긴다.** 무엇을 띄웠고 무엇을 불렀는지.
+ *   4) **작업 범위 밖이다.** MCP 서버는 우리 scope 를 안 지킨다 —
+ *      제 마음대로 파일을 읽고 쓸 수 있다. /mcp 화면에서 그렇다고 말한다.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { VERSION } from '../version.js';
+import { 열쇠환경인가 } from '../config.js';
+
+// 붙는 데 이만큼 넘게 걸리면 포기한다. 시작이 느려지면 안 쓰게 된다.
+export const 붙기제한 = 8000;
+// 도구 하나 부르고 이만큼 기다린다.
+export const 부르기제한 = 60000;
+// 한 서버에서 받을 도구 수. 스키마가 통째로 매 요청에 실리므로 무한정 받으면
+// 컨텍스트가 조용히 줄어든다. 넘으면 **넘었다고 말하고** 자른다.
+export const 도구최대 = 24;
+// 한 줄(JSON 한 통)의 최대 크기. 미친 서버가 stdout 을 쏟아부어도 안 죽게.
+const 줄최대 = 4 * 1024 * 1024;
+
+export const 설정자리 = (root) => join(root, '.deel', 'mcp.json');
+
+/**
+ * 설정을 읽는다. Claude Code 의 `mcpServers` 모양을 그대로 받는다 —
+ * 이미 쓰던 설정을 복사해 붙일 수 있어야 한다.
+ */
+export function 설정읽기(root) {
+  const p = 설정자리(root);
+  if (!existsSync(p)) return { 서버들: [], 자리: p, 있음: false };
+  let j;
+  try { j = JSON.parse(readFileSync(p, 'utf8')); } catch (e) {
+    return { 서버들: [], 자리: p, 있음: true, 오류: `mcp.json 을 못 읽었습니다: ${e.message}` };
+  }
+  const 표 = j.mcpServers ?? j.servers ?? {};
+  const 서버들 = [];
+  for (const [이름, v] of Object.entries(표)) {
+    if (v?.disabled === true) continue;
+    // stdio 만 받는다. http/sse 규격은 바깥으로 나가는 것이라 자물쇠와 부딪힌다.
+    if (v?.type && v.type !== 'stdio') continue;
+    if (!v?.command) continue;
+    서버들.push({
+      이름,
+      command: String(v.command),
+      args: Array.isArray(v.args) ? v.args.map(String) : [],
+      env: v.env && typeof v.env === 'object' ? v.env : null,
+      cwd: v.cwd ? String(v.cwd) : root,
+    });
+  }
+  return { 서버들, 자리: p, 있음: true };
+}
+
+/*
+ * ── 지금 띄워 둔 서버들 ─────────────────────────────────────────────────
+ *
+ * 여기 왜 명부가 있나. MCP 서버는 붙인 쪽(repl·ACP)이 들고 있을 뿐이라,
+ * 프로그램이 어느 길로든 끝나 버리면 **아무도 안 닫는다.** 그러면 사람
+ * 컴퓨터에 서버 프로세스가 하나씩 쌓인다 — 작업 관리자를 열기 전에는
+ * 모르는 종류의 탈이다.
+ *
+ * 일감(tools/jobs.js)과 언어 서버(lsp/client.js)에는 이미 이 그물이 있는데
+ * 여기만 없었다. 같은 자리, 같은 규칙으로 둔다.
+ */
+const 띄운것들 = new Set();
+
+/** 검사와 진단이 본다. 지금 살아 있는 서버 수. */
+export function 살아있는수() { return 띄운것들.size; }
+
+/**
+ * 다 닫는다. 프로그램이 끝날 때와 검사 뒤에 부른다.
+ * @returns {number} 닫은 개수
+ */
+export function 모두닫기() {
+  const 것들 = [...띄운것들];
+  띄운것들.clear();
+  let n = 0;
+  for (const s of 것들) { try { s.닫기(); n++; } catch { /* 끝나는 중이라 할 수 있는 게 없다 */ } }
+  return n;
+}
+
+/*
+ * 어떤 길로 끝나든 남기지 않는다. 붙인 쪽이 이미 닫았어도 무해하다.
+ *
+ * 이름 있는 함수를 그대로 건다 — 이름 없는 화살표로 걸면 그물이 걸려 있는지
+ * 검사가 밖에서 확인할 길이 없다. 걷어내도 아무도 모르는 그물은 없는 것과 같다.
+ */
+process.once('exit', 모두닫기);
+
+/**
+ * 서버 하나와의 연결.
+ *
+ * 규격은 JSON-RPC 2.0 이다. 줄 하나에 통 하나 — 그래서 줄 단위로 자르면 된다.
+ */
+export class MCP서버 {
+  constructor(설정) {
+    this.이름 = 설정.이름;
+    this.설정 = 설정;
+    this.kid = null;
+    this.다음번호 = 1;
+    this.기다리는것 = new Map();
+    this.찌꺼기 = '';
+    this.도구 = [];
+    this.정보 = null;
+    this.죽음 = null;      // 왜 죽었나 (사람에게 보여 줄 말)
+    this.잘림 = 0;         // 도구최대 를 넘어 자른 개수
+  }
+
+  살아있나() { return !!this.kid && this.kid.exitCode === null && !this.죽음; }
+
+  async 붙기({ timeout = 붙기제한 } = {}) {
+    try {
+      this.kid = spawn(this.설정.command, this.설정.args, {
+        cwd: this.설정.cwd,
+        // 설정에 적힌 env 만 얹는다. 우리 환경변수를 통째로 넘기면
+        // 게이트웨이 열쇠(DEEL_*)까지 남의 프로세스로 넘어간다.
+        env: { ...깨끗한환경(), ...(this.설정.env ?? {}) },
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+        shell: false,
+      });
+    } catch (e) {
+      this.죽음 = `띄우지 못했습니다: ${e.message}`;
+      return false;
+    }
+    // 띄운 순간부터 명부에 든다. 악수(initialize)를 못 마쳐도 아이는 이미
+    // 떠 있으므로, 여기서 안 적으면 그 아이는 아무도 안 거두는 아이가 된다.
+    띄운것들.add(this);
+
+    this.kid.on('error', (e) => this.끝냄(`오류: ${e.message}`));
+    this.kid.on('exit', (code, sig) => this.끝냄(`끝났습니다 (코드 ${code ?? sig})`));
+    this.kid.stdout.setEncoding('utf8');
+    this.kid.stdout.on('data', (d) => this.받음(d));
+    // 서버가 stderr 에 로그를 쏟는 일이 흔하다. 화면에 흘리면 대화가 뒤덮인다.
+    // 마지막 것만 들고 있다가 죽었을 때 원인으로 보여 준다.
+    this.kid.stderr.setEncoding('utf8');
+    this.kid.stderr.on('data', (d) => { this.마지막말 = String(d).trim().slice(-400); });
+
+    try {
+      const r = await this.보내고기다리기('initialize', {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        clientInfo: { name: 'deel', version: VERSION },
+      }, timeout);
+      this.정보 = r?.serverInfo ?? null;
+      this.알림('notifications/initialized', {});
+    } catch (e) {
+      this.끝냄(`규격 인사에 실패했습니다: ${e.message}`);
+      return false;
+    }
+
+    try {
+      const r = await this.보내고기다리기('tools/list', {}, timeout);
+      const 다 = Array.isArray(r?.tools) ? r.tools : [];
+      this.도구 = 다.slice(0, 도구최대);
+      this.잘림 = Math.max(0, 다.length - this.도구.length);
+    } catch (e) {
+      this.끝냄(`도구 목록을 못 받았습니다: ${e.message}`);
+      return false;
+    }
+    return true;
+  }
+
+  받음(덩이) {
+    this.찌꺼기 += 덩이;
+    if (this.찌꺼기.length > 줄최대) {
+      this.끝냄('한 통이 너무 큽니다 — 규격에 안 맞는 서버입니다');
+      return;
+    }
+    let i = this.찌꺼기.indexOf('\n');
+    while (i >= 0) {
+      const 줄 = this.찌꺼기.slice(0, i).trim();
+      this.찌꺼기 = this.찌꺼기.slice(i + 1);
+      if (줄) this.한통(줄);
+      i = this.찌꺼기.indexOf('\n');
+    }
+  }
+
+  한통(줄) {
+    let j;
+    try { j = JSON.parse(줄); } catch { return; }   // 규격 밖의 잡소리는 버린다
+    if (j.id == null) return;                        // 알림은 아직 안 쓴다
+    const 기다림 = this.기다리는것.get(j.id);
+    if (!기다림) return;
+    this.기다리는것.delete(j.id);
+    clearTimeout(기다림.타이머);
+    // 끝난 자리의 ESC 엿듣기는 떼어 낸다. 안 떼면 한 턴에 도구를 스무 번
+    // 부르는 사이 신호 하나에 스무 개가 매달린다 — 노드가 열 개 넘으면
+    // 「메모리가 새는 것 같다」 고 경고를 찍는데, 실제로 새는 것이 맞다.
+    기다림.끊기그만?.();
+    if (j.error) 기다림.실패(new Error(j.error.message ?? '알 수 없는 오류'));
+    else 기다림.성공(j.result);
+  }
+
+  /**
+   * 한 통 보내고 답을 기다린다.
+   *
+   * signal 은 사람이 누른 ESC 다. 안 받으면 도구 하나 부르는 데 최대 60초
+   * (부르기제한)를 기다리는데, 그 60초 동안 ESC 는 아무것도 안 한다 — 화면은
+   * 「멈추는 중…」 인데 남의 프로세스의 답을 계속 기다리고 있는 상태다.
+   * 그래서 시한과 같은 자리에서 같은 방식으로 푼다: 기다리는 표에서 빼고,
+   * 왜 끝났는지를 말로 남기고 끝낸다.
+   */
+  보내고기다리기(method, params, timeout = 부르기제한, signal = null) {
+    return new Promise((성공, 실패) => {
+      if (!this.kid || this.kid.exitCode !== null) return 실패(new Error(this.죽음 ?? '연결이 없습니다'));
+      // 이미 멈췄으면 보내지도 않는다. 보내 놓고 버리면 남의 서버는 그 일을 끝까지 한다.
+      if (signal?.aborted) return 실패(new Error('중단했습니다'));
+      const id = this.다음번호++;
+      const 타이머 = setTimeout(() => {
+        this.기다리는것.delete(id);
+        끊기그만();
+        실패(new Error(`${Math.round(timeout / 1000)}초 안에 답이 없습니다`));
+      }, timeout);
+      if (타이머.unref) 타이머.unref();
+      /*
+       * 기다리는 표에서 **반드시** 뺀다.
+       *
+       * 안 빼면 뒤늦게 온 답이 이미 끝난 약속을 또 푼다. 두 번째 풀기는
+       * 조용히 무시되므로 오류는 안 나지만, 표에 죽은 자리가 남아서
+       * 끝냄() 이 그것들을 다시 실패시킨다 — 아무도 안 듣는 실패다.
+       */
+      const 끊겼다 = () => {
+        clearTimeout(타이머);
+        this.기다리는것.delete(id);
+        실패(new Error('중단했습니다'));
+      };
+      signal?.addEventListener?.('abort', 끊겼다, { once: true });
+      const 끊기그만 = () => signal?.removeEventListener?.('abort', 끊겼다);
+      this.기다리는것.set(id, { 성공, 실패, 타이머, 끊기그만 });
+      try {
+        this.kid.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+      } catch (e) {
+        clearTimeout(타이머);
+        this.기다리는것.delete(id);
+        끊기그만();
+        실패(e);
+      }
+    });
+  }
+
+  알림(method, params) {
+    try { this.kid?.stdin?.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'); } catch { /* 죽었으면 어차피 끝이다 */ }
+  }
+
+  async 부르기(도구이름, args, { timeout = 부르기제한, signal = null } = {}) {
+    const r = await this.보내고기다리기('tools/call', { name: 도구이름, arguments: args ?? {} }, timeout, signal);
+    // 규격상 결과는 content 배열이다. 글만 뽑아 모델에게 넘긴다.
+    const 조각 = Array.isArray(r?.content) ? r.content : [];
+    const 글 = 조각
+      .map((p) => (p?.type === 'text' ? p.text : p?.type ? `[${p.type}]` : ''))
+      .filter(Boolean).join('\n');
+    return { text: 글, isError: r?.isError === true };
+  }
+
+  끝냄(왜) {
+    if (this.죽음) return;
+    this.죽음 = this.마지막말 ? `${왜} — ${this.마지막말}` : 왜;
+    for (const [, 기다림] of this.기다리는것) {
+      clearTimeout(기다림.타이머);
+      기다림.끊기그만?.();
+      기다림.실패(new Error(this.죽음));
+    }
+    this.기다리는것.clear();
+  }
+
+  닫기() {
+    this.끝냄('닫았습니다');
+    띄운것들.delete(this);
+    try {
+      this.kid?.stdin?.end();
+      this.kid?.kill();
+      // 자식이 살아 있으면 우리 프로그램이 안 끝난다.
+      this.kid?.unref?.();
+    } catch { /* 이미 죽었다 */ }
+  }
+}
+
+/**
+ * 우리 환경변수를 통째로 넘기지 않는다.
+ *
+ * DEEL_* 에는 게이트웨이 열쇠가 들어 있을 수 있고, 그 값이 남의 프로세스로
+ * 넘어가면 어디로 가는지 우리가 알 수 없다. 프로그램이 도는 데 꼭 필요한
+ * 것만 남긴다.
+ */
+export function 깨끗한환경() {
+  const 남길것 = ['PATH', 'Path', 'PATHEXT', 'HOME', 'USERPROFILE', 'TEMP', 'TMP', 'SystemRoot', 'windir', 'COMSPEC', 'LANG', 'LC_ALL', 'APPDATA', 'LOCALAPPDATA', 'ProgramFiles', 'ProgramData', 'NODE_PATH'];
+  const out = {};
+  for (const k of 남길것) if (process.env[k] != null) out[k] = process.env[k];
+  return out;
+}
+
+/**
+ * 게이트웨이 열쇠**만** 뺀 환경. Bash 와 Jobs 가 자식에게 넘길 것.
+ *
+ * 위 깨끗한환경 은 남의 프로그램(MCP 서버)에 주는 것이라 통째로 씻는다.
+ * 여기는 다르다 — Bash 로 도는 것은 **사용자 제 프로젝트**다. PATH·NODE_ENV·
+ * DEEL_HOME·사내 프록시 설정이 다 있어야 하고(사용자는 이 프로그램의 검사
+ * 자체를 Bash 로 돌린다), 하나라도 빠지면 「내 터미널에서는 되는데」 가 된다.
+ *
+ * 그래서 딱 하나만 뺀다. 안 빼면 `env` 한 줄로 열쇠가 화면에 찍히고, 그 화면이
+ * 대화에 실려 게이트웨이로 나가고 `.deel/sessions/*.jsonl` 로 디스크에도 남는다 —
+ * 열쇠를 그 열쇠의 주인에게 보내는 셈이다(guard.js 가 막는 것과 같은 길).
+ * 자식이 무엇을 하든 이 값이 필요할 일은 없다. 게이트웨이로 나가는 것은 우리다.
+ */
+export function 열쇠뺀환경(env = process.env) {
+  const out = { ...env };
+  /*
+   * 이름을 못 박지 않는다.
+   *
+   * 여기가 `delete out.DEEL_API_KEY` 한 줄이었다. 열쇠 이름은 **둘**인데
+   * (config.js 의 resolveKey), 그중 하나만 지운 것이다. 프로필 열쇠
+   * (`DEEL_KEY_PROD`)를 쓰는 사람은 `env` 한 줄로 그대로 샜다 — 그리고
+   * 그 방법을 우리 심사 명세가 권장으로 적어 뒀다.
+   *
+   * 무엇이 열쇠인지는 **읽는 자에게 묻는다**(열쇠환경인가). 이름이 늘면
+   * 거기만 고친다. 여기서 다시 적으면 반드시 한쪽이 낡는다.
+   */
+  for (const k of Object.keys(out)) if (열쇠환경인가(k)) delete out[k];
+  return out;
+}
+
+/** 우리 도구 이름과 안 부딪히게 앞에 서버 이름을 붙인다. Claude Code 와 같은 꼴이다. */
+export const 도구이름 = (서버, 도구) => `mcp__${서버}__${도구}`;
+
+/** 붙인 이름에서 서버와 도구를 도로 뗀다. */
+export function 이름풀기(전체) {
+  const m = /^mcp__([^_]+(?:_[^_]+)*?)__(.+)$/.exec(String(전체 ?? ''));
+  return m ? { 서버: m[1], 도구: m[2] } : null;
+}
+
+/**
+ * 설정에 적힌 서버를 전부 띄운다.
+ *
+ * 하나가 안 떠도 나머지는 쓴다 — 서버 하나 때문에 프로그램이 못 뜨면 안 된다.
+ * 안 뜬 것은 **안 떴다고 말한다.** 조용히 빠지면 "왜 그 도구가 없지" 를
+ * 영영 알 수 없다.
+ */
+export async function 다붙이기(root, { offline = false, timeout = 붙기제한, audit = null } = {}) {
+  const 설정 = 설정읽기(root);
+  if (설정.오류) return { 서버들: [], 못한것: [{ 이름: '(설정)', 왜: 설정.오류 }], 설정 };
+  if (!설정.서버들.length) return { 서버들: [], 못한것: [], 설정 };
+
+  // 자물쇠가 걸려 있으면 아예 안 띄운다. 자식 프로세스가 어디로 나가는지
+  // 우리는 못 막는다 — 막을 수 없는 것을 막았다고 말하지 않는다.
+  if (offline) {
+    return {
+      서버들: [],
+      못한것: 설정.서버들.map((s) => ({ 이름: s.이름, 왜: '오프라인 잠금 중에는 안 띄웁니다' })),
+      설정,
+      잠김: true,
+    };
+  }
+
+  const 붙은것 = [];
+  const 못한것 = [];
+  await Promise.all(설정.서버들.map(async (s) => {
+    const 서버 = new MCP서버(s);
+    const ok = await 서버.붙기({ timeout });
+    if (ok) {
+      붙은것.push(서버);
+      audit?.write?.('mcp', { 이름: s.이름, command: s.command, 도구: 서버.도구.length });
+    } else {
+      못한것.push({ 이름: s.이름, 왜: 서버.죽음 ?? '알 수 없는 이유' });
+      서버.닫기();
+    }
+  }));
+  붙은것.sort((a, b) => a.이름.localeCompare(b.이름));
+  return { 서버들: 붙은것, 못한것, 설정 };
+}
+
+/** 모델에게 넘길 도구 정의로 바꾼다. */
+export function 도구정의(서버들) {
+  const out = [];
+  for (const s of 서버들) {
+    for (const t of s.도구) {
+      out.push({
+        type: 'function',
+        function: {
+          name: 도구이름(s.이름, t.name),
+          description: `[${s.이름}] ${t.description ?? t.name}`,
+          parameters: t.inputSchema ?? { type: 'object', properties: {} },
+        },
+      });
+    }
+  }
+  return out;
+}