kibi-mcp 0.3.2 → 0.3.3

package/dist/diagnostics.js

@@ -0,0 +1,95 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { resolveWorkspaceRoot } from "./workspace.js";
+const DIAGNOSTIC_MODE_FLAG = "--diagnostic-mode";
+/**
+ * Whether diagnostic mode is enabled via CLI flag.
+ * Set during server startup and never changes at runtime.
+ */
+export const DIAGNOSTIC_MODE_ENABLED = process.argv.includes(DIAGNOSTIC_MODE_FLAG);
+/**
+ * Path to the diagnostic usage log file.
+ * Only valid when DIAGNOSTIC_MODE_ENABLED is true.
+ */
+let diagnosticUsageLogPath = null;
+/**
+ * Initialize diagnostic mode: set up usage.log path.
+ * Called once during server startup.
+ */
+export function initializeDiagnosticMode() {
+    if (DIAGNOSTIC_MODE_ENABLED) {
+        const workspaceRoot = resolveWorkspaceRoot();
+        diagnosticUsageLogPath = path.join(workspaceRoot, ".kb", "usage.log");
+        process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
+    }
+}
+/**
+ * Append a JSON line to the usage.log file.
+ * No-op if diagnostic mode is not enabled.
+ */
+export function appendUsageLogLine(entry) {
+    if (!DIAGNOSTIC_MODE_ENABLED || !diagnosticUsageLogPath) {
+        return;
+    }
+    const logDir = path.dirname(diagnosticUsageLogPath);
+    fs.mkdirSync(logDir, { recursive: true });
+    fs.appendFileSync(diagnosticUsageLogPath, `${JSON.stringify(entry)}\n`, {
+        encoding: "utf8",
+    });
+}
+/**
+ * Schema for _diagnostic_telemetry field added to tool inputs in diagnostic mode.
+ */
+export const DIAGNOSTIC_TELEMETRY_SCHEMA = {
+    type: "object",
+    description: "REQUIRED when diagnostic mode is on. Provide self-reflection metadata about this tool call.",
+    properties: {
+        is_autonomous: {
+            type: "boolean",
+            description: "Set to TRUE if you are calling this tool on your own initiative to retrieve context. Set to FALSE if the user explicitly commanded you to use the knowledge base.",
+        },
+        reasoning: {
+            type: "string",
+            description: "A brief, 1-2 sentence internal thought explaining exactly why you are calling this tool right now and what information you expect to get.",
+        },
+        confidence_score: {
+            type: "number",
+            description: "A score from 0.0 to 1.0 representing your confidence that the exact parameters, IDs, or tags you provided will yield a successful result.",
+        },
+        attempt_number: {
+            type: "integer",
+            description: "If you are retrying this exact task because a previous tool call failed or returned empty results, increment this number (start at 1).",
+        },
+        missing_context: {
+            type: "string",
+            description: "If you had to split your task into multiple steps because this tool lacks a specific filtering or querying capability, describe what parameter is missing. Otherwise, leave empty.",
+        },
+    },
+};
+/**
+ * Extract business args and telemetry from tool call arguments.
+ */
+export function extractToolCallPayload(args) {
+    const { _diagnostic_telemetry, ...businessArgs } = args;
+    const telemetry = _diagnostic_telemetry && typeof _diagnostic_telemetry === "object"
+        ? _diagnostic_telemetry
+        : null;
+    return { businessArgs, telemetry };
+}

package/dist/server/tools.js

@@ -17,12 +17,13 @@
  */
 import process from "node:process";
 import { z } from "zod";
+import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, extractToolCallPayload, } from "../diagnostics.js";
 import { TOOLS } from "../tools-config.js";
 import { handleKbCheck } from "../tools/check.js";
 import { handleKbDelete } from "../tools/delete.js";
 import { handleKbQuery } from "../tools/query.js";
 import { handleKbUpsert } from "../tools/upsert.js";
