triflux 8.9.2 → 8.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "8.9.2",
+  "version": "8.11.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/scripts/mcp-cleanup.ps1

@@ -0,0 +1,17 @@
+# mcp-cleanup.ps1 — Claude Code Stop hook: MCP 고아 프로세스 정리
+# Windows에서 Claude Code 세션 종료 시 남는 MCP 서버 고아 프로세스를 정리한다.
+# 원인: Claude Code가 stdio MCP 자식 프로세스 트리를 Windows에서 제대로 kill하지 못함
+#       (GitHub Issues #1935, #15211, #28126)
+$ErrorActionPreference = 'SilentlyContinue'
+
+# npx MCP servers (brave, notion, context7, exa, tavily, jira, playwright, etc.)
+# + oh-my-codex MCP servers (team/code-intel/memory/trace/state)
+# + omc bridge
+Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='cmd.exe'" |
+  Where-Object { $_.CommandLine -match 'npx-cli|oh-my-codex[\\/]dist[\\/]mcp|omc.*bridge.*mcp-server' } |
+  ForEach-Object { taskkill /F /PID $_.ProcessId 2>$null }
+
+# serena (uvx) + python MCP orphans
+Get-CimInstance Win32_Process -Filter "Name='python.exe' OR Name='uvx.exe'" |
+  Where-Object { $_.CommandLine -match 'serena|uv[\\/](cache|python)' } |
+  ForEach-Object { taskkill /F /PID $_.ProcessId 2>$null }

