@getmikk/mcp-server 1.9.0 → 1.9.2

package/bin/mikk-mcp.js

@@ -18,4 +18,13 @@ if (idx !== -1 && process.argv[idx + 1]) {
 process.env.MIKK_PROJECT_ROOT = projectRoot
 
 // Load the CJS bundle (auto-starts stdio server via src/index.ts)
-require('../dist/index.cjs')
+const mod = require('../dist/index.cjs')
+if (mod.startStdioServer) {
+    mod.startStdioServer().catch(err => {
+        console.error('Failed to start MCP server:', err)
+        process.exit(1)
+    })
+} else {
+    console.error('MCP server bundle is missing startStdioServer export.')
+    process.exit(1)
+}

package/dist/index.cjs

@@ -15394,7 +15394,7 @@ ${lanes.join("\n")}
             writeOutputIsTTY() {
               return process.stdout.isTTY;
             },
-            readFile: readFile7,
+            readFile: readFile6,
             writeFile: writeFile22,
             watchFile: watchFile2,
             watchDirectory,
@@ -15600,7 +15600,7 @@ ${lanes.join("\n")}
               callback
             );
           }
-          function readFile7(fileName, _encoding) {
+          function readFile6(fileName, _encoding) {
             let buffer;
             try {
               buffer = _fs.readFileSync(fileName);
@@ -52040,7 +52040,7 @@ ${lanes.join("\n")}
         const possibleOption = getSpellingSuggestion(unknownOption, diagnostics.optionDeclarations, getOptionName);
         return possibleOption ? createDiagnosticForNodeInSourceFileOrCompilerDiagnostic(sourceFile, node, diagnostics.unknownDidYouMeanDiagnostic, unknownOptionErrorText || unknownOption, possibleOption.name) : createDiagnosticForNodeInSourceFileOrCompilerDiagnostic(sourceFile, node, diagnostics.unknownOptionDiagnostic, unknownOptionErrorText || unknownOption);
       }
-      function parseCommandLineWorker(diagnostics, commandLine, readFile7) {
+      function parseCommandLineWorker(diagnostics, commandLine, readFile6) {
         const options = {};
         let watchOptions;
         const fileNames = [];
@@ -52088,7 +52088,7 @@ ${lanes.join("\n")}
           }
         }
         function parseResponseFile(fileName) {
-          const text = tryReadFile(fileName, readFile7 || ((fileName2) => sys.readFile(fileName2)));
+          const text = tryReadFile(fileName, readFile6 || ((fileName2) => sys.readFile(fileName2)));
           if (!isString(text)) {
             errors.push(text);
             return;
@@ -52190,8 +52190,8 @@ ${lanes.join("\n")}
         unknownDidYouMeanDiagnostic: Diagnostics.Unknown_compiler_option_0_Did_you_mean_1,
         optionTypeMismatchDiagnostic: Diagnostics.Compiler_option_0_expects_an_argument
       };
-      function parseCommandLine(commandLine, readFile7) {
-        return parseCommandLineWorker(compilerOptionsDidYouMeanDiagnostics, commandLine, readFile7);
+      function parseCommandLine(commandLine, readFile6) {
+        return parseCommandLineWorker(compilerOptionsDidYouMeanDiagnostics, commandLine, readFile6);
       }
       function getOptionFromName(optionName, allowShort) {
         return getOptionDeclarationFromName(getOptionsNameMap, optionName, allowShort);
@@ -52273,8 +52273,8 @@ ${lanes.join("\n")}
           watchOptionsToExtend
         );
       }
-      function readConfigFile(fileName, readFile7) {
-        const textOrDiagnostic = tryReadFile(fileName, readFile7);
+      function readConfigFile(fileName, readFile6) {
+        const textOrDiagnostic = tryReadFile(fileName, readFile6);
         return isString(textOrDiagnostic) ? parseConfigFileTextToJson(fileName, textOrDiagnostic) : { config: {}, error: textOrDiagnostic };
       }
       function parseConfigFileTextToJson(fileName, jsonText) {
@@ -52289,14 +52289,14 @@ ${lanes.join("\n")}
           error: jsonSourceFile.parseDiagnostics.length ? jsonSourceFile.parseDiagnostics[0] : void 0
         };
       }
-      function readJsonConfigFile(fileName, readFile7) {
-        const textOrDiagnostic = tryReadFile(fileName, readFile7);
+      function readJsonConfigFile(fileName, readFile6) {
+        const textOrDiagnostic = tryReadFile(fileName, readFile6);
         return isString(textOrDiagnostic) ? parseJsonText(fileName, textOrDiagnostic) : { fileName, parseDiagnostics: [textOrDiagnostic] };
       }
-      function tryReadFile(fileName, readFile7) {
+      function tryReadFile(fileName, readFile6) {
         let text;
         try {
-          text = readFile7(fileName);
+          text = readFile6(fileName);
         } catch (e) {
           return createCompilerDiagnostic(Diagnostics.Cannot_read_file_0_Colon_1, fileName, e.message);
         }
@@ -141824,12 +141824,12 @@ ${lanes.join("\n")}
       function createCompilerHost(options, setParentNodes) {
         return createCompilerHostWorker(options, setParentNodes);
       }
-      function createGetSourceFile(readFile7, setParentNodes) {
+      function createGetSourceFile(readFile6, setParentNodes) {
         return (fileName, languageVersionOrOptions, onError) => {
           let text;
           try {
             mark("beforeIORead");
-            text = readFile7(fileName);
+            text = readFile6(fileName);
             mark("afterIORead");
             measure("I/O Read", "beforeIORead", "afterIORead");
           } catch (e) {
@@ -142733,7 +142733,7 @@ ${lanes.join("\n")}
           getRedirectFromOutput,
           forEachResolvedProjectReference: forEachResolvedProjectReference2
         });
-        const readFile7 = host.readFile.bind(host);
+        const readFile6 = host.readFile.bind(host);
         (_e = tracing) == null ? void 0 : _e.push(tracing.Phase.Program, "shouldProgramCreateNewSourceFiles", { hasOldProgram: !!oldProgram });
         const shouldCreateNewSourceFile = shouldProgramCreateNewSourceFiles(oldProgram, options);
         (_f = tracing) == null ? void 0 : _f.pop();
@@ -142959,7 +142959,7 @@ ${lanes.join("\n")}
           shouldTransformImportCall,
           emitBuildInfo,
           fileExists: fileExists2,
-          readFile: readFile7,
+          readFile: readFile6,
           directoryExists,
           getSymlinkCache,
           realpath: (_o = host.realpath) == null ? void 0 : _o.bind(host),
@@ -236933,7 +236933,8 @@ var ImpactAnalyzer = class {
   analyze(changedNodeIds) {
     const visited = /* @__PURE__ */ new Set();
     const depthMap = /* @__PURE__ */ new Map();
-    const queue = changedNodeIds.map((id) => ({ id, depth: 0 }));
+    const pathConfidence = /* @__PURE__ */ new Map();
+    const queue = changedNodeIds.map((id) => ({ id, depth: 0, confidence: 1 }));
     let maxDepth = 0;
     const changedSet = new Set(changedNodeIds);
     const changedModules = /* @__PURE__ */ new Set();
@@ -236943,16 +236944,19 @@ var ImpactAnalyzer = class {
         changedModules.add(node.moduleId);
     }
     while (queue.length > 0) {
-      const { id: current, depth } = queue.shift();
+      const { id: current, depth, confidence: pathConf } = queue.shift();
       if (visited.has(current))
         continue;
       visited.add(current);
       depthMap.set(current, depth);
+      pathConfidence.set(current, pathConf);
       maxDepth = Math.max(maxDepth, depth);
       const dependents = this.graph.inEdges.get(current) || [];
       for (const edge of dependents) {
         if (!visited.has(edge.source) && edge.type !== "contains") {
-          queue.push({ id: edge.source, depth: depth + 1 });
+          const edgeConf = edge.confidence ?? 1;
+          const newPathConf = Math.min(pathConf, edgeConf);
+          queue.push({ id: edge.source, depth: depth + 1, confidence: newPathConf });
         }
       }
     }
@@ -236984,19 +236988,33 @@ var ImpactAnalyzer = class {
       changed: changedNodeIds,
       impacted,
       depth: maxDepth,
-      confidence: this.computeConfidence(impacted.length, maxDepth),
+      confidence: this.computeConfidence(impacted, pathConfidence),
       classified
     };
   }
   /**
-   * How confident are we in this impact analysis?
-   * High = few nodes affected, shallow depth
-   * Low = many nodes affected, deep chains
+   * Derive confidence from the actual quality of edges traversed, not from
+   * result size. A small result built from fuzzy/unresolved edges is LOW
+   * confidence; a large result built from high-confidence AST edges is HIGH.
+   *
+   * Algorithm:
+   *   - Compute the average minimum-path-confidence across all impacted nodes.
+   *   - Penalise for deep chains (they amplify uncertainty).
+   *   - Map the combined score to HIGH / MEDIUM / LOW.
    */
-  computeConfidence(impactedCount, depth) {
-    if (impactedCount < 5 && depth < 3)
+  computeConfidence(impacted, pathConfidence) {
+    if (impacted.length === 0)
       return "high";
-    if (impactedCount < 20 && depth < 6)
+    let total = 0;
+    for (const id of impacted) {
+      total += pathConfidence.get(id) ?? 1;
+    }
+    const avgConf = total / impacted.length;
+    const sizePenalty = impacted.length > 20 ? 0.15 : impacted.length > 10 ? 0.08 : 0;
+    const score = avgConf - sizePenalty;
+    if (score >= 0.75)
+      return "high";
+    if (score >= 0.5)
       return "medium";
     return "low";
   }
@@ -237007,7 +237025,6 @@ var ENTRY_POINT_PATTERNS = [
   /^(main|bootstrap|start|init|setup|configure|register|mount)$/i,
   /^(app|server|index|mod|program)$/i,
   /Handler$/i,
-  // Express/Koa/Hono handlers
   /Middleware$/i,
   /Controller$/i,
   /^use[A-Z]/,
@@ -237023,14 +237040,26 @@ var TEST_PATTERNS = [
   /\.spec\./,
   /__test__/
 ];
+var DYNAMIC_USAGE_PATTERNS = [
+  /^addEventListener$/i,
+  /^removeEventListener$/i,
+  /^on[A-Z]/,
+  /(invoke|dispatch|emit|call|apply)/i,
+  /^ngOnInit$/i,
+  /^componentDidMount$/i,
+  /^componentWillUnmount$/i
+];
 var DeadCodeDetector = class {
   graph;
   lock;
   routeHandlers;
+  /** Files that have at least one unresolved import (empty resolvedPath) */
+  filesWithUnresolvedImports;
   constructor(graph, lock) {
     this.graph = graph;
     this.lock = lock;
     this.routeHandlers = new Set((lock.routes ?? []).map((r) => r.handler).filter(Boolean));
+    this.filesWithUnresolvedImports = this.buildUnresolvedImportFileSet();
   }
   detect() {
     const dead = [];
@@ -237049,13 +237078,15 @@ var DeadCodeDetector = class {
         continue;
       if (this.isExempt(fn, id))
         continue;
+      const confidence = this.inferConfidence(fn);
       const entry = {
         id,
         name: fn.name,
         file: fn.file,
         moduleId,
         type: "function",
-        reason: this.inferReason(fn, id)
+        reason: this.inferReason(fn),
+        confidence
       };
       dead.push(entry);
       byModule[moduleId].dead++;
@@ -237069,9 +237100,7 @@ var DeadCodeDetector = class {
         }
         const inEdges = this.graph.inEdges.get(id) || [];
         const hasCallers = inEdges.some((e) => e.type === "calls" || e.type === "imports");
-        if (hasCallers)
-          continue;
-        if (cls.isExported)
+        if (hasCallers || cls.isExported)
           continue;
         const entry = {
           id,
@@ -237079,7 +237108,8 @@ var DeadCodeDetector = class {
           file: cls.file,
           moduleId,
           type: "class",
-          reason: "Class has no callers or importers and is not exported"
+          reason: "Class has no callers or importers and is not exported",
+          confidence: this.filesWithUnresolvedImports.has(cls.file) ? "medium" : "high"
         };
         dead.push(entry);
         byModule[moduleId].dead++;
@@ -237094,7 +237124,7 @@ var DeadCodeDetector = class {
       byModule
     };
   }
-  // ─── Exemption checks ──────────────────────────────────────────
+  // ─── Private helpers ───────────────────────────────────────────
   isExempt(fn, id) {
     if (fn.isExported)
       return true;
@@ -237106,24 +237136,66 @@ var DeadCodeDetector = class {
       return true;
     if (fn.name === "constructor" || fn.name === "__init__")
       return true;
-    if (this.isCalledByExportedInSameFile(fn, id))
+    if (this.isCalledByExportedInSameFile(fn))
       return true;
     return false;
   }
-  isCalledByExportedInSameFile(fn, fnId) {
+  isCalledByExportedInSameFile(fn) {
     for (const callerId of fn.calledBy) {
       const caller = this.lock.functions[callerId];
-      if (caller && caller.isExported && caller.file === fn.file) {
+      if (caller && caller.isExported && caller.file === fn.file)
         return true;
-      }
     }
     return false;
   }
-  inferReason(fn, id) {
+  /**
+   * Assign a confidence level to a dead code finding.
+   *
+   * Priority (first match wins):
+   *  medium — lock.calledBy has entries that didn't become graph edges:
+   *           something references this function but resolution failed.
+   *  medium — file has unresolved imports: the graph may be incomplete.
+   *  low    — function name matches common dynamic-dispatch patterns.
+   *  high   — none of the above: safe to remove.
+   */
+  inferConfidence(fn) {
+    if (fn.calledBy.length > 0)
+      return "medium";
+    if (this.filesWithUnresolvedImports.has(fn.file))
+      return "medium";
+    if (DYNAMIC_USAGE_PATTERNS.some((p) => p.test(fn.name)))
+      return "low";
+    return "high";
+  }
+  inferReason(fn) {
     if (fn.calledBy.length === 0) {
       return "No callers found anywhere in the codebase";
     }
-    return `${fn.calledBy.length} references exist but none resolved to active call edges`;
+    return `${fn.calledBy.length} reference(s) in lock but none resolved to active call edges`;
+  }
+  /**
+   * Build the set of file paths that have at least one import whose
+   * resolvedPath is empty. Used to downgrade confidence for all dead
+   * findings in those files, since the graph may be incomplete.
+   *
+   * We derive this from the lock's file entries. Each file entry stores
+   * its imports; any import with an empty resolvedPath (or no match in
+   * the graph nodes) indicates an unresolved dependency.
+   */
+  buildUnresolvedImportFileSet() {
+    const result = /* @__PURE__ */ new Set();
+    if (!this.lock.files)
+      return result;
+    for (const [filePath, fileInfo] of Object.entries(this.lock.files)) {
+      const imports = fileInfo.imports ?? [];
+      for (const imp of imports) {
+        if (!imp.resolvedPath || imp.resolvedPath === "") {
+          result.add(filePath);
+          break;
+        }
+      }
+    }
+    return result;
   }
 };
 
@@ -237272,22 +237344,43 @@ var MikkLockSchema = external_exports.object({
   })
 });
 
-// ../core/dist/contract/contract-reader.js
+// ../core/dist/utils/json.js
 var fs = __toESM(require("node:fs/promises"), 1);
+async function readJsonSafe(filePath, fileLabel = "JSON file") {
+  let content;
+  try {
+    content = await fs.readFile(filePath, "utf-8");
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      throw e;
+    }
+    throw new Error(`Failed to read ${fileLabel}: ${e.message}`);
+  }
+  const sanitized = content.replace(/^\uFEFF/, "");
+  try {
+    return JSON.parse(sanitized);
+  } catch (e) {
+    throw new Error(`Malformed ${fileLabel}: Syntax error - ${e.message}`);
+  }
+}
+
+// ../core/dist/contract/contract-reader.js
 var ContractReader = class {
   /** Read and validate mikk.json */
   async read(contractPath) {
-    let content;
+    let json;
     try {
-      content = await fs.readFile(contractPath, "utf-8");
-    } catch {
-      throw new ContractNotFoundError(contractPath);
+      json = await readJsonSafe(contractPath, "mikk.json");
+    } catch (e) {
+      if (e.code === "ENOENT") {
+        throw new ContractNotFoundError(contractPath);
+      }
+      throw e;
     }
-    const json = JSON.parse(content.replace(/^\uFEFF/, ""));
     const result = MikkContractSchema.safeParse(json);
     if (!result.success) {
       const errors = result.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
-      throw new Error(`Invalid mikk.json:
+      throw new Error(`Invalid mikk.json structure:
 ${errors}`);
     }
     return result.data;
@@ -237299,18 +237392,20 @@ var fs2 = __toESM(require("node:fs/promises"), 1);
 var LockReader = class {
   /** Read and validate mikk.lock.json */
   async read(lockPath) {
-    let content;
+    let json;
     try {
-      content = await fs2.readFile(lockPath, "utf-8");
-    } catch {
-      throw new LockNotFoundError();
+      json = await readJsonSafe(lockPath, "mikk.lock.json");
+    } catch (e) {
+      if (e.code === "ENOENT") {
+        throw new LockNotFoundError();
+      }
+      throw e;
     }
-    const json = JSON.parse(content.replace(/^\uFEFF/, ""));
     const hydrated = hydrateLock(json);
     const result = MikkLockSchema.safeParse(hydrated);
     if (!result.success) {
       const errors = result.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
-      throw new Error(`Invalid mikk.lock.json:
+      throw new Error(`Invalid mikk.lock.json structure:
 ${errors}`);
     }
     return result.data;
@@ -238659,6 +238754,38 @@ var IntentSchema = external_exports.object({
 // src/tools.ts
 var projectCache = /* @__PURE__ */ new Map();
 var CACHE_TTL_MS = 3e4;
+var _CPT = 4;
+var _ALC = 42;
+var _tallies = /* @__PURE__ */ new Map();
+function _tally(r) {
+  let t = _tallies.get(r);
+  if (!t) {
+    t = { calls: 0, used: 0, raw: 0, saved: 0, start: Date.now() };
+    _tallies.set(r, t);
+  }
+  return t;
+}
+function _tok(o) {
+  return Math.max(1, Math.round(JSON.stringify(o).length / _CPT));
+}
+function _fileTok(lock, fp) {
+  const fs22 = Object.values(lock.functions).filter((f) => f.file === fp);
+  const ln = fs22.length > 0 ? Math.max(...fs22.map((f) => f.endLine)) : 80;
+  return Math.round(ln * _ALC / _CPT);
+}
+function _filesTok(lock, fps) {
+  return fps.reduce((s, f) => s + _fileTok(lock, f), 0);
+}
+function _track(root, raw, resp) {
+  const used = _tok(resp);
+  const saved = Math.max(0, raw - used);
+  const t = _tally(root);
+  t.calls++;
+  t.used += used;
+  t.raw += raw;
+  t.saved += saved;
+  return { used, raw, saved, sessionSaved: t.saved, sessionCalls: t.calls };
+}
 var semanticSearchers = /* @__PURE__ */ new Map();
 function getSemanticSearcher(projectRoot) {
   let s = semanticSearchers.get(projectRoot);
@@ -238706,12 +238833,14 @@ function registerTools(server2, projectRoot) {
         warning: staleness,
         hint: "Next: Use mikk_query_context with your task description, or mikk_list_modules to explore the architecture."
       };
+      const _rawOverview = Math.min(15, Object.keys(lock.files).length) * Math.round(80 * _ALC / _CPT);
+      overview.tokens = _track(projectRoot, _rawOverview, overview);
       return { content: [{ type: "text", text: JSON.stringify(overview, null, 2) }] };
     }
   );
   server2.tool(
     "mikk_query_context",
-    "Ask an architecture question \u201D returns graph-traced context with relevant functions, files, and call chains. Use this to understand how code flows through the project.",
+    "Ask an architecture question \u2014 returns graph-traced context with relevant functions, files, and call chains. Use this to understand how code flows through the project.",
     {
       question: external_exports.string().describe("The architecture question or task description"),
       maxHops: external_exports.number().optional().default(4).describe("Graph traversal depth (default: 4)"),
@@ -238748,8 +238877,14 @@ function registerTools(server2, projectRoot) {
       const warning = staleness ? `
 
 ${staleness}` : "";
+      const _rawQC = (tokenBudget ?? 6e3) * 3;
+      const _tokQC = _track(projectRoot, _rawQC, output);
+      const tokLine = `
+
+---
+// tokens: ${JSON.stringify(_tokQC)}`;
       return {
-        content: [{ type: "text", text: output + warning + "\n\n---\nHint: Use mikk_before_edit on any files you plan to modify, then mikk_impact_analysis to see the full blast radius." }]
+        content: [{ type: "text", text: output + warning + "\n\n---\nHint: Use mikk_before_edit on any files you plan to modify, then mikk_impact_analysis to see the full blast radius." + tokLine }]
       };
     }
   );
@@ -238802,6 +238937,8 @@ ${staleness}` : "";
         warning: staleness,
         hint: "Next: Use mikk_get_function_detail on critical/high items to review them. Then mikk_before_edit to validate your planned changes."
       };
+      const _rawIA = _fileTok(lock, normalizedFile) + result.impacted.length * Math.round(40 * _ALC / _CPT);
+      response.tokens = _track(projectRoot, _rawIA, response);
       return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
     }
   );
@@ -238911,8 +239048,10 @@ ${staleness}` : "";
         constraintStatus: totalViolations === 0 ? "pass" : "fail",
         files: fileReports,
         warning: staleness,
-        hint: totalViolations > 0 ? "\x8F Constraint violations detected! Review the violations before proceeding. Use mikk_get_constraints for full rule context." : "All constraints satisfied. If safe, proceed with your edits."
+        hint: totalViolations > 0 ? "\u26A0 Constraint violations detected! Review the violations before proceeding. Use mikk_get_constraints for full rule context." : "All constraints satisfied. If safe, proceed with your edits."
       };
+      const _rawBE = _filesTok(lock, filesToEdit) * 4;
+      response.tokens = _track(projectRoot, _rawBE, response);
       return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
     }
   );
@@ -239043,7 +239182,7 @@ ${staleness}` : "";
           content: [{
             type: "text",
             text: [
-              "\x9D\u0152 Semantic search requires @xenova/transformers.",
+              "\u26A0 Semantic search requires @xenova/transformers.",
               "",
               "Install it in your project root:",
               "  npm install @xenova/transformers",
@@ -239172,7 +239311,7 @@ ${content}`
   );
   server2.tool(
     "mikk_dead_code",
-    "Detect dead code \u201D functions with zero callers after exempting exports, entry points, route handlers, tests, and constructors. Use this before refactoring or cleanup.",
+    "Detect dead code \u2014 functions with zero callers after exempting exports, entry points, route handlers, tests, and constructors. Use this before refactoring or cleanup.",
     {
       moduleId: external_exports.string().optional().describe("Filter results to a specific module ID")
     },
@@ -239300,6 +239439,8 @@ ${content}`
         warning: staleness,
         hint: modified.length + added.length > 0 ? "Run `mikk analyze` to update the lock file with these changes." : "Codebase is in sync with the lock file."
       };
+      const _rawGC = Math.min(50, Object.keys(lock.files).length) * Math.round(60 * _ALC / _CPT);
+      response.tokens = _track(projectRoot, _rawGC, response);
       return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
     }
   );
@@ -239345,7 +239486,7 @@ ${content}` }]
           (f) => (f.name === fnName || f.name.endsWith(`.${fnName}`)) && (f.file === normalizedFile || f.file.endsWith("/" + normalizedFile))
         );
         if (!fn) {
-          sections.push(`// \x9D\u0152 Function "${fnName}" not found in ${file}`);
+          sections.push(`// \u26A0 Function "${fnName}" not found in ${file}`);
           continue;
         }
         const header = [
@@ -239368,7 +239509,10 @@ ${body}`);
       const warningText = staleness ? `
 
 ${staleness}` : "";
-      return { content: [{ type: "text", text: output + warningText }] };
+      const _rawRF = _fileTok(lock, file.replace(/\\/g, "/"));
+      const _tokRF = _track(projectRoot, _rawRF, output);
+      return { content: [{ type: "text", text: output + warningText + `
+// tokens: ${JSON.stringify(_tokRF)}` }] };
     }
   );
   server2.tool(
@@ -239432,6 +239576,8 @@ ${staleness}` : "";
         warning: staleness,
         hint: changedCount > 0 ? `${changedCount} file(s) may have changed. Run \`mikk analyze\` for accurate results, or use mikk_get_changes for details.` : "Codebase is in sync. Use mikk_query_context with your task description to get started."
       };
+      const _rawSC = Math.min(20, Object.keys(lock.files).length) * Math.round(100 * _ALC / _CPT);
+      response.tokens = _track(projectRoot, _rawSC, response);
       return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
     }
   );
@@ -239536,6 +239682,37 @@ ${staleness}` : "";
       };
     }
   );
+  server2.tool(
+    "mikk_token_stats",
+    "Show token savings for this session \u2014 how many tokens Mikk saved vs. the agent reading raw source files. WHEN TO USE: Any time. Useful at end of session to see cumulative efficiency. Returns per-session totals and cost estimates.",
+    {},
+    async () => {
+      const t = _tally(projectRoot);
+      const { lock } = await loadContractAndLock(projectRoot);
+      const totalFileLine = Object.values(lock.functions).reduce((s, f) => s + (f.endLine - f.startLine + 1), 0);
+      const fullCodebaseTok = Math.round(totalFileLine * _ALC / _CPT);
+      const elapsedMin = Math.round((Date.now() - t.start) / 6e4);
+      const response = {
+        session: {
+          calls: t.calls,
+          elapsedMinutes: elapsedMin
+        },
+        tokens: {
+          used: t.used,
+          rawWouldHaveCost: t.raw,
+          saved: t.saved,
+          savingsPercent: t.raw > 0 ? Math.round(t.saved / t.raw * 100) : 0
+        },
+        context: {
+          fullCodebaseTokens: fullCodebaseTok,
+          percentOfCodebaseRead: t.raw > 0 ? Math.round(t.used / fullCodebaseTok * 100) : 0,
+          note: "Full codebase = if agent read every tracked source line once"
+        },
+        interpretation: t.saved > 0 ? `Mikk saved ~${t.saved.toLocaleString()} tokens this session (${Math.round(t.saved / t.raw * 100)}% reduction). Roughly ${Math.round(t.saved / 1e3)}k tokens = ~${(t.saved * 3e-6).toFixed(3)} USD at GPT-4o rates.` : "No tools called yet this session."
+      };
+      return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
+    }
+  );
 }
 async function loadContractAndLock(projectRoot) {
   const cached2 = projectCache.get(projectRoot);
@@ -239549,7 +239726,7 @@ async function loadContractAndLock(projectRoot) {
   const syncStatus = lock.syncState?.status ?? "unknown";
   let staleness = null;
   if (syncStatus === "drifted" || syncStatus === "conflict") {
-    staleness = `\x8F Lock file is ${syncStatus}. Run \`mikk analyze\` for accurate results.`;
+    staleness = `\u26A0 Lock file is ${syncStatus}. Run \`mikk analyze\` for accurate results.`;
   }
   if (!staleness) {
     const fileEntries = Object.entries(lock.files);
@@ -239572,7 +239749,7 @@ async function loadContractAndLock(projectRoot) {
       }
     }
     if (mismatched > 0) {
-      staleness = `\x8F STALE: ${mismatched} file(s) changed since last analysis (${mismatchedFiles.slice(0, 3).join(", ")}${mismatched > 3 ? "..." : ""}). Run \`mikk analyze\`.`;
+      staleness = `\u26A0 STALE: ${mismatched} file(s) changed since last analysis (${mismatchedFiles.slice(0, 3).join(", ")}${mismatched > 3 ? "..." : ""}). Run \`mikk analyze\`.`;
     }
   }
   const graph = buildGraphFromLock(lock);
@@ -239644,7 +239821,7 @@ function detectCircularDeps(fns, lock) {
         const cycleStart = cyclePath.indexOf(id);
         const cycle = cyclePath.slice(cycleStart).map((cid) => lock.functions[cid]?.name ?? cid);
         cycle.push(lock.functions[id]?.name ?? id);
-        warnings.push(`\x8F Circular: ${cycle.join(" \u2020\u2019 ")}`);
+        warnings.push(`\u26A0 Circular: ${cycle.join(" -> ")}`);
         return true;
       }
       if (visited.has(id)) return false;
@@ -239779,7 +239956,7 @@ async function safeRead(filePath) {
 }
 
 // src/server.ts
-var VERSION = true ? "1.9.0" : "0.0.0-dev";
+var VERSION = true ? "1.9.2" : "0.0.0-dev";
 function createMikkMcpServer(projectRoot) {
   const server2 = new McpServer({
     name: "mikk",
@@ -239889,9 +240066,6 @@ async function startStdioServer() {
   const transport = new StdioServerTransport();
   await server2.connect(transport);
 }
-
-// src/index.ts
-startStdioServer();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createMikkMcpServer,