@karajan-family/code 4.21.0

package/src/mcp/orphan-guard.js

@@ -0,0 +1,131 @@
+import { readFileSync, writeFileSync, unlinkSync, watch, mkdirSync, existsSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const RESTART_MARKER_DIR = path.join(os.homedir(), ".kj");
+const RESTART_MARKER_PATH = path.join(RESTART_MARKER_DIR, ".mcp-restart");
+
+const DEFAULT_INTERVAL_MS = 5000;
+
+export function setupOrphanGuard({ intervalMs = DEFAULT_INTERVAL_MS, exitFn = () => process.exit(0) } = {}) {
+  const parentPid = process.ppid;
+
+  const timer = setInterval(() => {
+    try {
+      process.kill(parentPid, 0);
+    } catch { /* parent process is gone */
+      clearInterval(timer);
+      exitFn();
+    }
+  }, intervalMs);
+  timer.unref();
+
+  process.stdin.on("end", exitFn);
+  process.stdin.on("close", exitFn);
+  process.on("SIGHUP", exitFn);
+
+  return { timer, parentPid };
+}
+
+const DEFAULT_MEMORY_CHECK_MS = 30_000;
+const DEFAULT_WARN_HEAP_MB = 512;
+const DEFAULT_CRITICAL_HEAP_MB = 768;
+
+export function setupMemoryWatchdog({
+  intervalMs = DEFAULT_MEMORY_CHECK_MS,
+  warnHeapMb = DEFAULT_WARN_HEAP_MB,
+  criticalHeapMb = DEFAULT_CRITICAL_HEAP_MB,
+  onWarn = null,
+  onCritical = null,
+  exitFn = () => process.exit(1)
+} = {}) {
+  const warnBytes = warnHeapMb * 1024 * 1024;
+  const criticalBytes = criticalHeapMb * 1024 * 1024;
+  let warned = false;
+
+  const timer = setInterval(() => {
+    const { heapUsed, rss } = process.memoryUsage();
+
+    if (heapUsed >= criticalBytes) {
+      if (global.gc) {
+        try { global.gc(); } catch { /* --expose-gc not set */ }
+        const after = process.memoryUsage().heapUsed;
+        if (after < criticalBytes) return; // GC freed enough
+      }
+      const msg = `Memory critical: heap ${(heapUsed / 1024 / 1024).toFixed(0)}MB / rss ${(rss / 1024 / 1024).toFixed(0)}MB — exiting to prevent OOM`;
+      if (onCritical) onCritical(msg);
+      else process.stderr.write(`[karajan-mcp] ${msg}\n`);
+      clearInterval(timer);
+      exitFn();
+      return;
+    }
+
+    if (heapUsed >= warnBytes && !warned) {
+      warned = true;
+      const msg = `Memory warning: heap ${(heapUsed / 1024 / 1024).toFixed(0)}MB / rss ${(rss / 1024 / 1024).toFixed(0)}MB (critical at ${criticalHeapMb}MB)`;
+      if (onWarn) onWarn(msg);
+      else process.stderr.write(`[karajan-mcp] ${msg}\n`);
+    } else if (heapUsed < warnBytes) {
+      warned = false;
+    }
+  }, intervalMs);
+  timer.unref();
+
+  return { timer };
+}
+
+const DEFAULT_GRACE_MS = 2000;
+
+export function writeRestartMarker(version, markerPath = RESTART_MARKER_PATH) {
+  try {
+    mkdirSync(path.dirname(markerPath), { recursive: true });
+    writeFileSync(markerPath, version, "utf8");
+  } catch { /* best-effort */ }
+}
+
+export function readAndDeleteRestartMarker(markerPath = RESTART_MARKER_PATH) {
+  try {
+    if (!existsSync(markerPath)) return null;
+    const version = readFileSync(markerPath, "utf8").trim();
+    unlinkSync(markerPath);
+    return version || null;
+  } catch { /* ignore */ }
+  return null;
+}
+
+export function setupVersionWatcher({
+  pkgPath,
+  currentVersion,
+  gracePeriodMs = DEFAULT_GRACE_MS,
+  exitFn = () => process.exit(0),
+  markerPath = RESTART_MARKER_PATH
+} = {}) {
+  if (!pkgPath) return null;
+
+  let _gracePeriodMs = gracePeriodMs;
+
+  function checkVersion() {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      if (pkg.version !== currentVersion) {
+        const newVersion = pkg.version;
+        process.stderr.write(
+          `[karajan-mcp] Karajan MCP updated (v${currentVersion} → v${newVersion}). Restarting...\n`
+        );
+        writeRestartMarker(newVersion, markerPath);
+        setTimeout(() => exitFn(), _gracePeriodMs);
+        return true;
+      }
+    } catch { /* ignore read errors */ }
+    return false;
+  }
+
+  let watcher = null;
+  try {
+    watcher = watch(pkgPath, { persistent: false }, () => {
+      checkVersion();
+    });
+  } catch { /* ignore watch errors */ }
+
+  return { watcher, checkVersion, get gracePeriodMs() { return _gracePeriodMs; }, set gracePeriodMs(v) { _gracePeriodMs = v; } };
+}

