cdsa-harness 0.4.0 → 0.6.0

package/README.md

@@ -9,10 +9,12 @@
 ```
 
 - **의존성 0개** — Node 18+ 내장 기능만(`fetch`/`readline`/`node:test`)
+- **실시간 스트리밍** — 모델 응답이 토큰 단위로 흐름(`/stream` 토글, OpenAI·Claude·mock)
 - **실제 LLM 연결** — OpenAI · Anthropic(Claude) · OpenRouter, 또는 키 없이 `mock`
 - **교육 모드** — 매 반복마다 모델에 보내는 메시지 구성·추정 토큰·시스템 프롬프트, 실제 토큰 사용량/응답시간까지 그대로 표시
-- **플러그인** — `.cdsa/plugins/` 에 JS 파일을 두면 **새 도구가 자동 등록**되어 모델이 사용
-- **스킬** — `.cdsa/skills/` 에 마크다운을 두면 `/이름` 으로 부르는 **프롬프트 템플릿**
+- **MCP 클라이언트** — Claude Code·Cursor 등과 **공용 표준**. MCP 서버를 그대로 붙여 도구로 사용
+- **플러그인** — npm 으로 설치하거나 `.cdsa/plugins/` 에 JS 파일 → **도구 자동 등록**
+- **크로스포맷 스킬** — `.cdsa/skills/` 뿐 아니라 `.claude/commands/`·`.opencode/command/` 의 스킬도 인식
 
 ---
 
@@ -52,6 +54,7 @@ export OPENROUTER_API_KEY=sk-or-...
 | `/provider <이름>` | openai · anthropic · openrouter · mock 전환 |
 | `/model <이름>` | 모델 변경 |
 | `/teach` | 교육 모드 켜기/끄기 |
+| `/stream` | 실시간 스트리밍 출력 켜기/끄기 |
 | `/context` | 지금 모델에 보내는 컨텍스트 들여다보기 |
 | `/reset` | 대화/컨텍스트 초기화 |
 | `/config` | 현재 설정값 |
@@ -108,10 +111,27 @@ export default {
 };
 ```
 
