@luanpdd/kit-mcp 1.28.0 → 1.29.0

package/kit/file-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.28.0",
-  "timestamp": "2026-05-12T12:13:30.244Z",
+  "version": "1.29.0",
+  "timestamp": "2026-05-12T13:38:43.278Z",
   "files": {
     "COMANDOS.md": "d24ec61a6ec35db314cc5f2ae287bfb927b794789c8f1d558c55862f5e6534b2",
     "COMPATIBILITY.md": "794e336a87045cdf0161785b9a7a0975a49abbd80bdd816b8852251fcc8126ca",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Generic infrastructure to ship YOUR personal kit of agents/commands/skills as an MCP server, with cross-IDE sync (Claude Code, Cursor, Codex, Gemini, Windsurf, Antigravity, Copilot, Trae).",
   "type": "module",
   "bin": {

package/src/cli/index.js

@@ -708,6 +708,39 @@ async function runDoctorChecks(projectRoot) {
       : 'enabled (default) — sidecar starts when MCP server boots',
     fix: noUi ? 'unset KIT_MCP_NO_UI if you want live tool-call visibility' : undefined });
 
+  // 10. (v1.29) auto-install drift check — is .claude/.kit-mcp-version aligned
+  // with the running kit-mcp package version?
+  try {
+    const versionMarker = path.join(projectRoot, '.claude', '.kit-mcp-version');
+    const restartMarker = path.join(projectRoot, '.claude', '.kit-mcp-restart-required');
+    let installedVersion = null;
+    try { installedVersion = fs.readFileSync(versionMarker, 'utf8').trim(); } catch { /* not installed */ }
+    const currentVersion = readPkgVersion();
+
+    if (!installedVersion) {
+      checks.push({ label: 'auto-install', status: 'warn',
+        detail: '.claude/.kit-mcp-version not found — kit not auto-installed in this project',
+        fix: 'call kit:auto-install MCP tool, or run: kit init' });
+    } else if (installedVersion !== currentVersion) {
+      checks.push({ label: 'auto-install', status: 'warn',
+        detail: `kit installed v${installedVersion}, MCP server is v${currentVersion}`,
+        fix: 'call kit:auto-install (idempotent) or rerun: kit sync claude-code' });
+    } else {
+      checks.push({ label: 'auto-install', status: 'pass',
+        detail: `v${installedVersion} (in sync)` });
+    }
+
+    if (fs.existsSync(restartMarker)) {
+      let payload = {};
+      try { payload = JSON.parse(fs.readFileSync(restartMarker, 'utf8')); } catch { /* malformed */ }
+      checks.push({ label: 'restart pending', status: 'warn',
+        detail: payload.reason
+          ? `${payload.reason} (written ${payload.writtenAt || 'unknown'})`
+          : 'restart marker present — IDE not yet reloaded since last auto-install',
+        fix: 'restart your IDE session, then call kit:ack-restart MCP tool (or just close/reopen)' });
+    }
+  } catch { /* .claude/ check is best-effort */ }
+
   return checks;
 }
 

package/src/mcp-server/index.js

@@ -34,11 +34,16 @@ import { wrapProgressForUi } from '../ui/wrapper.js';
 import { incrementInvocation, recordLatency, snapshot as metricsSnapshot, persistSnapshot } from '../core/metrics.js';
 import { logEvent } from '../core/logger.js';
 import { notify, isNotifyEnabled } from '../core/notify.js';
+// Note: roots.js is imported dynamically inside handlers that need it
+// (handleAutoInstall, handleAckRestart) — keeps boot path minimal.
 
 const TOOLS = [
   {
     name: 'kit',
-    description: 'Browse the personal kit: agents, commands, skills.',
+    // Phase 170 (v1.29): description enriched with trigger keywords so MCP
+    // hosts route here on relevant intents even in MCP-pure mode (before
+    // auto-install made .claude/ native). Keep under 1024 chars (host limit).
+    description: 'Browse the personal kit: 66 agents, 89 commands, 76 skills. Call this when the user mentions Supabase (RLS, branching, migrations, Edge Functions, Custom Claims, Postgres Roles, Storage, Realtime, pgvector), multi-tenant SaaS, agentic harness, characterization tests, legacy refactor, observability (SLO, golden signals, error budgets), DDIA topics (consistency, replication lag, schema evolution), SRE (postmortems, toil, PRR), CI/CD (hermetic builds, pipelines), or any workflow that benefits from the canonical patterns. Use action=search to discover, action=get to read the full prompt/skill.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -145,6 +150,37 @@ const TOOLS = [
       properties: {},
     },
   },