package/src/mcp/preflight.js

@@ -0,0 +1,47 @@
+/**
+ * MCP-scoped preflight state (handshake flag + session overrides facade).
+ *
+ * Two pieces of state:
+ *   - `preflightAcked`: whether the user/host has completed the
+ *     `kj_preflight` handshake in the current MCP session. Stays local
+ *     because it is strictly MCP-protocol state (no CLI equivalent).
+ *   - Session overrides: since v2.7.5 these live in
+ *     `src/session/runtime-overrides.js` — a neutral module that both
+ *     CLI commands and MCP handlers can depend on without creating a
+ *     layer violation. This file re-exports the same functions under
+ *     their historical names for back-compat with existing MCP handlers.
+ *
+ * CLI code must NOT import from this file — it should go straight to
+ * `src/session/runtime-overrides.js`. Enforced by
+ * `tests/architecture/layer-boundaries.test.js`.
+ */
+
+import {
+  getRuntimeOverrides,
+  setRuntimeOverride,
+  clearRuntimeOverrides,
+} from "../session/runtime-overrides.js";
+
+let preflightAcked = false;
+
+export function isPreflightAcked() {
+  return preflightAcked;
+}
+
+export function ackPreflight(overrides = {}) {
+  preflightAcked = true;
+  clearRuntimeOverrides();
+  for (const [k, v] of Object.entries(overrides || {})) {
+    setRuntimeOverride(k, v);
+  }
+}
+
+export function resetPreflight() {
+  preflightAcked = false;
+  clearRuntimeOverrides();
+}
+
+// Back-compat aliases for MCP handlers that still import these names.
+// New code should import from `src/session/runtime-overrides.js` directly.
+export const getSessionOverrides = getRuntimeOverrides;
+export const setSessionOverride = setRuntimeOverride;

package/src/mcp/progress.js