+## 🔗 MCP — 다른 에이전트와 플러그인 공유
+
+[MCP](https://modelcontextprotocol.io) 서버는 Claude Code·Cursor·Zed 등이 함께 쓰는 **공용 도구 표준**입니다.
+`config.json` 에 **그 도구들과 동일한 형식**으로 적으면, 다른 에이전트용으로 만든 MCP 서버를 cdsa-harness 에서 그대로 씁니다.
+
+```json
+{
+  "mcpServers": {
+    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] },
+    "github":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "..." } }
+  }
+}
+```
+
+연결되면 각 도구가 `mcp__서버__도구` 이름으로 모델에 노출됩니다. `/mcp` 로 확인.
+(부수효과가 있을 수 있는 도구는 실행 전 승인을 받습니다 — `readOnlyHint` 가 있으면 자동.)
+
 ## 🎯 스킬 (프롬프트 템플릿)
 
-`.cdsa/skills/` 또는 `~/.cdsa_harness/skills/` 에 마크다운을 두면 `/파일명` 으로 실행됩니다.
-본문의 `$ARGUMENTS` 는 명령 뒤 텍스트로 치환됩니다. `/skills` 로 목록 확인.
+`.cdsa/skills/` 에 마크다운을 두면 `/파일명` 으로 실행됩니다. 본문의 `$ARGUMENTS`(또는 `{{args}}`)가 치환됩니다.
+**다른 에이전트의 스킬도 인식** — `.claude/commands/`, `.claude/skills/<이름>/SKILL.md`, `.opencode/command/` 등을 함께 읽습니다. `/skills` 로 목록 확인.
 
 ```markdown
 ---
@@ -165,6 +185,9 @@ node-cli/
 │   ├── llm.js            # OpenAI/Anthropic/OpenRouter + mock, 응답 정규화(토큰·지연)
 │   ├── tools.js          # 도구 + sandbox + diff
 │   ├── loop.js           # ⭐ Agent Loop + 교육용 이벤트(컨텍스트/되먹임)
+│   ├── mcp.js            # MCP 클라이언트(stdio JSON-RPC) — 다른 에이전트와 공용
+│   ├── plugins.js        # 파일·npm 플러그인 발견/로드
+│   ├── skills.js         # 크로스포맷 스킬 로더
 │   ├── session.js        # 세션 로그(JSONL)
 │   ├── banner.js / ui.js # 배너 · ANSI/박스/diff 렌더
 │   └── cli.js            # REPL + 교육 모드 렌더 + /setup

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdsa-harness",
-  "version": "0.4.0",
-  "description": "AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 터미널 하네스. OpenAI/Claude/OpenRouter + npm 으로 설치하는 플러그인(추가 도구)·스킬 확장.",
+  "version": "0.6.0",
+  "description": "AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 터미널 하네스. 실시간 스트리밍 + OpenAI/Claude/OpenRouter + MCP + npm 플러그인·크로스포맷 스킬.",
   "type": "module",
   "bin": {
     "cdsa-harness": "bin/cdsa-harness.js",

package/src/cli.js

@@ -17,6 +17,7 @@ import { execFileSync } from "node:child_process";
 
 import { AgentLoop, Step } from "./loop.js";
 import { LLMClient } from "./llm.js";
+import { connectMcpServers } from "./mcp.js";
 import { discoverNpmExtensions, loadPlugins } from "./plugins.js";
 import { SessionLog, sessionsDir } from "./session.js";
 import { loadSkills, renderSkill } from "./skills.js";
@@ -45,15 +46,24 @@ function clip(s, n) {
 }
 
 // cfg.teach_mode 를 실행 중 토글할 수 있으므로 closure 로 cfg 를 잡아둔다.
-function makePrinter(cfg) {
+// stream.active 는 onToken 과 공유하는 스트리밍 상태.
+function makePrinter(cfg, stream) {
   return (ev) => {
-    if (cfg.teach_mode) return printTeach(ev);
-    return printCompact(ev);
+    if (cfg.teach_mode) return printTeach(ev, stream);
+    return printCompact(ev, stream);
   };
 }
 
+function replyMetaLine(d) {
+  const meta = [];
+  if (d.latencyMs != null) meta.push(`응답 ${d.latencyMs}ms`);
+  if (d.usage) meta.push(`토큰 입력 ${d.usage.input ?? "?"}/출력 ${d.usage.output ?? "?"}/합계 ${d.usage.total ?? "?"}`);
+  if (d.request?.bodyBytes) meta.push(`요청 ${d.request.bodyBytes}B`);
+  return meta.length ? meta.join(" · ") : "";
+}
+
 // ---- 교육(teach) 렌더: 내부 과정을 패널로 펼쳐 보여준다 ----
-function printTeach(ev) {
+function printTeach(ev, stream) {
   const d = ev.data || {};
   switch (ev.step) {
     case Step.USER_INPUT:
@@ -84,16 +94,26 @@ function printTeach(ev) {
     }
 
     case Step.MODEL_REPLY: {
+      // 스트리밍으로 이미 본문이 출력된 경우: 줄바꿈 후 메타/도구호출만 덧붙인다.
+      if (d.streamed) {
+        if (stream && stream.active) {
+          process.stdout.write("\n");
+          stream.active = false;
+        }
+        for (const tc of d.toolCalls || []) {
+          console.log(c.yellow(`  ↳ 도구 호출 요청: ${c.bold(tc.name)}(${clip(JSON.stringify(tc.args), 200)})`));
+        }
+        const meta = replyMetaLine(d);
+        if (meta) console.log(c.grey("  ─ " + meta));
+        return;
+      }
       const lines = [];
       if (ev.detail && ev.detail !== "(텍스트 없음)") lines.push(...clip(ev.detail, 1200).split("\n"));
       for (const tc of d.toolCalls || []) {
         lines.push(c.yellow(`↳ 도구 호출 요청: ${c.bold(tc.name)}(${clip(JSON.stringify(tc.args), 200)})`));
       }
-      const meta = [];
-      if (d.latencyMs != null) meta.push(`응답 ${d.latencyMs}ms`);
-      if (d.usage) meta.push(`토큰 입력 ${d.usage.input ?? "?"}/출력 ${d.usage.output ?? "?"}/합계 ${d.usage.total ?? "?"}`);
-      if (d.request?.bodyBytes) meta.push(`요청 ${d.request.bodyBytes}B`);
-      if (meta.length) lines.push(c.grey("─ " + meta.join(" · ")));
+      const meta = replyMetaLine(d);
+      if (meta) lines.push(c.grey("─ " + meta));
       else lines.push(c.dim("(mock: 토큰/지연 측정 없음)"));
       console.log(panel(lines.length ? lines : ["(빈 응답)"], { title: "🤖 ③ 모델 응답 (원본 판단)", color: "green" }));
       return;
@@ -131,11 +151,17 @@ function printTeach(ev) {
 }
 
 // ---- 간결(compact) 렌더: 한 줄 위주 ----
-function printCompact(ev) {
+function printCompact(ev, stream) {
   const [icon, color] = STEP_STYLE[ev.step] || ["•", "cyan"];
   const paint = c[color] || ((x) => x);
   if (ev.step === Step.APPROVAL && !ev.title.includes("자동 승인")) return;
   if (ev.step === Step.MODEL_REPLY) {
+    const d = ev.data || {};
+    if (d.streamed) {
+      if (stream && stream.active) { process.stdout.write("\n"); stream.active = false; }
+      for (const tc of d.toolCalls || []) console.log(c.yellow(`  ↳ ${tc.name}(${clip(JSON.stringify(tc.args), 120)})`));
+      return;
+    }
     if (ev.detail && ev.detail !== "(텍스트 없음)") console.log(panel(ev.detail.split("\n"), { title: "🤖 모델", color: "green" }));
     return;
   }
@@ -148,7 +174,7 @@ function printCompact(ev) {
   console.log(line);
 }
 
-function makeApproval(rl) {
+function makeApproval(ask) {
   return async (req) => {
     if (req.toolName === "write_file") {
       console.log(panel(renderDiff(req.diff || "(변경 미리보기 없음)"), {
@@ -160,12 +186,8 @@ function makeApproval(rl) {
     } else {
       console.log(panel([JSON.stringify(req.args)], { title: `🔐 ${req.toolLabel}`, color: "yellow" }));
     }
-    let ans = "";
-    try {
-      ans = (await rl.question(c.yellow("이 작업을 승인하시겠습니까? [y/N] "))).trim().toLowerCase();
-    } catch {
-      ans = "";
-    }
+    const raw = await ask(c.yellow("이 작업을 승인하시겠습니까? [y/N] "));
+    const ans = (raw || "").trim().toLowerCase();
     const approved = ans === "y" || ans === "yes";
     return { approved, reason: approved ? "" : "사용자가 거부했습니다." };
   };
@@ -192,6 +214,7 @@ function printIntro(cfg) {
     ["model", cfg.model],
     ["API 키", keySource],
     ["교육 모드", cfg.teach_mode ? c.green("ON (과정 펼쳐보기)") : "OFF"],
+    ["스트리밍", cfg.stream ? c.green("ON (실시간)") : "OFF"],
     ["작업 폴더", cfg.workspacePath()],
     ["승인 모드", cfg.approval_mode],
     ["셸 실행", cfg.allow_shell ? "허용" : "차단"],
@@ -216,9 +239,11 @@ function printHelp() {
         `  ${c.cyan("/provider")} <openai|anthropic|openrouter|mock> 제공자 변경`,
         `  ${c.cyan("/model")} <이름>   모델 변경`,
         `  ${c.cyan("/teach")}    교육 모드 켜기/끄기(내부 과정 펼쳐보기)`,
+        `  ${c.cyan("/stream")}   실시간 스트리밍 출력 켜기/끄기`,
         `  ${c.cyan("/context")}  지금 모델에 보내는 컨텍스트 들여다보기`,
         `  ${c.cyan("/skills")}   스킬 목록(.cdsa/skills 의 /명령들)`,
-        `  ${c.cyan("/plugins")}  플러그인 목록(.cdsa/plugins 의 추가 도구)`,
+        `  ${c.cyan("/plugins")}  플러그인 목록(파일·npm 추가 도구)`,
+        `  ${c.cyan("/mcp")}      연결된 MCP 서버/도구(다른 에이전트와 공용)`,
         `  ${c.cyan("/reset")}    대화/컨텍스트 초기화`,
         `  ${c.cyan("/config")}   현재 설정값`,
         `  ${c.cyan("/quit")}     종료 (Ctrl+D)`,
@@ -232,8 +257,14 @@ function printHelp() {
   );
 }
 
+// 붙여넣기한 키에 섞이기 쉬운 따옴표/공백/줄바꿈을 정리.
+function cleanKey(s) {
+  return (s || "").trim().replace(/^["']|["']$/g, "").trim();
+}
+
 // 대화형 연결 설정. 키는 환경변수가 있으면 그걸 우선 안내(파일 저장 안 함).
-async function runSetup(rl, cfg) {
+// ask 가 null 을 주면(Ctrl+C) 조용히 취소.
+async function runSetup(ask, cfg) {
   console.log(panel(
     [
       "어떤 AI 에 연결할까요? 번호를 입력하세요.",
@@ -244,8 +275,9 @@ async function runSetup(rl, cfg) {
     ],
     { title: "🔌 연결 설정 (/setup)", color: "cyan" }
   ));
-  const pick = (await rl.question(c.cyan("제공자 번호 [1-4]: "))).trim();
-  const provider = { "1": "openai", "2": "anthropic", "3": "openrouter", "4": "mock" }[pick];
+  const pickRaw = await ask(c.cyan("제공자 번호 [1-4] (취소: Enter): "));
+  if (pickRaw === null) return false;
+  const provider = { "1": "openai", "2": "anthropic", "3": "openrouter", "4": "mock" }[pickRaw.trim()];
   if (!provider) {
     console.log(c.yellow("취소했습니다."));
     return false;
@@ -257,27 +289,36 @@ async function runSetup(rl, cfg) {
   } else {
     const envName = ENV_KEYS[provider];
     const envVal = (process.env[envName] || "").trim();
+    let useExistingEnv = false;
     if (envVal) {
-      const useEnv = (await rl.question(c.cyan(`환경변수 ${envName} 에서 키를 찾았어요. 사용할까요? [Y/n] `))).trim().toLowerCase();
-      if (useEnv === "" || useEnv === "y" || useEnv === "yes") {
-        cfg.api_key = ""; // 환경변수 사용 → 파일엔 저장 안 함
-      } else {
-        const k = (await rl.question(c.cyan("API 키 붙여넣기(입력이 보일 수 있음): "))).trim();
-        cfg.api_key = k;
-      }
+      const useEnv = (await ask(c.cyan(`환경변수 ${envName} 에서 키를 찾았어요. 사용할까요? [Y/n] `))) || "";
+      useExistingEnv = ["", "y", "yes"].includes(useEnv.trim().toLowerCase());
+    }
+    if (useExistingEnv) {
+      cfg.api_key = ""; // 환경변수 사용 → 파일엔 저장 안 함
     } else {
-      console.log(c.dim(`(또는 종료 후 환경변수 ${envName} 에 키를 넣어두면 파일에 저장하지 않아도 됩니다)`));
-      const k = (await rl.question(c.cyan("API 키 붙여넣기(입력이 보일 수 있음): "))).trim();
-      cfg.api_key = k;
+      if (!envVal) console.log(c.dim(`(또는 종료 후 환경변수 ${envName} 에 키를 넣어두면 파일에 저장하지 않아도 됩니다)`));
+      const k = await ask(c.cyan("API 키 붙여넣기(붙여넣기 후 Enter): "));
+      if (k === null) {
+        console.log(c.yellow("취소했습니다."));
+        return false;
+      }
+      cfg.api_key = cleanKey(k);
     }
     const sugg = SUGGESTED_MODELS[provider] || [];
     const def = sugg[0] || "";
-    const m = (await rl.question(c.cyan(`모델 [${def}] (추천: ${sugg.join(", ")}): `))).trim();
-    cfg.model = m || def;
+    const note = provider === "openrouter" ? c.dim("  (OpenRouter 는 'provider/model' 형식)") : "";
+    const m = await ask(c.cyan(`모델 [${def}]${note}\n  추천: ${sugg.join(", ")}\n  > `));
+    if (m === null) {
+      console.log(c.yellow("취소했습니다."));
+      return false;
+    }
+    cfg.model = m.trim() || def;
   }
 
   const saved = saveConfig(cfg);
   console.log(c.green(`설정을 저장했습니다 → ${saved}`));
+  console.log(c.dim(`provider=${cfg.provider} · model=${cfg.model}`));
   if (!cfg.isReady()) console.log(c.yellow("⚠️ 아직 키가 없어 호출이 실패할 수 있어요. 환경변수나 /setup 으로 키를 넣어주세요."));
   return true;
 }
@@ -290,6 +331,7 @@ function parseArgs(argv) {
     else if (a === "--help" || a === "-h") out.help = true;
     else if (a === "--setup") out.setup = true;
     else if (a === "--no-teach") out.noTeach = true;
+    else if (a === "--no-stream") out.noStream = true;
     else if (a === "--provider") out.provider = argv[++i];
     else if (a === "--model") out.model = argv[++i];
     else if (a === "--workspace") out.workspace = argv[++i];
@@ -310,6 +352,7 @@ export async function main(argv = []) {
         "  --workspace <폴더경로>\n" +
         "  --setup                대화형 연결 설정 실행\n" +
         "  --no-teach             교육 모드 끄고 간결하게\n" +
+        "  --no-stream            실시간 스트리밍 끄기\n" +
         "  --auto                 승인 자동(approval_mode=auto)\n" +
         "  -h, --help             도움말\n\n" +
         "API 키는 환경변수로도 인식됩니다: OPENAI_API_KEY / ANTHROPIC_API_KEY / OPENROUTER_API_KEY\n"
@@ -341,14 +384,35 @@ export async function main(argv = []) {
   if (args.workspace) cfg.workspace = args.workspace;
   if (args.auto) cfg.approval_mode = "auto";
   if (args.noTeach) cfg.teach_mode = false;
+  if (args.noStream) cfg.stream = false;
 
   const rl = readline.createInterface({ input: stdin, output: stdout });
+  let session = null;
+  let mcp = { tools: [], servers: [], errors: [], closeAll: () => {} };
+
+  // Ctrl+C → 깔끔하게 종료(스택트레이스 없이). 어디서 누르든 안전.
+  const gracefulExit = () => {
+    try { rl.close(); } catch { /* */ }
+    try { session && session.close(); } catch { /* */ }
+    try { mcp && mcp.closeAll && mcp.closeAll(); } catch { /* */ }
+    console.log(c.dim("\n종료합니다. 안녕히 가세요!"));
+    process.exit(0);
+  };
+  rl.on("SIGINT", gracefulExit);
+  // 프롬프트 헬퍼: Ctrl+C(AbortError) 등은 null 로 돌려 호출부가 취소로 처리.
+  const ask = async (q) => {
+    try {
+      return await rl.question(q);
+    } catch {
+      return null;
+    }
+  };
 
   if (args.setup) {
-    await runSetup(rl, cfg);
+    await runSetup(ask, cfg);
   } else if (!cfg.isReady() && cfg.provider !== "mock") {
     console.log(c.yellow(`provider=${cfg.provider} 인데 API 키가 없습니다. 연결 설정을 시작합니다.\n`));
-    await runSetup(rl, cfg);
+    await runSetup(ask, cfg);
   }
 
   printIntro(cfg);
@@ -358,39 +422,58 @@ export async function main(argv = []) {
   //   ② npm 패키지: cdsa-harness-plugin-* 자동 발견 + config.plugins 강제 로드
   const filePlugins = await loadPlugins(cfg.workspacePath());
   const npm = await discoverNpmExtensions(process.cwd(), cfg.plugins || []);
-  const plugins = [...filePlugins, ...npm.plugins, ...npm.errors.map((e) => ({ error: e }))];
+  // ③ MCP 서버(다른 에이전트와 공용 표준)의 도구도 플러그인처럼 등록
+  if (cfg.mcpServers && Object.keys(cfg.mcpServers).length) {
+    process.stdout.write(c.dim("MCP 서버 연결 중...\r"));
+    mcp = await connectMcpServers(cfg.mcpServers);
+  }
+  const plugins = [
+    ...filePlugins,
+    ...npm.plugins,
+    ...mcp.tools,
+    ...npm.errors.map((e) => ({ error: e })),
+    ...mcp.errors.map((e) => ({ error: `MCP ${e}` })),
+  ];
   const skills = {};
   for (const s of npm.skills) skills[s.name] = { name: s.name, description: s.description || "", body: s.body, source: "(npm)" };
   Object.assign(skills, loadSkills(cfg.workspacePath())); // 로컬 파일 스킬이 우선
   const toolbox = new Toolbox(cfg.workspacePath(), cfg.allow_shell, plugins);
-  if (toolbox.plugins.length || Object.keys(skills).length || toolbox.pluginErrors.length) {
+  if (toolbox.plugins.length || Object.keys(skills).length || toolbox.pluginErrors.length || mcp.servers.length) {
     const bits = [];
-    if (toolbox.plugins.length) bits.push(c.green(`플러그인 ${toolbox.plugins.length}개`) + c.grey(` (${toolbox.plugins.map((p) => p.name).join(", ")})`));
-    if (Object.keys(skills).length) bits.push(c.green(`스킬 ${Object.keys(skills).length}개`) + c.grey(` (${Object.keys(skills).map((s) => "/" + s).join(", ")})`));
-    if (toolbox.pluginErrors.length) bits.push(c.red(`플러그인 오류 ${toolbox.pluginErrors.length}개`));
-    console.log("🔌 " + bits.join(" · ") + "\n");
+    if (toolbox.plugins.length) bits.push(c.green(`도구 +${toolbox.plugins.length}개`));
+    if (mcp.servers.length) bits.push(c.green(`MCP ${mcp.servers.length}개`) + c.grey(` (${mcp.servers.map((s) => s.name).join(", ")})`));
+    if (Object.keys(skills).length) bits.push(c.green(`스킬 ${Object.keys(skills).length}개`));
+    if (toolbox.pluginErrors.length) bits.push(c.red(`오류 ${toolbox.pluginErrors.length}개`));
+    console.log("🔌 " + bits.join(" · ") + c.dim("  (/plugins /skills /mcp 로 상세)") + "\n");
   }
 
-  const session = SessionLog.create();
+  session = SessionLog.create();
+  // 스트리밍: 토큰이 도착하는 대로 실시간 출력(첫 토큰에 헤더 1회).
+  const stream = { active: false };
+  const onToken = (chunk) => {
+    if (!stream.active) {
+      process.stdout.write("\n" + c.green("🤖 ③ 모델 응답 (스트리밍)") + "\n");
+      stream.active = true;
+    }
+    process.stdout.write(c.green(chunk));
+  };
   const loop = new AgentLoop({
     config: cfg,
     client: makeClient(cfg),
     toolbox,
-    onEvent: makePrinter(cfg),
-    approvalCallback: makeApproval(rl),
+    onEvent: makePrinter(cfg, stream),
+    approvalCallback: makeApproval(ask),
     session,
+    onToken,
   });
   loop.reset();
 
   const rule = () => console.log(c.grey("─".repeat(Math.min(80, stdout.columns || 80))));
 
   while (true) {
-    let user;
-    try {
-      user = (await rl.question(c.bold(c.cyan("› ")))).trim();
-    } catch {
-      break;
-    }
+    const raw = await ask(c.bold(c.cyan("› ")));
+    if (raw === null) break; // Ctrl+D / Ctrl+C / 스트림 종료
+    const user = raw.trim();
     if (!user) continue;
     const low = user.toLowerCase();
 
@@ -404,8 +487,13 @@ export async function main(argv = []) {
       console.log(c.green(`교육 모드 ${cfg.teach_mode ? "ON" : "OFF"}.`));
       continue;
     }
+    if (low === "/stream") {
+      cfg.stream = !cfg.stream;
+      console.log(c.green(`스트리밍 ${cfg.stream ? "ON (실시간 출력)" : "OFF"}.`));
+      continue;
+    }
     if (low === "/setup" || low === "/login") {
-      await runSetup(rl, cfg);
+      await runSetup(ask, cfg);
       loop.client = makeClient(cfg);
       loop.reset();
       continue;
@@ -449,6 +537,16 @@ export async function main(argv = []) {
       console.log(panel(lines, { title: "🔌 플러그인 (모델이 쓸 수 있는 추가 도구)", color: "blue" }));
       continue;
     }
+    if (low === "/mcp") {
+      const lines = [];
+      if (!mcp.servers.length) lines.push(c.dim("연결된 MCP 서버가 없습니다."));
+      for (const s of mcp.servers) lines.push(`${c.bold(s.name)}  ${c.grey(`도구 ${s.count}개`)}`);
+      for (const t of mcp.tools) lines.push(`  ${c.cyan(t.name)}  ${c.grey(clip(t.description, 60))}`);
+      for (const e of mcp.errors) lines.push(c.red("✖ " + e));
+      lines.push(c.dim('설정: config.json 의 "mcpServers" (Claude Code/Cursor 와 동일 형식)'));
+      console.log(panel(lines, { title: "🔗 MCP 서버 (다른 에이전트와 공용)", color: "blue" }));
+      continue;
+    }
     if (low === "/skills") {
       const names = Object.keys(skills);
       const lines = names.length ? names.map((n) => `${c.cyan("/" + n)}  ${c.grey(skills[n].description || "")}`) : [c.dim("등록된 스킬이 없습니다.")];
@@ -487,6 +585,7 @@ export async function main(argv = []) {
 
   rl.close();
   session.close();
+  mcp.closeAll();
   console.log(c.dim("\n종료합니다. 안녕히 가세요!"));
   return 0;
 }

package/src/config.js

@@ -9,10 +9,11 @@ export const PROVIDERS = ["openai", "anthropic", "openrouter", "mock"];
 export const SUGGESTED_MODELS = {
   openai: ["gpt-4o-mini", "gpt-4.1-mini", "gpt-4.1"],
   anthropic: ["claude-3-5-haiku-latest", "claude-3-5-sonnet-latest", "claude-sonnet-4-5"],
+  // OpenRouter 는 반드시 'provider/model' 형식. (옛 anthropic/claude-3.5-sonnet 등은 404 가능)
   openrouter: [
     "openai/gpt-4o-mini",
-    "anthropic/claude-3.5-sonnet",
-    "google/gemini-2.5-flash",
+    "anthropic/claude-3.7-sonnet",
+    "google/gemini-2.0-flash-001",
   ],
   mock: ["mock-agent"],
 };
@@ -37,7 +38,9 @@ const DEFAULTS = {
   temperature: 0.2,
   max_tokens: 1024,
   teach_mode: true,
+  stream: true, // 모델 응답을 실시간(토큰 단위)으로 출력
   plugins: [], // 추가로 불러올 npm 플러그인 패키지 이름(이름 규칙과 무관하게 강제 로드)
+  mcpServers: {}, // MCP 서버 설정 (Claude Code/Cursor 와 동일한 형식)
 };
 
 export function configDir() {

package/src/llm.js

@@ -23,13 +23,43 @@ export class LLMClient {
     this.timeout = timeout;
   }
 
-  async chat(messages, tools) {
-    if (this.provider === "mock") return mockChat(messages);
-    if (this.provider === "anthropic") return this._anthropicChat(messages, tools);
-    if (ENDPOINTS[this.provider]) return this._openaiChat(messages, tools);
+  // onToken(chunk) 를 주면 텍스트가 도착하는 대로 콜백한다(스트리밍).
+  async chat(messages, tools, onToken = null) {
+    if (this.provider === "mock") {
+      const r = mockChat(messages);
+      if (onToken && r.content) await streamText(r.content, onToken);
+      return r;
+    }
+    if (this.provider === "anthropic") {
+      return onToken ? this._anthropicStream(messages, tools, onToken) : this._anthropicChat(messages, tools);
+    }
+    if (ENDPOINTS[this.provider]) {
+      return onToken ? this._openaiStream(messages, tools, onToken) : this._openaiChat(messages, tools);
+    }
     throw new LLMError(`지원하지 않는 provider 입니다: ${this.provider}`);
   }
 
+  // 스트리밍용: 응답 객체(본문 스트림)를 그대로 받는다.
+  async _openStream(url, headers, body) {
+    const json = JSON.stringify(body);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeout);
+    const started = Date.now();
+    let res;
+    try {
+      res = await fetch(url, { method: "POST", headers, body: json, signal: ctrl.signal });
+    } catch (e) {
+      clearTimeout(timer);
+      throw new LLMError(`네트워크 오류: ${e.message}`);
+    }
+    if (!res.ok) {
+      clearTimeout(timer);
+      const text = await res.text().catch(() => "");
+      throw new LLMError(httpErrorMessage(res.status, text || res.statusText));
+    }
+    return { res, started, timer, bodyBytes: Buffer.byteLength(json, "utf8") };
+  }
+
   async _post(url, headers, body) {
     const json = JSON.stringify(body);
     const ctrl = new AbortController();
@@ -46,7 +76,7 @@ export class LLMClient {
     const latencyMs = Date.now() - started;
     if (!res.ok) {
       const text = await res.text().catch(() => "");
-      throw new LLMError(`API 오류 ${res.status}: ${trim(text) || res.statusText}`);
+      throw new LLMError(httpErrorMessage(res.status, text || res.statusText));
     }
     return { payload: await res.json(), latencyMs, bodyBytes: Buffer.byteLength(json, "utf8") };
   }
@@ -94,6 +124,87 @@ export class LLMClient {
     };
   }
 
+  // --- OpenAI/OpenRouter 스트리밍 ---
+  async _openaiStream(messages, tools, onToken) {
+    const url = ENDPOINTS[this.provider];
+    const body = { model: this.model, messages, temperature: this.temperature, stream: true, stream_options: { include_usage: true } };
+    if (tools && tools.length) {
+      body.tools = tools;
+      body.tool_choice = "auto";
+    }
+    const headers = { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" };
+    if (this.provider === "openrouter") {
+      headers["HTTP-Referer"] = "https://github.com/cdsassj00/miniharness";
+      headers["X-Title"] = "CDSA Harness";
+    }
+    const { res, started, timer, bodyBytes } = await this._openStream(url, headers, body);
+    let content = "";
+    const tcMap = new Map(); // index -> {id,name,args}
+    let usage = null;
+    try {
+      await readSSE(res, (data) => {
+        if (data === "[DONE]") return;
+        let json;
+        try { json = JSON.parse(data); } catch { return; }
+        if (json.usage) usage = { input: json.usage.prompt_tokens ?? null, output: json.usage.completion_tokens ?? null, total: json.usage.total_tokens ?? null };
+        const delta = json.choices?.[0]?.delta;
+        if (!delta) return;
+        if (delta.content) { content += delta.content; onToken(delta.content); }
+        for (const tc of delta.tool_calls || []) {
+          const i = tc.index ?? 0;
+          const cur = tcMap.get(i) || { id: tc.id || `call_${i}`, name: "", args: "" };
+          if (tc.id) cur.id = tc.id;
+          if (tc.function?.name) cur.name += tc.function.name;
+          if (tc.function?.arguments) cur.args += tc.function.arguments;
+          tcMap.set(i, cur);
+        }
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const toolCalls = [...tcMap.values()].map((t) => ({ id: t.id, name: t.name, args: safeParse(t.args) }));
+    return { content: content || null, toolCalls, usage, latencyMs: Date.now() - started, request: this._meta(url, tools, bodyBytes) };
+  }
+
+  // --- Anthropic 스트리밍 ---
+  async _anthropicStream(messages, tools, onToken) {
+    const url = ENDPOINTS.anthropic;
+    const body = toAnthropicBody(messages, tools, this.model, this.temperature, this.maxTokens);
+    body.stream = true;
+    const headers = { "x-api-key": this.apiKey, "anthropic-version": "2023-06-01", "Content-Type": "application/json" };
+    const { res, started, timer, bodyBytes } = await this._openStream(url, headers, body);
+    let content = "";
+    const blocks = new Map(); // index -> {type,name,id,json}
+    let usage = { input: null, output: null, total: 0 };
+    try {
+      await readSSE(res, (data) => {
+        let ev;
+        try { ev = JSON.parse(data); } catch { return; }
+        if (ev.type === "message_start" && ev.message?.usage) usage.input = ev.message.usage.input_tokens ?? null;
+        else if (ev.type === "content_block_start") {
+          const b = ev.content_block || {};
+          blocks.set(ev.index, { type: b.type, name: b.name, id: b.id, json: "" });
+        } else if (ev.type === "content_block_delta") {
+          const d = ev.delta || {};
+          if (d.type === "text_delta") { content += d.text; onToken(d.text); }
+          else if (d.type === "input_json_delta") {
+            const cur = blocks.get(ev.index);
+            if (cur) cur.json += d.partial_json || "";
+          }
+        } else if (ev.type === "message_delta" && ev.usage) {
+          usage.output = ev.usage.output_tokens ?? usage.output;
+        }
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    usage.total = (usage.input || 0) + (usage.output || 0);
+    const toolCalls = [...blocks.values()]
+      .filter((b) => b.type === "tool_use")
+      .map((b) => ({ id: b.id, name: b.name, args: safeParse(b.json) }));
+    return { content: content || null, toolCalls, usage, latencyMs: Date.now() - started, request: this._meta(url, tools, bodyBytes) };
+  }
+
   _meta(endpoint, tools, bodyBytes) {
     return {
       provider: this.provider,
@@ -111,6 +222,51 @@ function trim(s) {
   return s.length > 400 ? s.slice(0, 400) + " …" : s;
 }
 
+function safeParse(jsonStr) {
+  try {
+    return JSON.parse(jsonStr || "{}");
+  } catch {
+    return { _raw: jsonStr };
+  }
+}
+
+function httpErrorMessage(status, text) {
+  let msg = `API 오류 ${status}: ${trim(text)}`;
+  if (status === 404) {
+    msg += "\n  ↳ 모델 이름을 확인하세요. /model 로 변경 가능. " +
+      "OpenRouter 는 'provider/model' 형식이어야 합니다 (예: openai/gpt-4o-mini, anthropic/claude-3.7-sonnet).";
+  } else if (status === 401 || status === 403) {
+    msg += "\n  ↳ API 키가 잘못되었거나 권한이 없어요. /setup 으로 다시 연결하세요.";
+  } else if (status === 429) {
+    msg += "\n  ↳ 요청이 너무 많거나 크레딧이 부족할 수 있어요(잠시 후 재시도).";
+  }
+  return msg;
+}
+
+// SSE(data: ...) 본문 스트림을 줄 단위로 콜백. onEvent(dataString) 호출(‘[DONE]’ 포함).
+async function readSSE(res, onEvent) {
+  let buf = "";
+  for await (const chunk of res.body) {
+    buf += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    let nl;
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (line.startsWith("data:")) onEvent(line.slice(5).trim());
+    }
+  }
+  if (buf.trim().startsWith("data:")) onEvent(buf.trim().slice(5).trim());
+}
+
+// mock/공통: 텍스트를 토큰처럼 쪼개 콜백(TTY 면 살짝 지연해 흐르는 효과).
+async function streamText(text, onToken) {
+  const parts = String(text).match(/\S+\s*|\s+/g) || [String(text)];
+  for (const p of parts) {
+    onToken(p);
+    if (process.stdout.isTTY) await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
 function parseOpenAiReply(payload) {
   const msg = payload?.choices?.[0]?.message;
   if (!msg) {

package/src/loop.js

@@ -79,13 +79,14 @@ function findRules(workspace) {
 }
 
 export class AgentLoop {
-  constructor({ config, client, toolbox, onEvent, approvalCallback, session = null }) {
+  constructor({ config, client, toolbox, onEvent, approvalCallback, session = null, onToken = null }) {
     this.config = config;
     this.client = client;
     this.toolbox = toolbox;
     this.onEvent = onEvent;
     this.approvalCallback = approvalCallback;
     this.session = session;
+    this.onToken = onToken; // 스트리밍 토큰 콜백(있으면 실시간 출력)
     this.messages = [];
   }
 
@@ -168,9 +169,10 @@ export class AgentLoop {
         }
       );
 
+      const streaming = Boolean(this.onToken && this.config.stream);
       let reply;
       try {
-        reply = await this.client.chat(this.messages, tools);
+        reply = await this.client.chat(this.messages, tools, streaming ? this.onToken : null);
       } catch (e) {
         if (e instanceof LLMError) {
           this._emit(Step.ERROR, "LLM 오류", e.message);
@@ -180,11 +182,13 @@ export class AgentLoop {
       }
 
       // ③ 모델의 원본 판단 + 실측 메타(응답시간/토큰/요청크기)를 드러낸다.
+      // streamed=true 면 텍스트는 이미 실시간 출력됨 → UI 는 메타만 덧붙인다.
       this._emit(Step.MODEL_REPLY, "모델 응답", reply.content || "(텍스트 없음)", {
         toolCalls: reply.toolCalls.map((tc) => ({ name: tc.name, args: tc.args })),
         usage: reply.usage || null,
         latencyMs: reply.latencyMs ?? null,
         request: reply.request || null,
+        streamed: streaming && Boolean(reply.content),
       });
       if (reply.content) finalText = reply.content;
 

package/src/mcp.js

@@ -0,0 +1,148 @@
+// MCP (Model Context Protocol) 클라이언트 — 상호운용의 핵심.
+// Claude Code · Cursor · Zed 등에서 쓰는 'MCP 서버'를 그대로 붙여 쓴다.
+// 설정은 그 도구들과 동일한 형식:
+//   "mcpServers": { "이름": { "command": "npx", "args": ["-y","..."], "env": {} } }
+//
+// stdio 전송(JSON-RPC 2.0, 줄바꿈 구분). 외부 의존성 없음(node child_process).
+import { spawn } from "node:child_process";
+
+const PROTOCOL_VERSION = "2024-11-05";
+
+export class McpServer {
+  constructor(name, spec) {
+    this.name = name;
+    this.spec = spec || {};
+    this.proc = null;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.buf = "";
+    this.tools = [];
+  }
+
+  async start(timeout = 20000) {
+    if (!this.spec.command) throw new Error("command 가 없습니다");
+    this.proc = spawn(this.spec.command, this.spec.args || [], {
+      env: { ...process.env, ...(this.spec.env || {}) },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    this.proc.stdout.on("data", (d) => this._onData(d));
+    this.proc.stderr.on("data", () => {}); // 서버 로그는 무시
+    this.proc.on("error", (e) => this._failAll(e));
+    this.proc.on("exit", () => this._failAll(new Error("MCP 서버 프로세스 종료")));
+
+    await this._request(
+      "initialize",
+      { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: "cdsa-harness", version: "0.5.0" } },
+      timeout
+    );
+    this._notify("notifications/initialized", {});
+    const list = await this._request("tools/list", {}, timeout);
+    this.tools = (list && list.tools) || [];
+    return this.tools;
+  }
+
+  _onData(chunk) {
+    this.buf += chunk.toString("utf8");
+    let nl;
+    while ((nl = this.buf.indexOf("\n")) >= 0) {
+      const line = this.buf.slice(0, nl);
+      this.buf = this.buf.slice(nl + 1);
+      if (!line.trim()) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue; // 프레이밍 깨진 줄 무시
+      }
+      if (msg.id != null && this.pending.has(msg.id)) {
+        const { resolve, reject } = this.pending.get(msg.id);
+        this.pending.delete(msg.id);
+        if (msg.error) reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+        else resolve(msg.result);
+      }
+    }
+  }
+
+  _request(method, params, timeout = 20000) {
+    const id = this.nextId++;
+    const payload = JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n";
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`MCP ${method} 시간초과`));
+      }, timeout);
+      this.pending.set(id, {
+        resolve: (r) => { clearTimeout(timer); resolve(r); },
+        reject: (e) => { clearTimeout(timer); reject(e); },
+      });
+      try {
+        this.proc.stdin.write(payload);
+      } catch (e) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(e);
+      }
+    });
+  }
+
+  _notify(method, params) {
+    try {
+      this.proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+    } catch {
+      /* ignore */
+    }
+  }
+
+  _failAll(err) {
+    for (const { reject } of this.pending.values()) reject(err);
+    this.pending.clear();
+  }
+
+  async callTool(name, args) {
+    const res = await this._request("tools/call", { name, arguments: args || {} });
+    const parts = ((res && res.content) || []).map((b) =>
+      b.type === "text" ? b.text : b.type === "json" ? JSON.stringify(b.json) : `[${b.type}]`
+    );
+    const text = parts.join("\n") || (res && res.isError ? "(오류)" : "(빈 결과)");
+    return res && res.isError ? `MCP 오류: ${text}` : text;
+  }
+
+  stop() {
+    try {
+      this.proc && this.proc.kill();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+// 여러 MCP 서버에 연결하고, 각 도구를 '플러그인 형식' tool def 로 변환해 돌려준다.
+// (Toolbox/loop 가 플러그인과 동일하게 다룰 수 있음)
+export async function connectMcpServers(servers = {}) {
+  const out = { tools: [], servers: [], errors: [], instances: [] };
+  for (const [name, spec] of Object.entries(servers)) {
+    if (!spec || spec.disabled) continue;
+    const srv = new McpServer(name, spec);
+    try {
+      const tools = await srv.start();
+      out.instances.push(srv);
+      out.servers.push({ name, count: tools.length });
+      for (const t of tools) {
+        const readOnly = t.annotations && t.annotations.readOnlyHint === true;
+        out.tools.push({
+          name: `mcp__${name}__${t.name}`,
+          description: t.description || `MCP(${name}) 도구 ${t.name}`,
+          parameters: t.inputSchema || { type: "object", properties: {} },
+          mutating: !readOnly, // 읽기전용 힌트가 없으면 보수적으로 승인 필요
+          handler: async (args) => srv.callTool(t.name, args),
+          source: `mcp:${name}`,
+        });
+      }
+    } catch (e) {
+      out.errors.push(`${name}: ${e.message}`);
+      srv.stop();
+    }
+  }
+  out.closeAll = () => out.instances.forEach((s) => s.stop());
+  return out;
+}

package/src/skills.js

@@ -11,10 +11,21 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+// 우리 폴더 + 다른 코딩 에이전트들의 커맨드/스킬 폴더도 함께 읽어 상호운용한다.
+// (Claude Code, OpenCode 등은 스킬이 결국 frontmatter 달린 마크다운이라 그대로 호환)
 export function skillDirs(workspace) {
+  const home = os.homedir();
   return [
-    path.join(os.homedir(), ".cdsa_harness", "skills"),
+    // 전역
+    path.join(home, ".cdsa_harness", "skills"),
+    path.join(home, ".claude", "commands"),
+    path.join(home, ".config", "opencode", "command"),
+    // 작업 폴더
     path.join(workspace, ".cdsa", "skills"),
+    path.join(workspace, ".claude", "commands"),
+    path.join(workspace, ".claude", "skills"),
+    path.join(workspace, ".opencode", "command"),
+    path.join(workspace, ".github", "prompts"),
   ];
 }
 
@@ -29,33 +40,54 @@ function parseFrontmatter(text) {
   return { meta, body: text.slice(m[0].length).trim() };
 }
 
+function addSkill(skills, name, file) {
+  if (!name || skills[name]) return; // 먼저 발견된 것 우선
+  try {
+    const raw = fs.readFileSync(file, "utf8");
+    const { meta, body } = parseFrontmatter(raw);
+    skills[name] = { name, description: meta.description || "", body, source: file };
+  } catch {
+    /* ignore unreadable skill */
+  }
+}
+
 export function loadSkills(workspace) {
   const skills = {};
   for (const dir of skillDirs(workspace)) {
-    let files = [];
+    let entries = [];
     try {
       if (!fs.existsSync(dir)) continue;
-      files = fs.readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
+      entries = fs.readdirSync(dir).sort();
     } catch {
       continue;
     }
-    for (const f of files) {
-      const name = f.replace(/\.md$/, "");
+    for (const e of entries) {
+      const full = path.join(dir, e);
+      let stat;
       try {
-        const raw = fs.readFileSync(path.join(dir, f), "utf8");
-        const { meta, body } = parseFrontmatter(raw);
-        skills[name] = { name, description: meta.description || "", body, source: path.join(dir, f) };
+        stat = fs.statSync(full);
       } catch {
-        /* ignore unreadable skill */
+        continue;
+      }
+      if (stat.isFile() && e.endsWith(".md")) {
+        addSkill(skills, e.replace(/\.md$/, ""), full);
+      } else if (stat.isDirectory()) {
+        // Claude Code 스킬 형식: <이름>/SKILL.md
+        const skillMd = path.join(full, "SKILL.md");
+        if (fs.existsSync(skillMd)) addSkill(skills, e, skillMd);
       }
     }
   }
   return skills;
 }
 
-// 스킬 본문에 인자를 채워 최종 프롬프트를 만든다.
+// 스킬 본문에 인자를 채워 최종 프롬프트를 만든다. $ARGUMENTS / {{args}} 둘 다 지원.
 export function renderSkill(skill, args) {
   const argStr = (args || "").trim();
-  if (skill.body.includes("$ARGUMENTS")) return skill.body.replace(/\$ARGUMENTS/g, argStr);
-  return argStr ? `${skill.body}\n\n[추가 입력]\n${argStr}` : skill.body;
+  let body = skill.body;
+  const hasPlaceholder = /\$ARGUMENTS|\{\{\s*args\s*\}\}/.test(body);
+  if (hasPlaceholder) {
+    return body.replace(/\$ARGUMENTS/g, argStr).replace(/\{\{\s*args\s*\}\}/g, argStr);
+  }
+  return argStr ? `${body}\n\n[추가 입력]\n${argStr}` : body;
 }