+  {
+    // Phase 167 (v1.29): auto-sync the kit content into the host project's
+    // .claude/ (or equivalent) directory so agents become real subagent_types,
+    // skills get native auto-trigger, and commands appear as slash-commands.
+    // Idempotent — re-runs are no-ops if .claude/.kit-mcp-version matches the
+    // running server's package version. Permission-gated by the host.
+    name: 'auto-install',
+    description: 'IMPORTANT for first contact: project kit/ into the host\'s native layout (.claude/agents/, skills/, commands/) so 66 agents become real subagent_types in the Agent tool, 76 skills get native auto-trigger via descriptions, and 89 commands appear as /slash-commands in the IDE. Idempotent — re-running is a no-op if already in sync. Run once per project on first kit-mcp contact; restart the IDE session after to load the new agents/skills/commands. After restart, call ack-restart to clear the marker.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action:      { type: 'string', enum: ['install', 'check'], description: 'install: write files. check: read-only drift report. Default: install.' },
+        target:      { type: 'string', description: 'IDE id (claude-code, cursor, …). Defaults to claude-code.' },
+        projectRoot: { type: 'string', description: 'Override the auto-detected project root. Usually omitted — server reads it from MCP roots capability.' },
+        force:       { type: 'boolean', description: 'Re-write even if .kit-mcp-version already matches. Default: false.' },
+      },
+    },
+  },
+  {
+    // Phase 168 (v1.29): acknowledge the restart-required marker after the
+    // user reloads the IDE session. Removes .claude/.kit-mcp-restart-required
+    // so doctor stops flagging it.
+    name: 'ack-restart',
+    description: 'Acknowledge that the IDE session was restarted after kit:auto-install. Removes the .kit-mcp-restart-required marker so kit:doctor stops warning. Called automatically by the harness when it detects the marker after reload, or manually by the user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectRoot: { type: 'string' },
+      },
+    },
+  },
 ];
 
 // DRIFT-13-03: read version from package.json at module load (NOT inside