@@ -0,0 +1,149 @@
+/**
+ * MCP progress notification helpers.
+ * Extracted from server.js for testability and reuse.
+ */
+
+export const PROGRESS_STAGES = [
+  "session:start",
+  "iteration:start",
+  "triage:start",
+  "triage:end",
+  "researcher:start",
+  "researcher:end",
+  "planner:start",
+  "planner:end",
+  "coder:start",
+  "coder:end",
+  "refactorer:start",
+  "refactorer:end",
+  "tdd:result",
+  "sonar:start",
+  "sonar:end",
+  "reviewer:start",
+  "reviewer:end",
+  "iteration:end",
+  "solomon:escalate",
+  "question",
+  "session:end",
+  "dry-run:summary",
+  "pipeline:tracker",
+  "agent:heartbeat",
+  "agent:stall"
+];
+
+const PIPELINE_ORDER = [
+  "triage", "researcher", "planner", "coder", "refactorer", "sonar", "reviewer", "tester", "security", "commiter"
+];
+
+export function buildPipelineTracker(config, emitter) {
+  const pipeline = config.pipeline || {};
+
+  const stages = PIPELINE_ORDER
+    .filter(name => {
+      if (name === "coder") return true;
+      if (name === "reviewer") return pipeline.reviewer?.enabled !== false;
+      if (name === "sonar") return pipeline.sonar?.enabled || config.sonarqube?.enabled;
+      return pipeline[name]?.enabled;
+    })
+    .map(name => ({ name, status: "pending", summary: undefined }));
+
+  const findStage = (name) => stages.find(s => s.name === name);
+
+  const emitTracker = () => {
+    emitter.emit("progress", {
+      type: "pipeline:tracker",
+      detail: { stages: stages.map(s => ({ ...s })) }
+    });
+  };
+
+  emitter.on("progress", (event) => {
+    const match = /^(\w+):(start|end)$/.exec(event.type ?? "");
+    if (!match) return;
+
+    const [, name, phase] = match;
+    const stage = findStage(name);
+    if (!stage) return;
+
+    if (phase === "start") {
+      stage.status = "running";
+      stage.summary = event.detail?.[name] || stage.summary;
+    } else {
+      stage.status = event.status === "fail" ? "failed" : "done";
+      stage.summary = event.detail?.summary || event.detail?.gateStatus || stage.summary;
+    }
+
+    emitTracker();
+  });
+
+  return { stages };
+}
+
+export function sendTrackerLog(server, stageName, status, summary) {
+  try {
+    server.sendLoggingMessage({
+      level: "info",
+      logger: "karajan",
+      data: {
+        type: "pipeline:tracker",
+        detail: {
+          stages: [{ name: stageName, status, summary: summary || undefined }]
+        }
+      }
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+function resolveLogLevel(event) {
+  if (event.type === "agent:output") return "debug";
+  if (event.type === "agent:heartbeat") return "debug";
+  if (event.type === "agent:stall") return "warning";
+  if (event.status === "fail") return "error";
+  return "info";
+}
+
+export function buildProgressHandler(server) {
+  return (event) => {
+    try {
+      server.sendLoggingMessage({
+        level: resolveLogLevel(event),
+        logger: "karajan",
+        data: event
+      });
+    } catch {
+      // best-effort: if logging fails, continue
+    }
+  };
+}
+
+export function buildProgressNotifier(extra) {
+  const progressToken = extra?._meta?.progressToken;
+  if (progressToken === undefined) return null;
+
+  const total = PROGRESS_STAGES.length;
+  return (event) => {
+    const idx = PROGRESS_STAGES.indexOf(event.type);
+    if (idx < 0) return;
+
+    const iteration = event.iteration || event.detail?.iteration;
+    const baseMessage = event.message || event.type;
+    const message = iteration
+      ? `[${event.iteration}] ${baseMessage}`
+      : baseMessage;
+
+    try {
+      extra.sendNotification({
+        method: "notifications/progress",
+        params: {
+          progressToken,
+          progress: idx + 1,
+          total,
+          message
+        }
+      });
+    } catch {
+      // best-effort
+    }
+  };
+}

package/src/mcp/response-compressor.js

@@ -0,0 +1,81 @@
+/**
+ * MCP response compressor — reduces token consumption by stripping
+ * verbose fields from list payloads and truncating oversized arrays.
+ */
+
+// Fields to strip from list items (keep in single-item detail views)
+const STRIP_FROM_LIST_ITEMS = [
+  "descriptionStructured", "acceptanceCriteriaStructured",
+  "implementationPlan", "implementationNotes",
+  "developmentInstructions", "raw", "textSummary",
+  "workCycles", "config_snapshot", "paused_state",
+  "checkpoints"
+];
+
+// Fields to strip from all responses (never useful to the LLM)
+const ALWAYS_STRIP = [
+  "firebaseId", "cardType", "group", "createdBy", "updatedBy",
+  "_instance"
+];
+
+const MAX_ARRAY_ITEMS = 20;
+const MAX_COMMITS = 5;
+const MAX_FINDINGS = 10;
+
+export function compressResponse(data, toolName = "") {
+  if (!data || typeof data !== "object") return data;
+  if (Array.isArray(data)) return compressArray(data);
+
+  const compressed = { ...data };
+
+  // Strip always-remove fields
+  for (const key of ALWAYS_STRIP) delete compressed[key];
+
+  // Compress nested arrays and objects
+  for (const [key, value] of Object.entries(compressed)) {
+    if (Array.isArray(value)) {
+      if (key === "commits") compressed[key] = truncateFromEnd(value, MAX_COMMITS);
+      else if (key === "findings" || key === "blocking_issues") compressed[key] = truncateFromStart(value, MAX_FINDINGS);
+      else compressed[key] = compressArray(value);
+    } else if (value && typeof value === "object") {
+      compressed[key] = compressResponse(value, toolName);
+    }
+  }
+
+  return compressed;
+}
+
+function compressArray(arr) {
+  if (!Array.isArray(arr) || arr.length === 0) return arr;
+
+  // Strip verbose fields from list items
+  const stripped = arr.map(item => {
+    if (!item || typeof item !== "object") return item;
+    const clean = { ...item };
+    for (const key of STRIP_FROM_LIST_ITEMS) delete clean[key];
+    for (const key of ALWAYS_STRIP) delete clean[key];
+    return clean;
+  });
+
+  if (stripped.length <= MAX_ARRAY_ITEMS) return stripped;
+
+  const truncated = stripped.slice(0, MAX_ARRAY_ITEMS);
+  truncated.push({ _truncated: true, _total: arr.length, _showing: MAX_ARRAY_ITEMS });
+  return truncated;
+}
+
+function truncateFromEnd(arr, max) {
+  if (arr.length <= max) return arr;
+  return [{ _note: `${arr.length - max} earlier items omitted` }, ...arr.slice(-max)];
+}
+
+function truncateFromStart(arr, max) {
+  if (arr.length <= max) return arr;
+  const truncated = arr.slice(0, max);
+  truncated.push({ _note: `... and ${arr.length - max} more` });
+  return truncated;
+}
+
+export function compactStringify(data) {
+  return JSON.stringify(data);
+}

package/src/mcp/run-kj.js

@@ -0,0 +1,135 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execa } from "execa";
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const CLI_PATH = path.resolve(MODULE_DIR, "..", "cli.js");
+
+/** Mask a secret token for safe logging: show first 4 and last 4 chars only. */
+function maskToken(token) {
+  if (!token || typeof token !== "string") return "***";
+  if (token.length <= 8) return "***";
+  return `${token.slice(0, 4)}${"*".repeat(Math.min(token.length - 8, 16))}${token.slice(-4)}`;
+}
+
+function normalizeBoolFlag(value, flagName, args) {
+  if (value === true) args.push(flagName);
+}
+
+function addOptionalValue(args, flag, value) {
+  if (value !== undefined && value !== null && value !== "") {
+    args.push(flag, String(value));
+  }
+}
+
+export async function runKjCommand({ command, commandArgs = [], options = {}, env = {} }) {
+  const args = [CLI_PATH, command, ...commandArgs];
+
+  addOptionalValue(args, "--coder", options.coder);
+  addOptionalValue(args, "--reviewer", options.reviewer);
+  addOptionalValue(args, "--planner", options.planner);
+  addOptionalValue(args, "--refactorer", options.refactorer);
+  addOptionalValue(args, "--planner-model", options.plannerModel);
+  addOptionalValue(args, "--coder-model", options.coderModel);
+  addOptionalValue(args, "--reviewer-model", options.reviewerModel);
+  addOptionalValue(args, "--refactorer-model", options.refactorerModel);
+  addOptionalValue(args, "--reviewer-fallback", options.reviewerFallback);
+  addOptionalValue(args, "--reviewer-retries", options.reviewerRetries);
+  addOptionalValue(args, "--mode", options.mode);
+  addOptionalValue(args, "--max-iterations", options.maxIterations);
+  addOptionalValue(args, "--max-iteration-minutes", options.maxIterationMinutes);
+  addOptionalValue(args, "--max-total-minutes", options.maxTotalMinutes);
+  addOptionalValue(args, "--base-branch", options.baseBranch);
+  addOptionalValue(args, "--base-ref", options.baseRef);
+  addOptionalValue(args, "--branch-prefix", options.branchPrefix);
+  addOptionalValue(args, "--methodology", options.methodology);
+  normalizeBoolFlag(options.enablePlanner, "--enable-planner", args);
+  normalizeBoolFlag(options.enableReviewer, "--enable-reviewer", args);
+  normalizeBoolFlag(options.enableRefactorer, "--enable-refactorer", args);
+  normalizeBoolFlag(options.enableResearcher, "--enable-researcher", args);
+  normalizeBoolFlag(options.enableTester, "--enable-tester", args);
+  normalizeBoolFlag(options.enableSecurity, "--enable-security", args);
+  normalizeBoolFlag(options.enableImpeccable, "--enable-impeccable", args);
+  normalizeBoolFlag(options.enablePerf, "--enable-perf", args);
+  normalizeBoolFlag(options.design, "--design", args);
+  normalizeBoolFlag(options.enableTriage, "--enable-triage", args);
+  normalizeBoolFlag(options.enableDiscover, "--enable-discover", args);
+  normalizeBoolFlag(options.enableArchitect, "--enable-architect", args);
+  normalizeBoolFlag(options.enableHuReviewer, "--enable-hu-reviewer", args);
+  addOptionalValue(args, "--hu-file", options.huFile);
+  normalizeBoolFlag(options.enableSerena, "--enable-serena", args);
+  normalizeBoolFlag(options.autoCommit, "--auto-commit", args);
+  normalizeBoolFlag(options.autoPush, "--auto-push", args);
+  normalizeBoolFlag(options.autoPr, "--auto-pr", args);
+  if (options.autoRebase === false) args.push("--no-auto-rebase");
+  addOptionalValue(args, "--task-type", options.taskType);
+  normalizeBoolFlag(options.noSonar, "--no-sonar", args);
+  if (options.autoSimplify === true) args.push("--auto-simplify");
+  if (options.autoSimplify === false) args.push("--no-auto-simplify");
+  if (options.smartModels === true) args.push("--smart-models");
+  if (options.smartModels === false) args.push("--no-smart-models");
+  addOptionalValue(args, "--checkpoint-interval", options.checkpointInterval);
+  addOptionalValue(args, "--pg-task", options.pgTask);
+  addOptionalValue(args, "--pg-project", options.pgProject);
+  if (options.quiet === true) args.push("--quiet");
+  if (options.quiet === false) args.push("--verbose");
+
+  const runEnv = {
+    ...process.env,
+    ...env
+  };
+
+  if (options.kjHome) {
+    runEnv.KJ_HOME = options.kjHome;
+  }
+
+  if (options.sonarToken) {
+    runEnv.KJ_SONAR_TOKEN = options.sonarToken;
+  }
+
+  const timeout = options.timeoutMs ? Number(options.timeoutMs) : undefined;
+
+  const execOpts = {
+    env: runEnv,
+    reject: false,
+    timeout
+  };
+  if (options.projectDir) execOpts.cwd = options.projectDir;
+
+  const result = await execa("node", args, execOpts);
+
+  const ok = result.exitCode === 0;
+  const payload = {
+    ok,
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr
+  };
+
+  if (result.timedOut) {
+    payload.ok = false;
+    payload.timedOut = true;
+    payload.stderr = `Process timed out after ${Math.round((timeout || 0) / 1000)}s (explicit timeout). Consider using kj_run for interactive checkpoint support instead of subprocess commands.`;
+  }
+
+  if (result.killed && !payload.timedOut) {
+    payload.ok = false;
+    payload.stderr = `Process was killed by signal ${result.signal || "unknown"}. ${result.stderr || ""}`.trim();
+  }
+
+  if (!ok && result.stderr && !payload.timedOut) {
+    payload.errorSummary = result.stderr.split("\n").filter(Boolean).slice(-3).join(" | ");
+  }
+
+  // Sanitize output: strip sonar token from any log/error output
+  if (options.sonarToken) {
+    const masked = maskToken(options.sonarToken);
+    for (const key of ["stdout", "stderr", "errorSummary"]) {
+      if (payload[key] && typeof payload[key] === "string") {
+        payload[key] = payload[key].replaceAll(options.sonarToken, masked);
+      }
+    }
+  }
+
+  return payload;
+}

package/src/mcp/server-handlers.js

@@ -0,0 +1,79 @@
+/**
+ * MCP server handler logic.
+ * Shared helpers live in ./shared-helpers.js (to avoid circular imports).
+ * Handler implementations are in ./handlers/*.
+ * This module re-exports everything so existing imports continue to work.
+ */
+
+// ── Shared helpers (re-exported from shared-helpers.js) ──────────────
+export {
+  resolveProjectDir,
+  asObject,
+  responseText,
+  failPayload,
+  assertNotOnBaseBranch,
+  enrichedFailPayload,
+  buildConfig,
+  buildAskQuestion,
+  buildDirectEmitter,
+  classifyError
+} from "./shared-helpers.js";
+
+// ── Sub-module re-exports ────────────────────────────────────────────
+export { handleRunDirect, handleResumeDirect, validateResumeAnswer, handleRun, handleResume } from "./handlers/run-handler.js";
+export { handlePlanDirect, handleCodeDirect, handleReviewDirect, handleDiscoverDirect, handleTriageDirect, handleResearcherDirect, handleAuditDirect, handleArchitectDirect, handleCode, handleReview, handlePlan, handleDiscover, handleTriage, handleResearcher, handleArchitect, handleAudit } from "./handlers/direct-handlers.js";
+export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, handleUndo, handleClean, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
+export { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
+
+// ── Handler dispatch ─────────────────────────────────────────────────
+
+import { asObject, failPayload } from "./shared-helpers.js";
+import { handleRun, handleResume } from "./handlers/run-handler.js";
+import {
+  handleCode, handleReview, handlePlan, handleDiscover,
+  handleTriage, handleResearcher, handleArchitect, handleAudit
+} from "./handlers/direct-handlers.js";
+import {
+  handleStatus, handleAgents, handlePreflight, handleRoles,
+  handleReport, handleInit, handleDoctor, handleConfig,
+  handleScan, handleBoard, handleUndo, handleClean
+} from "./handlers/management-handlers.js";
+import { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
+import { handleRagQuery, handleRagIndex } from "./handlers/rag-handler.js";
+
+export async function handleToolCall(name, args, server, extra) {
+  const a = asObject(args);
+  const handler = {
+    kj_status:      (a, server) => handleStatus(a, server),
+    kj_init:        (a) => handleInit(a),
+    kj_doctor:      (a) => handleDoctor(a),
+    kj_agents:      (a) => handleAgents(a),
+    kj_preflight:   (a) => handlePreflight(a),
+    kj_config:      (a) => handleConfig(a),
+    kj_scan:        (a, server) => handleScan(a, server),
+    kj_roles:       (a) => handleRoles(a),
+    kj_report:      (a) => handleReport(a),
+    kj_resume:      (a, server, extra) => handleResume(a, server, extra),
+    kj_run:         (a, server, extra) => handleRun(a, server, extra),
+    kj_code:        (a, server, extra) => handleCode(a, server, extra),
+    kj_review:      (a, server, extra) => handleReview(a, server, extra),
+    kj_plan:        (a, server, extra) => handlePlan(a, server, extra),
+    kj_discover:    (a, server, extra) => handleDiscover(a, server, extra),
+    kj_triage:      (a, server, extra) => handleTriage(a, server, extra),
+    kj_researcher:  (a, server, extra) => handleResearcher(a, server, extra),
+    kj_architect:   (a, server, extra) => handleArchitect(a, server, extra),
+    kj_audit:       (a, server, extra) => handleAudit(a, server, extra),
+    kj_board:       (a) => handleBoard(a),
+    kj_hu:          (a, server) => handleHu(a, server),
+    kj_suggest:     (a) => handleSuggest(a),
+    kj_skills:      (a) => handleSkills(a),
+    kj_undo:        (a, server) => handleUndo(a, server),
+    kj_clean:       (a) => handleClean(a),
+    kj_rag_query:   (a, server) => handleRagQuery(a, server),
+    kj_rag_index:   (a, server) => handleRagIndex(a, server),
+  }[name];
+  if (handler) {
+    return handler(a, server, extra);
+  }
+  return failPayload(`Unknown tool: ${name}`);
+}

package/src/mcp/server.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { tools } from "./tools.js";
+import { handleToolCall, responseText, enrichedFailPayload } from "./server-handlers.js";
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PKG_PATH = path.resolve(MODULE_DIR, "../../package.json");
+
+function readVersion() {
+  return JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
+}
+
+const LOADED_VERSION = readVersion();
+
+const mcpServer = new McpServer(
+  {
+    name: "karajan-mcp",
+    version: LOADED_VERSION
+  },
+  {
+    capabilities: {
+      tools: {},
+      logging: {},
+      elicitation: {}
+    }
+  }
+);
+const server = mcpServer.server;
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  // Auto-exit if package version changed (stale process)
+  if (readVersion() !== LOADED_VERSION) process.exit(0);
+
+  const name = request.params?.name;
+  const args = request.params?.arguments || {};
+
+  try {
+    const result = await handleToolCall(name, args, server, extra);
+    return responseText(result);
+  } catch (error) {
+    return responseText(enrichedFailPayload(error, name));
+  }
+});
+
+// --- Orphan process protection + version watcher ---
+import { setupOrphanGuard, setupVersionWatcher, setupMemoryWatchdog, readAndDeleteRestartMarker } from "./orphan-guard.js";
+
+// Check if this is a restart after update
+const restartedVersion = readAndDeleteRestartMarker();
+if (restartedVersion) {
+  process.stderr.write(`[karajan-mcp] MCP server restarted after update to v${restartedVersion}\n`);
+}
+
+setupOrphanGuard();
+setupVersionWatcher({ pkgPath: PKG_PATH, currentVersion: LOADED_VERSION });
+setupMemoryWatchdog();
+
+const transport = new StdioServerTransport();
+await mcpServer.connect(transport);