@luanpdd/kit-mcp 1.34.0 → 1.36.0

package/src/mcp-server/roots.js

@@ -1,124 +1,124 @@
-// src/mcp-server/roots.js — MCP `roots` capability consumer.
-//
-// Phase 166 (v1.29). The MCP spec lets clients (hosts like Claude Code,
-// Cursor) declare workspace roots via `roots/list`. Servers can query this
-// to learn the project directory without guessing from `process.cwd()`.
-//
-// Flow:
-//   1. Server declares capability `roots: { listChanged: true }` on init.
-//   2. After `initialized` notification, server sends `roots/list` request.
-//   3. Cache the response in memory.
-//   4. Listen for `notifications/roots/list_changed` to refresh cache.
-//
-// Discipline:
-//   - Failures are silent — fallback to process.cwd() if host doesn't support.
-//   - Cache survives the session; not persisted to disk.
-//   - No side effects (the auto-sync that USES the roots lives in another module).
-
-import { ListRootsRequestSchema, RootsListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
-import { fileURLToPath } from 'node:url';
-
-// Module-level cache. Keyed by server instance via closure in attachRootsCapability.
-let cachedRoots = null;
-let supportLevel = 'unknown'; // 'supported' | 'unsupported' | 'unknown'
-
-/**
- * Convert a file:// URI to a local filesystem path. Returns null if invalid.
- * @param {string} uri
- */
-function uriToPath(uri) {
-  if (typeof uri !== 'string') return null;
-  if (!uri.startsWith('file://')) return null;
-  try {
-    return fileURLToPath(uri);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Request roots/list from the connected client. Caches the result.
- * Returns array of {uri, name, path} entries, or [] on failure.
- * @param {import('@modelcontextprotocol/sdk/server/index.js').Server} server
- */
-export async function fetchRoots(server) {
-  try {
-    const result = await server.request(
-      { method: 'roots/list' },
-      // The SDK validates the response shape with this schema
-      // eslint-disable-next-line no-undef
-      // @ts-ignore — runtime-only import shape
-      undefined,
-    );
-    // Defensive: SDK may return either {roots: [...]} or the bare array depending on version
-    const roots = Array.isArray(result?.roots) ? result.roots
-      : Array.isArray(result) ? result
-      : [];
-    const normalized = roots.map((r) => ({
-      uri: r.uri,
-      name: r.name,
-      path: uriToPath(r.uri),
-    })).filter((r) => r.path);
-    cachedRoots = normalized;
-    supportLevel = 'supported';
-    return normalized;
-  } catch (e) {
-    // Client doesn't support roots, or returned an error.
-    supportLevel = 'unsupported';
-    cachedRoots = [];
-    return [];
-  }
-}
-
-/**
- * Attach roots capability handlers to the server. Must be called BEFORE
- * server.connect(). Sets up the list_changed listener so cache stays fresh.
- * @param {import('@modelcontextprotocol/sdk/server/index.js').Server} server
- */
-export function attachRootsCapability(server) {
-  // Listen for client telling us roots changed — invalidate cache.
-  server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
-    // Re-fetch on next access via fetchRoots(). Mark cache stale.
-    cachedRoots = null;
-    // Eager refresh — best-effort.
-    try { await fetchRoots(server); } catch { /* swallow */ }
-  });
-}
-
-/**
- * Get the currently-cached roots, or trigger a fetch if not yet cached.
- * Returns array of {uri, name, path}.
- * @param {import('@modelcontextprotocol/sdk/server/index.js').Server} server
- */
-export async function getRoots(server) {
-  if (cachedRoots !== null) return cachedRoots;
-  return await fetchRoots(server);
-}
-
-/**
- * Get the primary project root path. Falls back to process.cwd() if no
- * roots were declared by the client. Synchronous accessor for use AFTER
- * fetchRoots() has been called at least once.
- */
-export function getPrimaryProjectRoot() {
-  if (cachedRoots && cachedRoots.length > 0) {
-    return cachedRoots[0].path;
-  }
-  return process.cwd();
-}
-
-/**
- * Diagnostic helper — exposes whether host declared roots support.
- * Values: 'supported' | 'unsupported' | 'unknown'.
- */
-export function getRootsSupportLevel() {
-  return supportLevel;
-}
-
-/**
- * Reset state. Test helper only.
- */
-export function __resetForTests() {
-  cachedRoots = null;
-  supportLevel = 'unknown';
-}
+// src/mcp-server/roots.js — MCP `roots` capability consumer.
+//
+// Phase 166 (v1.29). The MCP spec lets clients (hosts like Claude Code,
+// Cursor) declare workspace roots via `roots/list`. Servers can query this
+// to learn the project directory without guessing from `process.cwd()`.
+//
+// Flow:
+//   1. Server declares capability `roots: { listChanged: true }` on init.
+//   2. After `initialized` notification, server sends `roots/list` request.
+//   3. Cache the response in memory.
+//   4. Listen for `notifications/roots/list_changed` to refresh cache.
+//
+// Discipline:
+//   - Failures are silent — fallback to process.cwd() if host doesn't support.
+//   - Cache survives the session; not persisted to disk.
+//   - No side effects (the auto-sync that USES the roots lives in another module).
+
+import { ListRootsRequestSchema, RootsListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { fileURLToPath } from 'node:url';
+
+// Module-level cache. Keyed by server instance via closure in attachRootsCapability.
+let cachedRoots = null;
+let supportLevel = 'unknown'; // 'supported' | 'unsupported' | 'unknown'
+
+/**
+ * Convert a file:// URI to a local filesystem path. Returns null if invalid.
+ * @param {string} uri
+ */
+function uriToPath(uri) {
+  if (typeof uri !== 'string') return null;
+  if (!uri.startsWith('file://')) return null;
+  try {
+    return fileURLToPath(uri);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Request roots/list from the connected client. Caches the result.
+ * Returns array of {uri, name, path} entries, or [] on failure.
+ * @param {import('@modelcontextprotocol/sdk/server/index.js').Server} server
+ */
+export async function fetchRoots(server) {
+  try {
+    const result = await server.request(
+      { method: 'roots/list' },
+      // The SDK validates the response shape with this schema
+      // eslint-disable-next-line no-undef
+      // @ts-ignore — runtime-only import shape
+      undefined,
+    );
+    // Defensive: SDK may return either {roots: [...]} or the bare array depending on version
+    const roots = Array.isArray(result?.roots) ? result.roots
+      : Array.isArray(result) ? result
+      : [];
+    const normalized = roots.map((r) => ({
+      uri: r.uri,
+      name: r.name,
+      path: uriToPath(r.uri),
+    })).filter((r) => r.path);
+    cachedRoots = normalized;
+    supportLevel = 'supported';
+    return normalized;
+  } catch (e) {
+    // Client doesn't support roots, or returned an error.
+    supportLevel = 'unsupported';
+    cachedRoots = [];
+    return [];
+  }
+}
+
+/**
+ * Attach roots capability handlers to the server. Must be called BEFORE
+ * server.connect(). Sets up the list_changed listener so cache stays fresh.
+ * @param {import('@modelcontextprotocol/sdk/server/index.js').Server} server
+ */
+export function attachRootsCapability(server) {
+  // Listen for client telling us roots changed — invalidate cache.
+  server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+    // Re-fetch on next access via fetchRoots(). Mark cache stale.
+    cachedRoots = null;
+    // Eager refresh — best-effort.
+    try { await fetchRoots(server); } catch { /* swallow */ }
+  });
+}
+
+/**
+ * Get the currently-cached roots, or trigger a fetch if not yet cached.
+ * Returns array of {uri, name, path}.
+ * @param {import('@modelcontextprotocol/sdk/server/index.js').Server} server
+ */
+export async function getRoots(server) {
+  if (cachedRoots !== null) return cachedRoots;
+  return await fetchRoots(server);
+}
+
+/**
+ * Get the primary project root path. Falls back to process.cwd() if no
+ * roots were declared by the client. Synchronous accessor for use AFTER
+ * fetchRoots() has been called at least once.
+ */
+export function getPrimaryProjectRoot() {
+  if (cachedRoots && cachedRoots.length > 0) {
+    return cachedRoots[0].path;
+  }
+  return process.cwd();
+}
+
+/**
+ * Diagnostic helper — exposes whether host declared roots support.
+ * Values: 'supported' | 'unsupported' | 'unknown'.
+ */
+export function getRootsSupportLevel() {
+  return supportLevel;
+}
+
+/**
+ * Reset state. Test helper only.
+ */
+export function __resetForTests() {
+  cachedRoots = null;
+  supportLevel = 'unknown';
+}

package/src/ui/auto-spawn.js

@@ -1,113 +1,113 @@
-// src/ui/auto-spawn.js
-// Spawn the sidecar in a detached subprocess and wait until it's healthy.
-// Used by MCP tool handlers when the caller passes `autoSpawn: true` and no
-// sidecar lockfile is present for the project.
-//
-// Discipline: stderr/file logging only. Audit gate enforced.
-
-import { spawn } from 'node:child_process';
-import http from 'node:http';
-import path from 'node:path';
-import process from 'node:process';
-import { fileURLToPath } from 'node:url';
-
-import { readLock } from './lockfile.js';
-import { openBrowser } from './browser.js';
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-// src/ui → src → repo root → bin/ui.js
-const UI_BIN = path.resolve(HERE, '..', '..', 'bin', 'ui.js');
-
-const POLL_INTERVAL_MS = 100;
-const POLL_TIMEOUT_MS = 5000;
-
-// healthzOk returns true if GET /healthz on this port responds 200 within 1s.
-function healthzOk(port) {
-  return new Promise((resolve) => {
-    const req = http.request({
-      method: 'GET',
-      host: '127.0.0.1',
-      port,
-      path: '/healthz',
-      agent: false,
-      headers: { host: `127.0.0.1:${port}`, connection: 'close' },
-    }, (res) => {
-      res.resume();
-      res.on('end', () => resolve(res.statusCode === 200));
-    });
-    req.on('error', () => resolve(false));
-    req.setTimeout(800, () => { try { req.destroy(); } catch { /* noop */ } resolve(false); });
-    req.end();
-  });
-}
-
-async function waitForHealth(projectRoot, deadline) {
-  // Poll for lockfile + healthz until deadline.
-  while (Date.now() < deadline) {
-    const lock = readLock(projectRoot);
-    if (lock?.port) {
-      // eslint-disable-next-line no-await-in-loop
-      if (await healthzOk(lock.port)) return lock;
-    }
-    // eslint-disable-next-line no-await-in-loop
-    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
-  }
-  return null;
-}
-
-// ensureSidecar({projectRoot, openBrowser?}): if a sidecar is already running
-// for this projectRoot, returns immediately with its lock metadata. Otherwise
-// spawns bin/ui.js detached and waits for it to come online, then optionally
-// opens the browser. Resolves to:
-//   { ready: true, port, spawned: bool, opened: bool }   on success
-//   { ready: false, reason }                             on timeout/spawn-fail
-export async function ensureSidecar({ projectRoot, openBrowserOnSpawn = true } = {}) {
-  if (!projectRoot) return { ready: false, reason: 'no_project_root' };
-
-  // Already running?
-  const existing = readLock(projectRoot);
-  if (existing?.port) {
-    if (await healthzOk(existing.port)) {
-      return { ready: true, port: existing.port, spawned: false, opened: false };
-    }
-    // Stale lockfile — let the spawn step reclaim it.
-  }
-
-  // Spawn detached. Inherits stderr only — stdout is closed so a buggy child
-  // can never poison parent's stdout (e.g. when the parent is the MCP server
-  // running on stdio).
-  let child;
-  try {
-    child = spawn(process.execPath, [UI_BIN, '--project-root', projectRoot], {
-      detached: true,
-      stdio: ['ignore', 'ignore', 'inherit'],
-      windowsHide: true,
-    });
-    child.unref();
-  } catch (err) {
-    return { ready: false, reason: `spawn_failed: ${err.message}` };
-  }
-
-  // Wait for it to come online.
-  const deadline = Date.now() + POLL_TIMEOUT_MS;
-  const lock = await waitForHealth(projectRoot, deadline);
-  if (!lock) {
-    return { ready: false, reason: 'healthz_timeout' };
-  }
-
-  let opened = false;
-  if (openBrowserOnSpawn) {
-    // SEC-14-02: propagate auth token via query param so browser can self-authenticate
-    // without user interaction. EventSource cannot send custom headers; ?t= is the
-    // canonical pattern. The browser scrubs ?t= from the address bar via
-    // history.replaceState immediately on boot to avoid leak via screenshare.
-    const tokenSuffix = lock.token ? `?t=${encodeURIComponent(lock.token)}` : '';
-    const url = `http://127.0.0.1:${lock.port}/${tokenSuffix}`;
-    const r = await openBrowser(url);
-    opened = r.opened === true;
-  }
-
-  return { ready: true, port: lock.port, spawned: true, opened };
-}
-
-export const __test = { healthzOk, UI_BIN, POLL_INTERVAL_MS, POLL_TIMEOUT_MS };
+// src/ui/auto-spawn.js
+// Spawn the sidecar in a detached subprocess and wait until it's healthy.
+// Used by MCP tool handlers when the caller passes `autoSpawn: true` and no
+// sidecar lockfile is present for the project.
+//
+// Discipline: stderr/file logging only. Audit gate enforced.
+
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { readLock } from './lockfile.js';
+import { openBrowser } from './browser.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// src/ui → src → repo root → bin/ui.js
+const UI_BIN = path.resolve(HERE, '..', '..', 'bin', 'ui.js');
+
+const POLL_INTERVAL_MS = 100;
+const POLL_TIMEOUT_MS = 5000;
+
+// healthzOk returns true if GET /healthz on this port responds 200 within 1s.
+function healthzOk(port) {
+  return new Promise((resolve) => {
+    const req = http.request({
+      method: 'GET',
+      host: '127.0.0.1',
+      port,
+      path: '/healthz',
+      agent: false,
+      headers: { host: `127.0.0.1:${port}`, connection: 'close' },
+    }, (res) => {
+      res.resume();
+      res.on('end', () => resolve(res.statusCode === 200));
+    });
+    req.on('error', () => resolve(false));
+    req.setTimeout(800, () => { try { req.destroy(); } catch { /* noop */ } resolve(false); });
+    req.end();
+  });
+}
+
+async function waitForHealth(projectRoot, deadline) {
+  // Poll for lockfile + healthz until deadline.
+  while (Date.now() < deadline) {
+    const lock = readLock(projectRoot);
+    if (lock?.port) {
+      // eslint-disable-next-line no-await-in-loop
+      if (await healthzOk(lock.port)) return lock;
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+  return null;
+}
+
+// ensureSidecar({projectRoot, openBrowser?}): if a sidecar is already running
+// for this projectRoot, returns immediately with its lock metadata. Otherwise
+// spawns bin/ui.js detached and waits for it to come online, then optionally
+// opens the browser. Resolves to:
+//   { ready: true, port, spawned: bool, opened: bool }   on success
+//   { ready: false, reason }                             on timeout/spawn-fail
+export async function ensureSidecar({ projectRoot, openBrowserOnSpawn = true } = {}) {
+  if (!projectRoot) return { ready: false, reason: 'no_project_root' };
+
+  // Already running?
+  const existing = readLock(projectRoot);
+  if (existing?.port) {
+    if (await healthzOk(existing.port)) {
+      return { ready: true, port: existing.port, spawned: false, opened: false };
+    }
+    // Stale lockfile — let the spawn step reclaim it.
+  }
+
+  // Spawn detached. Inherits stderr only — stdout is closed so a buggy child
+  // can never poison parent's stdout (e.g. when the parent is the MCP server
+  // running on stdio).
+  let child;
+  try {
+    child = spawn(process.execPath, [UI_BIN, '--project-root', projectRoot], {
+      detached: true,
+      stdio: ['ignore', 'ignore', 'inherit'],
+      windowsHide: true,
+    });
+    child.unref();
+  } catch (err) {
+    return { ready: false, reason: `spawn_failed: ${err.message}` };
+  }
+
+  // Wait for it to come online.
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  const lock = await waitForHealth(projectRoot, deadline);
+  if (!lock) {
+    return { ready: false, reason: 'healthz_timeout' };
+  }
+
+  let opened = false;
+  if (openBrowserOnSpawn) {
+    // SEC-14-02: propagate auth token via query param so browser can self-authenticate
+    // without user interaction. EventSource cannot send custom headers; ?t= is the
+    // canonical pattern. The browser scrubs ?t= from the address bar via
+    // history.replaceState immediately on boot to avoid leak via screenshare.
+    const tokenSuffix = lock.token ? `?t=${encodeURIComponent(lock.token)}` : '';
+    const url = `http://127.0.0.1:${lock.port}/${tokenSuffix}`;
+    const r = await openBrowser(url);
+    opened = r.opened === true;
+  }
+
+  return { ready: true, port: lock.port, spawned: true, opened };
+}
+
+export const __test = { healthzOk, UI_BIN, POLL_INTERVAL_MS, POLL_TIMEOUT_MS };

package/src/ui/browser.js

@@ -1,78 +1,78 @@
-// src/ui/browser.js
-// Cross-platform browser opener. Wraps `open@11` with detection for environments
-// where launching a browser silently fails (CI, headless SSH, WSL, sandboxed
-// macOS Terminal). In those environments we DON'T attempt to launch — we just
-// print the URL to stderr so the user can copy it.
-//
-// Discipline: nothing on stdout. Audit gate enforced by Phase 11 CI.
-
-import process from 'node:process';
-
-let openModule = null;
-
-async function loadOpen() {
-  if (openModule) return openModule;
-  try {
-    const mod = await import('open');
-    openModule = mod.default || mod;
-    return openModule;
-  } catch (err) {
-    return null;
-  }
-}
-
-// isHeadless heuristics — designed to err on the side of NOT launching.
-// Returns a reason string when headless, or null when a browser launch is plausible.
-export function detectHeadless(env = process.env, plat = process.platform) {
-  if (env.CI && env.CI !== 'false') return 'CI=' + env.CI;
-  if (env.KIT_MCP_NO_OPEN === '1' || env.KIT_MCP_NO_OPEN === 'true') return 'KIT_MCP_NO_OPEN';
-  if (env.TERM === 'dumb') return 'TERM=dumb';
-  // Linux without a display server is headless. WSL is special: it forwards
-  // to the Windows host browser via wslview, so we let `open` try.
-  if (plat === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
-    if (env.WSL_DISTRO_NAME || env.WSLENV) return null; // WSL — let `open` try (it'll use wslview)
-    return 'no_display';
-  }
-  // SSH session without local display — no good way to open in user's browser.
-  if (env.SSH_CONNECTION && plat !== 'win32' && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
-    return 'ssh_no_display';
-  }
-  return null;
-}
-
-// openBrowser(url, opts):
-//   { opened: true,  via: 'open' }                    on success
-//   { opened: false, reason: 'headless:<why>', url }  when headless detected
-//   { opened: false, reason: 'no_module' }            if `open` package missing
-//   { opened: false, reason: 'launch_failed:<msg>' }  if open() throws
-//
-// Always calls process.stderr.write with the URL so the user can copy it manually.
-export async function openBrowser(url, { force = false } = {}) {
-  process.stderr.write(`[kit-mcp ui] ${url}\n`);
-
-  if (!force) {
-    const headless = detectHeadless();
-    if (headless) {
-      process.stderr.write(`[kit-mcp ui] not opening browser (${headless}) — open the URL above manually\n`);
-      return { opened: false, reason: `headless:${headless}`, url };
-    }
-  }
-
-  const open = await loadOpen();
-  if (!open) {
-    process.stderr.write('[kit-mcp ui] `open` package not available — open the URL above manually\n');
-    return { opened: false, reason: 'no_module' };
-  }
-
-  try {
-    // open() returns a child process; we don't await its exit (it's the browser).
-    // We just need to know that the spawn succeeded.
-    await open(url);
-    return { opened: true, via: 'open' };
-  } catch (err) {
-    process.stderr.write(`[kit-mcp ui] browser launch failed: ${err.message} — open the URL above manually\n`);
-    return { opened: false, reason: `launch_failed:${err.message}` };
-  }
-}
-
-export const __test = { loadOpen };
+// src/ui/browser.js
+// Cross-platform browser opener. Wraps `open@11` with detection for environments
+// where launching a browser silently fails (CI, headless SSH, WSL, sandboxed
+// macOS Terminal). In those environments we DON'T attempt to launch — we just
+// print the URL to stderr so the user can copy it.
+//
+// Discipline: nothing on stdout. Audit gate enforced by Phase 11 CI.
+
+import process from 'node:process';
+
+let openModule = null;
+
+async function loadOpen() {
+  if (openModule) return openModule;
+  try {
+    const mod = await import('open');
+    openModule = mod.default || mod;
+    return openModule;
+  } catch (err) {
+    return null;
+  }
+}
+
+// isHeadless heuristics — designed to err on the side of NOT launching.
+// Returns a reason string when headless, or null when a browser launch is plausible.
+export function detectHeadless(env = process.env, plat = process.platform) {
+  if (env.CI && env.CI !== 'false') return 'CI=' + env.CI;
+  if (env.KIT_MCP_NO_OPEN === '1' || env.KIT_MCP_NO_OPEN === 'true') return 'KIT_MCP_NO_OPEN';
+  if (env.TERM === 'dumb') return 'TERM=dumb';
+  // Linux without a display server is headless. WSL is special: it forwards
+  // to the Windows host browser via wslview, so we let `open` try.
+  if (plat === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+    if (env.WSL_DISTRO_NAME || env.WSLENV) return null; // WSL — let `open` try (it'll use wslview)
+    return 'no_display';
+  }
+  // SSH session without local display — no good way to open in user's browser.
+  if (env.SSH_CONNECTION && plat !== 'win32' && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+    return 'ssh_no_display';
+  }
+  return null;
+}
+
+// openBrowser(url, opts):
+//   { opened: true,  via: 'open' }                    on success
+//   { opened: false, reason: 'headless:<why>', url }  when headless detected
+//   { opened: false, reason: 'no_module' }            if `open` package missing
+//   { opened: false, reason: 'launch_failed:<msg>' }  if open() throws
+//
+// Always calls process.stderr.write with the URL so the user can copy it manually.
+export async function openBrowser(url, { force = false } = {}) {
+  process.stderr.write(`[kit-mcp ui] ${url}\n`);
+
+  if (!force) {
+    const headless = detectHeadless();
+    if (headless) {
+      process.stderr.write(`[kit-mcp ui] not opening browser (${headless}) — open the URL above manually\n`);
+      return { opened: false, reason: `headless:${headless}`, url };
+    }
+  }
+
+  const open = await loadOpen();
+  if (!open) {
+    process.stderr.write('[kit-mcp ui] `open` package not available — open the URL above manually\n');
+    return { opened: false, reason: 'no_module' };
+  }
+
+  try {
+    // open() returns a child process; we don't await its exit (it's the browser).
+    // We just need to know that the spawn succeeded.
+    await open(url);
+    return { opened: true, via: 'open' };
+  } catch (err) {
+    process.stderr.write(`[kit-mcp ui] browser launch failed: ${err.message} — open the URL above manually\n`);
+    return { opened: false, reason: `launch_failed:${err.message}` };
+  }
+}
+
+export const __test = { loadOpen };