@@ -318,6 +354,163 @@ async function handleInstall(args) {
 let _lastAutoPersistTs = 0;
 const AUTO_PERSIST_THROTTLE_MS = 1000;
 
+// Phase 167 (v1.29): auto-install handler.
+// Bridges MCP → host-native integration by writing kit/ files into .claude/
+// (or whatever the target IDE expects). Idempotent via .kit-mcp-version marker.
+// Phase 168 hooks add the restart_recommended signal to the result.
+async function handleAutoInstall(args) {
+  const action = args.action || 'install';
+  const target = args.target || 'claude-code';
+  const force = !!args.force;
+
+  // Resolve projectRoot: explicit arg > cwd fallback. (Future v1.30 will add
+  // MCP `roots` capability consumer for a tighter projectRoot signal — for now
+  // we use cwd to keep the boot path race-free with the SDK init handshake.)
+  let projectRoot = args.projectRoot;
+  const _rootsSource = projectRoot ? 'explicit' : 'cwd';
+  if (!projectRoot) projectRoot = process.cwd();
+
+  // SEC-14-03: validate project root (allowlist-of-1 — must be a real dir).
+  const guard = await validateProjectRoot(projectRoot);
+  if (!guard.ok) {
+    return { ok: false, reason: guard.reason, projectRoot, rootsSource: _rootsSource };
+  }
+  projectRoot = guard.resolvedPath;
+
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const markerPath = path.join(projectRoot, '.claude', '.kit-mcp-version');
+
+  // Read current marker if present.
+  let currentVersion = null;
+  try {
+    currentVersion = (await fs.readFile(markerPath, 'utf8')).trim();
+  } catch { /* not installed yet */ }
+
+  const targetVersion = PKG_VERSION;
+  const inSync = currentVersion === targetVersion;
+
+  // Phase 167 — action=check: read-only drift report.
+  if (action === 'check') {
+    return {
+      ok: true,
+      action: 'check',
+      target,
+      projectRoot,
+      rootsSource: _rootsSource,
+      installedVersion: currentVersion,
+      currentVersion: targetVersion,
+      inSync,
+      restartRecommended: false,
+    };
+  }
+
+  // action=install: skip if in sync and not forced.
+  if (inSync && !force) {
+    return {
+      ok: true,
+      action: 'install',
+      target,
+      projectRoot,
+      rootsSource: _rootsSource,
+      version: targetVersion,
+      skipped: true,
+      reason: 'already in sync',
+      restartRecommended: false,
+    };
+  }
+
+  // Run the sync.
+  let syncResult;
+  try {
+    syncResult = await syncTo(target, { projectRoot, mode: 'reference', dryRun: false });
+  } catch (e) {
+    return {
+      ok: false,
+      action: 'install',
+      target,
+      projectRoot,
+      rootsSource: _rootsSource,
+      reason: `sync_failed: ${e.message}`,
+    };
+  }
+
+  // Write/update marker file (.claude/.kit-mcp-version).
+  try {
+    await fs.mkdir(path.dirname(markerPath), { recursive: true });
+    await fs.writeFile(markerPath, targetVersion + '\n', 'utf8');
+  } catch (e) {
+    // Marker is best-effort — sync already succeeded. Just warn.
+    process.stderr.write(`[kit-mcp] auto-install marker write failed: ${e.message}\n`);
+  }
+
+  // Phase 168 (v1.29): write .kit-mcp-restart-required so doctor/host can detect
+  // pending restart even if the user closes/reopens kit-mcp without restarting IDE.
+  try {
+    const restartMarker = path.join(projectRoot, '.claude', '.kit-mcp-restart-required');
+    const payload = JSON.stringify({
+      version: targetVersion,
+      previousVersion: currentVersion,
+      writtenAt: new Date().toISOString(),
+      reason: currentVersion
+        ? `Kit updated ${currentVersion} → ${targetVersion}`
+        : 'Initial kit install',
+    }, null, 2);
+    await fs.writeFile(restartMarker, payload + '\n', 'utf8');
+  } catch (e) {
+    process.stderr.write(`[kit-mcp] restart marker write failed: ${e.message}\n`);
+  }
+
+  return {
+    ok: true,
+    action: 'install',
+    target,
+    projectRoot,
+    rootsSource: _rootsSource,
+    version: targetVersion,
+    previousVersion: currentVersion,
+    written: (syncResult.written || []).length,
+    restartRecommended: true,
+    _kit_action: 'session_restart_recommended',
+    _kit_reason: currentVersion
+      ? `Kit updated from ${currentVersion} to ${targetVersion} — restart the IDE session so agents/skills/commands reload.`
+      : `Kit installed (v${targetVersion}) into ${path.join('.claude', '')} — restart the IDE session for native subagent_type + slash-command + skill auto-trigger integration.`,
+  };
+}
+
+// Phase 168 (v1.29): acknowledge that the IDE was restarted after a kit:auto-install.
+// Removes the .kit-mcp-restart-required marker. Read by kit:doctor (Phase 171)
+// to stop flagging "pending restart".
+async function handleAckRestart(args) {
+  let projectRoot = args.projectRoot || process.cwd();
+
+  const guard = await validateProjectRoot(projectRoot);
+  if (!guard.ok) return { ok: false, reason: guard.reason, projectRoot };
+  projectRoot = guard.resolvedPath;
+
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const restartMarker = path.join(projectRoot, '.claude', '.kit-mcp-restart-required');
+
+  let acked = false;
+  try {
+    await fs.unlink(restartMarker);
+    acked = true;
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      return { ok: false, reason: `unlink_failed: ${e.message}`, projectRoot };
+    }
+    // ENOENT — nothing to ack, already clean. Not an error.
+  }
+
+  return {
+    ok: true,
+    projectRoot,
+    acked,
+    reason: acked ? 'restart marker removed' : 'no restart marker present (nothing to ack)',
+  };
+}
+
 async function handleMetricsSnapshot() {
   const payload = metricsSnapshot();
   const now = Date.now();
@@ -336,13 +529,22 @@ async function handleMetricsSnapshot() {
 }
 
 const HANDLERS = {
-  kit:               handleKit,
-  sync:              handleSync,
-  'reverse-sync':    handleReverseSync,
-  gates:             handleGates,
-  forensics:         handleForensics,
-  install:           handleInstall,
+  kit:                handleKit,
+  sync:               handleSync,
+  'reverse-sync':     handleReverseSync,
+  gates:              handleGates,
+  forensics:          handleForensics,
+  install:            handleInstall,
   'metrics-snapshot': handleMetricsSnapshot,
+  'auto-install':     handleAutoInstall,
+  'ack-restart':      handleAckRestart,
+};
+
+// Phase 167+168 test affordances — exported for unit coverage.
+// Production callers should go through the MCP dispatch (HANDLERS map).
+export const __TEST_HANDLERS = {
+  handleAutoInstall,
+  handleAckRestart,
 };
 
 function slim(x) {
@@ -365,7 +567,7 @@ function slimTerse(x) {
 export async function createServer() {
   const server = new Server(
     { name: 'kit-mcp', version: PKG_VERSION },
-    { capabilities: { tools: {} } }
+    { capabilities: { tools: {} } },
   );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
@@ -457,6 +659,7 @@ export async function startStdio() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 
+
   // SRE-20-02 (Phase 105): pre-warm the kit cache to push MCP dispatch p95
   // below 100ms. Without this, the very first tools/call against `kit` pays
   // the full disk read (~144ms baseline on the v1.17 reference machine; ~96ms

package/src/mcp-server/roots.js

@@ -0,0 +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';
+}