kibi-mcp 2.1.0 → 2.2.0

package/dist/diagnostics.js

@@ -10,13 +10,32 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendPayloadCountField, normalizeResultPayload } from "kibi-runtime";
 import { resolveWorkspaceRoot } from "./workspace.js";
 export { buildDiagnosticToolCall, classifyDiagnosticError, deriveDiagnosticHints, deriveDiagnosticRetryKey, extractToolCallPayload, redactDiagnosticArgs, } from "./diagnostics-helpers.js";
 const DIAGNOSTIC_MODE_FLAG = "--diagnostic-mode";
-export const DIAGNOSTIC_MODE_ENABLED = process.argv.includes(DIAGNOSTIC_MODE_FLAG);
+const DIAGNOSTIC_MODE_ENV_KEY = "KIBI_DIAGNOSTIC_MODE";
+/**
+ * Usage telemetry is opt-in and stays off unless the operator asks for it.
+ *
+ * The launch flag covers hosts whose MCP command line the operator writes by
+ * hand.  `KIBI_DIAGNOSTIC_MODE=1` covers hosts where a plugin owns the command
+ * line, so opting in never requires editing a shipped launcher.  Neither
+ * signal is set by default, and plugin installation alone never enables it.
+ */
+export function diagnosticModeRequested(argv = process.argv, env = process.env) {
+    if (argv.includes(DIAGNOSTIC_MODE_FLAG))
+        return true;
+    const optIn = env[DIAGNOSTIC_MODE_ENV_KEY]?.trim().toLowerCase();
+    return optIn === "1" || optIn === "true";
+}
+export const DIAGNOSTIC_MODE_ENABLED = diagnosticModeRequested();
 let diagnosticUsageLogPath = null;
+let diagnosticOriginFields = {};
 export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
     diagnosticUsageLogPath = null;
+    diagnosticOriginFields = {};
     if (!enabled) {
         process.env.KIBI_MCP_DIAGNOSTIC_MODE = "0";
         return;
@@ -30,13 +49,50 @@ export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
     diagnosticUsageLogPath =
         process.env.KIBI_MCP_DIAGNOSTIC_USAGE_LOG_PATH ??
             path.join(workspaceRoot, ".kb", "usage.log");
+    diagnosticOriginFields = resolveOriginFields(workspaceRoot);
     process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
 }
+/**
+ * Identify which host, package build, and checkout produced a usage row.
+ *
+ * Without these a multi-worktree or multi-host setup cannot tell whether a
+ * behavioral difference came from the agent, the editor integration, or the
+ * installed Kibi version, because nothing else in a row names its origin.
+ */
+function resolveOriginFields(workspaceRoot) {
+    return {
+        interface: "mcp",
+        host: process.env.KIBI_MCP_HOST?.trim() || "unknown",
+        package_version: readMcpPackageVersion(),
+        workspace_root: workspaceRoot,
+    };
+}
+function readMcpPackageVersion() {
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = path.join(current, "package.json");
+        if (fs.existsSync(candidate)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(candidate, "utf8"));
+                const version = isRecord(parsed) ? parsed.version : undefined;
+                return typeof version === "string" ? version : null;
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
 export function appendUsageLogLine(entry) {
     if (!diagnosticUsageLogPath)
         return;
     fs.mkdirSync(path.dirname(diagnosticUsageLogPath), { recursive: true });
-    fs.appendFileSync(diagnosticUsageLogPath, `${JSON.stringify(entry)}\n`, {
+    const row = { ...diagnosticOriginFields, ...entry };
+    fs.appendFileSync(diagnosticUsageLogPath, `${JSON.stringify(row)}\n`, {
         encoding: "utf8",
     });
 }
@@ -77,12 +133,6 @@ export const DIAGNOSTIC_TELEMETRY_SCHEMA = {
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function structuredContentFrom(result) {
-    if (!isRecord(result))
-        return undefined;
-    const structuredContent = result.structuredContent;
-    return isRecord(structuredContent) ? structuredContent : undefined;
-}
 function stringArray(value) {
     if (!Array.isArray(value))
         return [];
@@ -276,11 +326,8 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
             fields.actor_id = telemetry.actor_id;
         }
     }
-    const envelope = structuredContentFrom(result);
-    const structuredContent = envelope?.kibiProtocol === 1 && isRecord(envelope.data)
-        ? envelope.data
-        : envelope;
-    if (envelope?.kibiProtocol === 1) {
+    const { envelope, data: structuredContent } = normalizeResultPayload(result);
+    if (envelope) {
         fields.protocol_version = envelope.kibiProtocol;
         fields.result_version = envelope.resultVersion ?? null;
         fields.result_status = envelope.status ?? null;
@@ -296,18 +343,14 @@ export function deriveDiagnosticFields(toolName, args, telemetry, result) {
         fields.unsafe_original_retry = telemetry?.unsafe_original_retry === true;
     }
     if (toolName === "kb_query" || toolName === "kb_search") {
-        const resultCount = Number(structuredContent?.count ?? 0);
-        fields.result_count = resultCount;
-        fields.zero_results = resultCount === 0;
-        fields.result_summary =
-            resultCount === 0 ? "0 results" : `${resultCount} results`;
+        appendPayloadCountField(fields, "result_count", "results", structuredContent);
+        if (typeof fields.result_count === "number") {
+            fields.zero_results = fields.result_count === 0;
+        }
     }
     if (toolName === "kb_check") {
-        const violationCount = Number(structuredContent?.count ?? 0);
-        fields.violation_count = violationCount;
+        appendPayloadCountField(fields, "violation_count", "violations", structuredContent);
         fields.requested_rules = Array.isArray(args.rules) ? args.rules : [];
-        fields.result_summary =
-            violationCount === 0 ? "0 violations" : `${violationCount} violations`;
     }
     if (toolName === "kb_coverage" && structuredContent) {
         appendCoverageFields(fields, args, structuredContent);

package/dist/server/docs.js

@@ -199,7 +199,7 @@ function registerDocResources() {
         '2. `kb_coverage` with `{ "by": "req", "includePassing": false }` to review proof rows and `repairPlan`; require `repairPlan.scope.complete` before treating it as a project-wide inventory',
         "3. Apply only a `repairPlan` batch whose state is `ready`; batches are non-auto-applicable guidance, so query current endpoints, validate every write, and keep `kb_upsert` sequential",
         "4. Re-run `kb_coverage` after each batch instead of continuing from a stale plan",
-        '5. `kb_graph` with `{ "seedIds": ["REQ-001"], "direction": "both", "depth": 2 }` to inspect neighboring entities',
+        '5. `kb_graph` with `{ "seedIds": ["REQ-cli-gc"], "direction": "both", "depth": 2 }` to inspect neighboring entities',
         "",
         "## Add a requirement and link it to a test",
         '1. `kb_query` with `{ "type": "test" }` to check for existing test IDs',

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "kibi-mcp",
-  "version": "2.1.0",
+  "version": "2.2.0",
+  "mcpName": "io.github.Looted/kibi-mcp",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "ajv": "^8.18.0",
@@ -9,8 +10,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-runtime": "^2.0.1",
-    "kibi-core": "^0.13.0",
+    "kibi-runtime": "^2.0.2",
+    "kibi-core": "^0.14.0",
     "mcpcat": "^0.1.12",
     "zod": "^4.3.6"
   },