package/scripts/mcp-gateway-config.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// mcp-gateway-config.mjs — Claude Code MCP stdio↔SSE 전환
+// Usage: node mcp-gateway-config.mjs --enable   # stdio → SSE
+//        node mcp-gateway-config.mjs --disable  # SSE → stdio (복원)
+
+import { execSync } from 'node:child_process';
+
+export const GATEWAY_SERVERS = [
+  { name: 'context7',     port: 8100, stdioCmd: 'cmd /c npx -y @upstash/context7-mcp@latest' },
+  { name: 'brave-search', port: 8101, stdioCmd: 'cmd /c npx -y @brave/brave-search-mcp-server' },
+  { name: 'exa',          port: 8102, stdioCmd: 'cmd /c npx -y exa-mcp-server' },
+  { name: 'tavily',       port: 8103, stdioCmd: 'cmd /c npx -y tavily-mcp@latest' },
+  { name: 'jira',         port: 8104, stdioCmd: 'cmd /c npx -y mcp-jira-cloud@latest' },
+  { name: 'serena',       port: 8105, stdioCmd: 'uvx --from git+https://github.com/oraios/serena serena start-mcp-server' },
+  { name: 'notion',       port: 8106, stdioCmd: 'cmd /c npx -y @notionhq/notion-mcp-server' },
+  { name: 'notion-guest', port: 8107, stdioCmd: 'cmd /c npx -y @notionhq/notion-mcp-server' },
+];
+
+const SKIP_SERVERS = new Set([
+  'playwright',
+  'claude.ai Notion',
+  'plugin:oh-my-claudecode:t',
+]);
+
+// Git Bash에서 /c → C:/ 경로 변환 방지
+const EXEC_ENV = { ...process.env, MSYS_NO_PATHCONV: '1' };
+
+function run(cmd) {
+  try {
+    execSync(cmd, { stdio: 'pipe', encoding: 'utf8', timeout: 15000, env: EXEC_ENV });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function removeMcp(name) {
+  // 여러 scope에서 제거 시도 (user → local)
+  run(`claude mcp remove "${name}" -s user`);
+  run(`claude mcp remove "${name}" -s local`);
+}
+
+function enableSse() {
+  console.log('Switching MCP servers to SSE mode...\n');
+  let ok = 0;
+  let fail = 0;
+
+  for (const { name, port } of GATEWAY_SERVERS) {
+    if (SKIP_SERVERS.has(name)) continue;
+
+    removeMcp(name);
+    const url = `http://localhost:${port}/sse`;
+    const success = run(`claude mcp add --transport sse -s user "${name}" ${url}`);
+
+    if (success) {
+      console.log(`  [SSE] ${name} → ${url}`);
+      ok++;
+    } else {
+      console.error(`  [FAIL] ${name}`);
+      fail++;
+    }
+  }
+
+  console.log(`\nDone: ${ok} switched, ${fail} failed`);
+}
+
+function disableSse() {
+  console.log('Restoring MCP servers to stdio mode...\n');
+  let ok = 0;
+  let fail = 0;
+
+  for (const { name, stdioCmd } of GATEWAY_SERVERS) {
+    if (SKIP_SERVERS.has(name)) continue;
+
+    removeMcp(name);
+    const success = run(`claude mcp add "${name}" -s user -- ${stdioCmd}`);
+
+    if (success) {
+      console.log(`  [stdio] ${name} → ${stdioCmd}`);
+      ok++;
+    } else {
+      console.error(`  [FAIL] ${name}`);
+      fail++;
+    }
+  }
+
+  console.log(`\nDone: ${ok} restored, ${fail} failed`);
+}
+
+function printUsage() {
+  console.log(`Usage: node mcp-gateway-config.mjs [--enable|--disable]
+
+  --enable   Switch Claude Code MCP servers from stdio to SSE (supergateway)
+  --disable  Restore Claude Code MCP servers to original stdio mode
+
+Servers managed: ${GATEWAY_SERVERS.map((s) => s.name).join(', ')}
+Servers skipped: ${[...SKIP_SERVERS].join(', ')}`);
+}
+
+// ── main ──
+const flag = process.argv[2];
+
+if (flag === '--enable') {
+  enableSse();
+} else if (flag === '--disable') {
+  disableSse();
+} else {
+  printUsage();
+  process.exit(flag ? 1 : 0);
+}

package/scripts/mcp-gateway-ensure.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// mcp-gateway-ensure.mjs — SessionStart 훅에서 supergateway MCP 서비스 보장
+// hub-ensure.mjs 패턴을 따름. 가볍게 헬스체크만 수행하고 필요시 기동.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const PLUGIN_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const PID_FILE = join(tmpdir(), 'tfx-gateway-pids.json');
+const PROBE_PORT = 8100; // context7 — 첫 번째 게이트웨이 포트로 alive 프로브
+const PROBE_TIMEOUT_MS = 1500;
+const STARTUP_WAIT_MS = 4000;
+const POLL_INTERVAL_MS = 500;
+
+/**
+ * 단일 포트 /healthz 프로브로 게이트웨이 클러스터 alive 판정.
+ * 모든 포트를 체크하면 hook timeout(8s)에 걸리므로 대표 포트 1개만 확인.
+ */
+async function isGatewayAlive() {
+  try {
+    const res = await fetch(`http://127.0.0.1:${PROBE_PORT}/healthz`, {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** 매니페스트 파일 존재 여부로 gateway 설치 판정 (빠른 경로) */
+function hasManifest() {
+  return existsSync(PID_FILE);
+}
+
+/** mcp-gateway-start.mjs를 detached로 기동 */
+function startGateway() {
+  const scriptPath = join(PLUGIN_ROOT, 'scripts', 'mcp-gateway-start.mjs');
+  if (!existsSync(scriptPath)) return false;
+
+  try {
+    // hub-ensure.mjs 패턴: cmd.exe /c start /b → hook timeout에서 생존
+    const child = spawn('cmd.exe', ['/c', 'start', '/b', '', process.execPath, scriptPath], {
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 게이트웨이 기동 후 프로브 포트 ready 대기 */
+async function waitForGatewayReady(maxWaitMs = STARTUP_WAIT_MS) {
+  const deadline = Date.now() + maxWaitMs;
+  while (Date.now() < deadline) {
+    if (await isGatewayAlive()) return true;
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  return false;
+}
+
+// ── main ──
+
+// 빠른 경로: 매니페스트 존재 + 프로브 포트 살아있으면 즉시 OK
+if (hasManifest() && await isGatewayAlive()) {
+  process.stdout.write('gateway: ok');
+  process.exit(0);
+}
+
+// 매니페스트 없으면 gateway가 설정되지 않은 상태 — 조용히 스킵
+if (!hasManifest()) {
+  process.stdout.write('gateway: not configured');
+  process.exit(0);
+}
+
+// 느린 경로: 게이트웨이 기동 시도
+const started = startGateway();
+if (started) {
+  const ready = await waitForGatewayReady();
+  process.stdout.write(ready ? 'gateway: ok' : 'gateway: starting');
+} else {
+  process.stderr.write('[gateway-ensure] start failed');
+}

package/scripts/mcp-gateway-start.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// mcp-gateway-start.mjs — supergateway MCP SSE 영속 서비스 관리
+// Usage: node mcp-gateway-start.mjs          # 시작
+//        node mcp-gateway-start.mjs --stop   # 중지
+//        node mcp-gateway-start.mjs --status # 상태 확인
+
+import { spawn, execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createConnection } from 'node:net';
+
+const PID_FILE = join(tmpdir(), 'tfx-gateway-pids.json');
+const STARTUP_WAIT_MS = 8000;
+const POLL_INTERVAL_MS = 500;
+const HEALTH_TIMEOUT_MS = 3000;
+
+const SERVERS = [
+  { name: 'context7',     port: 8100, cmd: 'npx -y @upstash/context7-mcp@latest',          envVars: [] },
+  { name: 'brave-search', port: 8101, cmd: 'npx -y @brave/brave-search-mcp-server',        envVars: ['BRAVE_API_KEY'] },
+  { name: 'exa',          port: 8102, cmd: 'npx -y exa-mcp-server',                        envVars: ['EXA_API_KEY'] },
+  { name: 'tavily',       port: 8103, cmd: 'npx -y tavily-mcp@latest',                     envVars: ['TAVILY_API_KEY'] },
+  { name: 'jira',         port: 8104, cmd: 'npx -y mcp-jira-cloud@latest',                 envVars: ['JIRA_API_TOKEN', 'JIRA_EMAIL', 'JIRA_INSTANCE_URL'] },
+  { name: 'serena',       port: 8105, cmd: 'uvx --from git+https://github.com/oraios/serena serena start-mcp-server', envVars: [] },
+  { name: 'notion',       port: 8106, cmd: 'npx -y @notionhq/notion-mcp-server',           envVars: ['NOTION_TOKEN'] },
+  { name: 'notion-guest', port: 8107, cmd: 'npx -y @notionhq/notion-mcp-server',           envVars: ['NOTION_TOKEN'] },
+];
+
+export { SERVERS };
+
+// ── 유틸리티 ──
+
+function isPortInUse(port) {
+  return new Promise((resolve) => {
+    const sock = createConnection({ host: '127.0.0.1', port });
+    sock.once('connect', () => { sock.destroy(); resolve(true); });
+    sock.once('error', () => resolve(false));
+    sock.setTimeout(1000, () => { sock.destroy(); resolve(false); });
+  });
+}
+
+async function checkHealth(port) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/healthz`, {
+      signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// ── 시작 ──
+
+function spawnGateway(srv) {
+  // 단일 명령 문자열 — shell: true에서 공백 인자를 올바르게 쿼팅
+  const cmdStr = `npx -y supergateway --stdio "${srv.cmd}" --port ${srv.port} --outputTransport sse --healthEndpoint /healthz`;
+
+  // detached: true → 독립 프로세스 그룹 (부모 종료 후 생존)
+  // shell: true → Windows에서 npx.cmd 해석
+  const child = spawn(cmdStr, [], {
+    detached: true,
+    stdio: 'ignore',
+    shell: true,
+    windowsHide: true,
+    env: process.env,
+  });
+  child.unref();
+  return child.pid;
+}
+
+async function startAll() {
+  const launched = [];
+
+  for (const srv of SERVERS) {
+    // 포트 사용 중이면 스킵
+    if (await isPortInUse(srv.port)) {
+      console.log(`[SKIP] ${srv.name} already running on :${srv.port}`);
+      continue;
+    }
+
+    // 필수 환경변수 체크
+    const missing = srv.envVars.filter((k) => !process.env[k]);
+    if (missing.length > 0) {
+      console.log(`[WARN] ${srv.name} skipped — missing env: ${missing.join(', ')}`);
+      continue;
+    }
+
+    spawnGateway(srv);
+    launched.push(srv);
+    console.log(`[START] ${srv.name} on :${srv.port}`);
+  }
+
+  if (launched.length === 0) {
+    console.log('\n[gateway] No servers started (all running or skipped)');
+    return;
+  }
+
+  // 헬스체크 대기
+  console.log(`\n[gateway] Waiting for ${launched.length} servers...`);
+  const deadline = Date.now() + STARTUP_WAIT_MS;
+  const pending = new Set(launched.map((s) => s.port));
+
+  while (pending.size > 0 && Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    for (const port of [...pending]) {
+      if (await checkHealth(port)) pending.delete(port);
+    }
+  }
+
+  // 결과 출력
+  console.log('\nHealth Check');
+  console.log('='.repeat(50));
+  const pidEntries = [];
+  for (const srv of launched) {
+    const healthy = !pending.has(srv.port);
+    const mark = healthy ? '\u2713' : '\u2717';
+    const status = healthy ? 'ok' : 'down';
+    console.log(`  ${srv.name.padEnd(16)} :${srv.port}  ${mark} ${status}`);
+    if (healthy) pidEntries.push({ name: srv.name, port: srv.port });
+  }
+
+  // PID 파일 대신 포트 매니페스트 저장 (프로세스 찾기는 포트 기반)
+  const existing = loadManifest();
+  const merged = [...existing.filter((e) => !pidEntries.some((p) => p.port === e.port)), ...pidEntries];
+  writeFileSync(PID_FILE, JSON.stringify(merged, null, 2));
+  console.log(`\n[gateway] ${launched.length - pending.size}/${launched.length} healthy. Manifest: ${PID_FILE}`);
+}
+
+// ── 중지 ──
+
+function stopAll() {
+  // supergateway + 하위 MCP 프로세스를 포트 기반으로 찾아 종료
+  try {
+    const ps = `Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='cmd.exe'" | Where-Object { $_.CommandLine -match 'supergateway' } | ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null; Write-Output "[STOP] PID $($_.ProcessId)" }`;
+    const output = execSync(`powershell -NoProfile -Command "${ps}"`, {
+      encoding: 'utf8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    if (output.trim()) console.log(output.trim());
+    else console.log('[gateway] No supergateway processes found');
+  } catch {
+    console.log('[gateway] No supergateway processes found');
+  }
+
+  if (existsSync(PID_FILE)) {
+    unlinkSync(PID_FILE);
+    console.log('[gateway] Manifest removed');
+  }
+}
+
+// ── 상태 ──
+
+async function showStatus() {
+  const manifest = loadManifest();
+  if (manifest.length === 0) {
+    console.log('[gateway] No manifest — checking all ports...');
+  }
+
+  console.log('\nMCP Gateway Status');
+  console.log('='.repeat(50));
+  for (const srv of SERVERS) {
+    const healthy = await checkHealth(srv.port);
+    const mark = healthy ? '\u2713' : '\u2717';
+    const status = healthy ? 'ok' : 'down';
+    console.log(`  ${srv.name.padEnd(16)} :${srv.port}  ${mark} ${status}`);
+  }
+}
+
+function loadManifest() {
+  if (!existsSync(PID_FILE)) return [];
+  try {
+    return JSON.parse(readFileSync(PID_FILE, 'utf8'));
+  } catch {
+    return [];
+  }
+}
+
+// ── main ──
+
+const flag = process.argv[2];
+if (flag === '--stop') {
+  stopAll();
+} else if (flag === '--status') {
+  await showStatus();
+} else {
+  await startAll();
+}

package/scripts/mcp-gateway-start.ps1

@@ -0,0 +1,138 @@
+# mcp-gateway-start.ps1 — supergateway MCP SSE 영속 서비스 관리
+# 각 MCP 서버를 supergateway로 래핑하여 SSE 엔드포인트로 노출한다.
+# Usage: .\mcp-gateway-start.ps1          # 시작
+#        .\mcp-gateway-start.ps1 -Stop    # 중지
+
+param(
+  [switch]$Stop
+)
+
+$PidFile = Join-Path $env:TEMP 'tfx-gateway-pids.json'
+
+$Servers = @(
+  @{ Name = 'context7';     Port = 8100; Cmd = 'npx -y @upstash/context7-mcp@latest';          EnvVars = @() }
+  @{ Name = 'brave-search'; Port = 8101; Cmd = 'npx -y @brave/brave-search-mcp-server';        EnvVars = @('BRAVE_API_KEY') }
+  @{ Name = 'exa';          Port = 8102; Cmd = 'npx -y exa-mcp-server';                        EnvVars = @('EXA_API_KEY') }
+  @{ Name = 'tavily';       Port = 8103; Cmd = 'npx -y tavily-mcp@latest';                     EnvVars = @('TAVILY_API_KEY') }
+  @{ Name = 'jira';         Port = 8104; Cmd = 'npx -y mcp-jira-cloud@latest';                 EnvVars = @('JIRA_API_TOKEN', 'JIRA_EMAIL', 'JIRA_INSTANCE_URL') }
+  @{ Name = 'serena';       Port = 8105; Cmd = 'uvx --from git+https://github.com/oraios/serena serena start-mcp-server'; EnvVars = @() }
+  @{ Name = 'notion';       Port = 8106; Cmd = 'npx -y @notionhq/notion-mcp-server';           EnvVars = @('NOTION_TOKEN') }
+  @{ Name = 'notion-guest'; Port = 8107; Cmd = 'npx -y @notionhq/notion-mcp-server';           EnvVars = @('NOTION_TOKEN') }
+)
+
+function Test-PortInUse {
+  param([int]$Port)
+  try {
+    $tcp = New-Object System.Net.Sockets.TcpClient
+    $tcp.Connect('127.0.0.1', $Port)
+    $tcp.Close()
+    return $true
+  }
+  catch {
+    return $false
+  }
+}
+
+function Stop-AllGateways {
+  if (-not (Test-Path $PidFile)) {
+    Write-Host '[gateway] PID file not found — nothing to stop'
+    return
+  }
+  try {
+    $entries = Get-Content $PidFile -Raw | ConvertFrom-Json
+    foreach ($entry in $entries) {
+      try {
+        Stop-Process -Id $entry.pid -Force -ErrorAction SilentlyContinue
+        Write-Host "[STOP] $($entry.name) (PID $($entry.pid))"
+      }
+      catch {
+        Write-Host "[SKIP] $($entry.name) (PID $($entry.pid)) — already gone"
+      }
+    }
+    Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
+    Write-Host '[gateway] All gateways stopped'
+  }
+  catch {
+    Write-Error "[gateway] Failed to parse PID file: $_"
+  }
+}
+
+function Start-AllGateways {
+  $pidEntries = @()
+  $started = 0
+
+  foreach ($srv in $Servers) {
+    $name = $srv.Name
+    $port = $srv.Port
+
+    # 포트 사용 중이면 스킵
+    if (Test-PortInUse -Port $port) {
+      Write-Host "[SKIP] $name already running on :$port"
+      continue
+    }
+
+    # 필수 환경변수 체크
+    $missing = @()
+    foreach ($envKey in $srv.EnvVars) {
+      if (-not [Environment]::GetEnvironmentVariable($envKey)) {
+        $missing += $envKey
+      }
+    }
+    if ($missing.Count -gt 0) {
+      Write-Host "[WARN] $name skipped — missing env: $($missing -join ', ')"
+      continue
+    }
+
+    # supergateway 기동 — npx는 .cmd 파일이므로 cmd.exe /c 로 래핑
+    $stdioCmdEscaped = $srv.Cmd -replace '"', '\"'
+    $sgCmd = "npx -y supergateway --stdio `"$stdioCmdEscaped`" --port $port --outputTransport sse --healthEndpoint /healthz"
+
+    try {
+      $proc = Start-Process -FilePath 'cmd.exe' -ArgumentList "/c $sgCmd" `
+        -WindowStyle Hidden -PassThru -ErrorAction Stop
+      $pidEntries += @{ name = $name; port = $port; pid = $proc.Id }
+      $started++
+      Write-Host "[START] $name on :$port (PID $($proc.Id))"
+    }
+    catch {
+      Write-Host "[ERROR] $name failed to start: $_"
+    }
+  }
+
+  # PID 파일 저장
+  if ($pidEntries.Count -gt 0) {
+    $pidEntries | ConvertTo-Json -Depth 3 | Set-Content -Path $PidFile -Encoding UTF8
+    Write-Host "`n[gateway] $started servers started. PID file: $PidFile"
+  }
+  else {
+    Write-Host "`n[gateway] No servers started (all running or skipped)"
+    return
+  }
+
+  # 헬스체크 (3초 대기 후)
+  Write-Host "`n[gateway] Waiting 3s for startup..."
+  Start-Sleep -Seconds 3
+
+  Write-Host "`nHealth Check"
+  Write-Host ('=' * 50)
+  foreach ($entry in $pidEntries) {
+    $url = "http://127.0.0.1:$($entry.port)/healthz"
+    try {
+      $resp = Invoke-WebRequest -Uri $url -UseBasicParsing -TimeoutSec 3 -ErrorAction Stop
+      $status = if ($resp.StatusCode -eq 200) { 'ok' } else { 'error' }
+      $mark = if ($status -eq 'ok') { [char]0x2713 } else { [char]0x2717 }
+      Write-Host ("  {0,-16} :{1}  {2} {3}" -f $entry.name, $entry.port, $mark, $status)
+    }
+    catch {
+      Write-Host ("  {0,-16} :{1}  {2} down" -f $entry.name, $entry.port, [char]0x2717)
+    }
+  }
+}
+
+# ── main ──
+if ($Stop) {
+  Stop-AllGateways
+}
+else {
+  Start-AllGateways
+}

package/scripts/mcp-gateway-verify.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// mcp-gateway-verify.mjs — supergateway SSE 엔드포인트 헬스체크
+
+const ENDPOINTS = [
+  { name: 'context7',     port: 8100 },
+  { name: 'brave-search', port: 8101 },
+  { name: 'exa',          port: 8102 },
+  { name: 'tavily',       port: 8103 },
+  { name: 'jira',         port: 8104 },
+  { name: 'serena',       port: 8105 },
+  { name: 'notion',       port: 8106 },
+  { name: 'notion-guest', port: 8107 },
+];
+
+async function checkHealth(name, port) {
+  const start = Date.now();
+  try {
+    const res = await fetch(`http://localhost:${port}/healthz`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    const latencyMs = Date.now() - start;
+    return res.ok
+      ? { name, port, status: 'ok', latencyMs, error: null }
+      : { name, port, status: 'down', latencyMs, error: `HTTP ${res.status}` };
+  } catch (err) {
+    const latencyMs = Date.now() - start;
+    const message = err?.cause?.code || err?.message || 'unknown';
+    return { name, port, status: 'down', latencyMs, error: message };
+  }
+}
+
+async function main() {
+  const results = await Promise.allSettled(
+    ENDPOINTS.map(({ name, port }) => checkHealth(name, port)),
+  );
+
+  const entries = results.map((r) =>
+    r.status === 'fulfilled' ? r.value : { name: '?', port: 0, status: 'down', error: r.reason },
+  );
+
+  console.log('\nMCP Gateway Health Check');
+  console.log('='.repeat(56));
+
+  let downCount = 0;
+  for (const e of entries) {
+    const mark = e.status === 'ok' ? '\u2713' : '\u2717';
+    const detail = e.status === 'ok' ? `(${e.latencyMs}ms)` : `(${e.error})`;
+    const line = `  ${e.name.padEnd(16)} :${String(e.port).padEnd(6)} ${mark} ${e.status.padEnd(6)} ${detail}`;
+    console.log(line);
+    if (e.status !== 'ok') downCount++;
+  }
+
+  console.log('='.repeat(56));
+  console.log(
+    downCount === 0
+      ? `All ${entries.length} gateways healthy`
+      : `${downCount}/${entries.length} gateways down`,
+  );
+
+  process.exit(downCount > 0 ? 1 : 0);
+}
+
+main();

package/scripts/setup.mjs

@@ -144,6 +144,11 @@ const SYNC_MAP = [
     dst: join(CLAUDE_DIR, "scripts", "hub", "workers", "factory.mjs"),
     label: "hub/workers/factory.mjs",
   },
+  {
+    src: join(PLUGIN_ROOT, "scripts", "mcp-cleanup.ps1"),
+    dst: join(CLAUDE_DIR, "scripts", "mcp-cleanup.ps1"),
+    label: "mcp-cleanup.ps1",
+  },
   {
     src: join(PLUGIN_ROOT, "hud", "hud-qos-status.mjs"),
     dst: join(CLAUDE_DIR, "hud", "hud-qos-status.mjs"),
@@ -580,6 +585,44 @@ function applyHooks(s) {
     changed = true;
   }
 
+  // ── Stop 훅: MCP 고아 프로세스 정리 (Windows 전용) ──
+  if (process.platform === "win32") {
+    if (!Array.isArray(s.hooks.Stop)) s.hooks.Stop = [];
+
+    const cleanupScriptPath = join(CLAUDE_DIR, "scripts", "mcp-cleanup.ps1").replace(/\\/g, "/");
+    const hasCleanupHook = s.hooks.Stop.some((entry) =>
+      Array.isArray(entry.hooks) &&
+      entry.hooks.some((h) => typeof h.command === "string" && h.command.includes("mcp-cleanup")),
+    );
+
+    if (!hasCleanupHook && existsSync(cleanupScriptPath.replace(/\//g, "\\"))) {
+      // 기존 Stop 엔트리가 있으면 거기에 추가, 없으면 새 엔트리 생성
+      const existingEntry = s.hooks.Stop.find((entry) => entry.matcher === "*" && Array.isArray(entry.hooks));
+      const cleanupHook = {
+        type: "command",
+        command: `powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File "${cleanupScriptPath}"`,
+        timeout: 8,
+      };
+
+      if (existingEntry) {
+        existingEntry.hooks.push(cleanupHook);
+      } else {
+        s.hooks.Stop.push({ matcher: "*", hooks: [cleanupHook] });
+      }
+      changed = true;
+    } else if (hasCleanupHook) {
+      for (const entry of s.hooks.Stop) {
+        if (!Array.isArray(entry.hooks)) continue;
+        for (const h of entry.hooks) {
+          if (typeof h.command === "string" && h.command.includes("mcp-cleanup") && !h.command.includes(cleanupScriptPath)) {
+            h.command = `powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File "${cleanupScriptPath}"`;
+            changed = true;
+          }
+        }
+      }
+    }
+  }
+
   // ── PreToolUse 훅: headless-guard (auto-route) ──
   if (!Array.isArray(s.hooks.PreToolUse)) s.hooks.PreToolUse = [];
 

package/skills/tfx-remote-setup/SKILL.md

@@ -337,7 +337,49 @@ options:
 
 저장 후 결과 보고.
 
-**2-8. 후속 작업**
+**2-8. MCP 고아 프로세스 정리 훅 배포 (Windows 원격 호스트)**
+
+원격 호스트가 Windows인 경우, MCP 고아 프로세스 정리 훅을 자동 배포한다.
+Claude Code 세션 종료 시 MCP 서버 프로세스가 정리되지 않는 Windows 고유 버그 대응.
+(GitHub Issues #1935, #15211, #28126)
+
+```bash
+# mcp-cleanup.ps1 배포
+scp "$(npm root -g)/triflux/scripts/mcp-cleanup.ps1" {host}:~/.claude/scripts/mcp-cleanup.ps1
+```
+
+배포 후 원격 호스트의 `~/.claude/settings.json`에 Stop 훅을 등록한다:
+
+```bash
+ssh {host} "node -e \"
+  const fs = require('fs');
+  const p = require('path').join(require('os').homedir(), '.claude', 'settings.json');
+  const s = JSON.parse(fs.readFileSync(p, 'utf8'));
+  if (!s.hooks) s.hooks = {};
+  if (!Array.isArray(s.hooks.Stop)) s.hooks.Stop = [];
+  const has = s.hooks.Stop.some(e => e.hooks?.some(h => h.command?.includes('mcp-cleanup')));
+  if (!has) {
+    const script = require('path').join(require('os').homedir(), '.claude/scripts/mcp-cleanup.ps1').replace(/\\\\\\\\/g, '/');
+    const entry = s.hooks.Stop.find(e => e.matcher === '*' && Array.isArray(e.hooks));
+    const hook = { type: 'command', command: 'powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File \\\"' + script + '\\\"', timeout: 8 };
+    if (entry) entry.hooks.push(hook); else s.hooks.Stop.push({ matcher: '*', hooks: [hook] });
+    fs.writeFileSync(p, JSON.stringify(s, null, 2) + '\\n');
+    console.log('mcp-cleanup hook registered');
+  } else { console.log('mcp-cleanup hook already exists'); }
+\""
+```
+
+macOS/Linux 원격 호스트에서는 이 단계를 건너뛴다 (PGID 기반 kill이 정상 동작).
+
+프로브 결과에서 OS를 확인하여 자동 판단:
+- Windows → 배포 실행
+- macOS/Linux → 건너뛰기 (표시만)
+
+```
+"{host}는 Windows입니다. MCP 고아 프로세스 정리 훅을 배포합니다."
+```
+
+**2-9. 후속 작업**
 
 ```
 question: "호스트가 등록되었습니다. 추가 작업이 있습니까?"