-import { ensureProlog, inFlightRequests, isShuttingDown } from "./session.js";
+import { activeBranchName, ensureProlog, inFlightRequests, isShuttingDown, prologProcess, } from "./session.js";
 const ACTIVE_TOOLS = TOOLS;
 function debugLog(...args) {
     if (process.env.KIBI_MCP_DEBUG) {
@@ -131,12 +132,16 @@ export function jsonSchemaToZod(schema) {
 }
 function addTool(server, name, description, inputSchema, handler) {
     const wrappedHandler = async (args) => {
+        const startedAt = new Date();
+        // Extract telemetry in diagnostic mode
+        const { businessArgs, telemetry } = DIAGNOSTIC_MODE_ENABLED
+            ? extractToolCallPayload(args)
+            : { businessArgs: args, telemetry: null };
         try {
             // Validate that args is a valid object
             if (typeof args !== "object" || args === null) {
                 throw new Error(`Invalid arguments for tool ${name}: expected object, got ${typeof args}`);
             }
-            const businessArgs = args;
             // Check if shutting down before processing
             if (isShuttingDown) {
                 throw new Error(`Tool ${name} rejected: server is shutting down`);
@@ -155,7 +160,47 @@ function addTool(server, name, description, inputSchema, handler) {
             inFlightRequests.set(requestId, handlerPromise);
             try {
                 // Execute handler
-                return await handlerPromise;
+                const result = await handlerPromise;
+                // Log usage in diagnostic mode
+                if (DIAGNOSTIC_MODE_ENABLED) {
+                    const finishedAt = new Date();
+                    appendUsageLogLine({
+                        timestamp: finishedAt.toISOString(),
+                        request_id: requestId,
+                        tool: name,
+                        telemetry,
+                        business_args: businessArgs,
+                        status: "success",
+                        started_at: startedAt.toISOString(),
+                        finished_at: finishedAt.toISOString(),
+                        duration_ms: finishedAt.getTime() - startedAt.getTime(),
+                        prolog_pid: prologProcess?.getPid() ?? null,
+                        active_branch: activeBranchName,
+                    });
+                }
+                return result;
+            }
+            catch (error) {
+                // Log error in diagnostic mode
+                if (DIAGNOSTIC_MODE_ENABLED) {
+                    const finishedAt = new Date();
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    appendUsageLogLine({
+                        timestamp: finishedAt.toISOString(),
+                        request_id: requestId,
+                        tool: name,
+                        telemetry,
+                        business_args: businessArgs,
+                        status: "error",
+                        started_at: startedAt.toISOString(),
+                        finished_at: finishedAt.toISOString(),
+                        duration_ms: finishedAt.getTime() - startedAt.getTime(),
+                        prolog_pid: prologProcess?.getPid() ?? null,
+                        active_branch: activeBranchName,
+                        error_message: err.message,
+                    });
+                }
+                throw error;
             }
             finally {
                 // Always clean up from Map when done (success or failure)

package/dist/server.js

@@ -15,17 +15,24 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { initializeDiagnosticMode } from "./diagnostics.js";
 import { loadDefaultEnvFile } from "./env.js";
 import { setupDocsAndPrompts } from "./server/docs.js";
 import { registerAllTools } from "./server/tools.js";
 import { connectTransport, setupTransportHandlers, } from "./server/transport.js";
+// Read version from package.json to prevent drift
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const VERSION = packageJson.version ?? "0.1.0";
 export async function startServer() {
     // Load environment configuration
     loadDefaultEnvFile();
+    // Initialize diagnostic mode if --diagnostic-mode flag is present
+    initializeDiagnosticMode();
     // Create MCP server
-    const server = new McpServer({ name: "kibi-mcp", version: "0.2.1" });
+    const server = new McpServer({ name: "kibi-mcp", version: VERSION });
     // Setup documentation resources and prompts
     setupDocsAndPrompts(server);
     // Register all KB tools

package/dist/tools/query.js

@@ -45,9 +45,7 @@ export async function handleKbQuery(prolog, args) {
             goal = `findall(['${safeId}',Type,Props], kb_entity('${safeId}', Type, Props), Results)`;
         }
         else if (tags && tags.length > 0) {
-            // TODO: Reintroduce server-side (Prolog) tag filtering once normalization
-            // issues with tag list formats are resolved, to avoid fetching all entities
-            // before filtering in JS for large knowledge bases.
+            // JS-side fallback until REQ-mcp-tag-filtering-server-side is implemented.
             if (type) {
                 const safeType = escapeAtomContent(type);
                 goal = `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;

package/dist/tools-config.js

@@ -14,8 +14,9 @@
 
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
-*/
-export const TOOLS = [
+ */
+import { DIAGNOSTIC_MODE_ENABLED, DIAGNOSTIC_TELEMETRY_SCHEMA, } from "./diagnostics.js";
+const BASE_TOOLS = [
     // implements REQ-002
     {
         name: "kb_query",
@@ -216,3 +217,31 @@ export const TOOLS = [
         },
     },
 ];
+/**
+ * Inject _diagnostic_telemetry schema into tool inputs when diagnostic mode is enabled.
+ */
+function withDiagnosticTelemetrySchema(tools) {
+    return tools.map((tool) => {
+        const schema = tool.inputSchema;
+        const properties = schema.properties && typeof schema.properties === "object"
+            ? schema.properties
+            : {};
+        return {
+            ...tool,
+            inputSchema: {
+                ...schema,
+                properties: {
+                    ...properties,
+                    _diagnostic_telemetry: DIAGNOSTIC_TELEMETRY_SCHEMA,
+                },
+            },
+        };
+    });
+}
+/**
+ * Active tools list.
+ * In diagnostic mode, all tools include the _diagnostic_telemetry parameter.
+ */
+export const TOOLS = DIAGNOSTIC_MODE_ENABLED
+    ? withDiagnosticTelemetrySchema(BASE_TOOLS)
+    : BASE_TOOLS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -40,7 +40,8 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@types/node": "latest"
+    "@types/node": "latest",
+    "typescript": "^5.7.0"
   },
   "license": "AGPL-3.0-or-later",
   "author": "Piotr Franczyk",