kibi-mcp 0.2.0 → 0.2.2

package/dist/server.js

@@ -17,6 +17,7 @@
 */
 import fs from "node:fs";
 import { createRequire } from "node:module";
+import path from "node:path";
 /*
  How to apply this header to source files (examples)
 
@@ -51,13 +52,64 @@ import { PrologProcess } from "kibi-cli/prolog";
 import { copyCleanSnapshot, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, } from "kibi-cli/public/branch-resolver";
 import { z } from "zod";
 import { loadDefaultEnvFile } from "./env.js";
-import { attachMcpcat } from "./mcpcat.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 { resolveKbPath, resolveWorkspaceRoot } from "./workspace.js";
+const DIAGNOSTIC_MODE_FLAG = "--diagnostic-mode";
+const DIAGNOSTIC_MODE_ENABLED = process.argv.includes(DIAGNOSTIC_MODE_FLAG);
+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.",
+        },
+    },
+};
+function withDiagnosticTelemetrySchema(tools) {
+    return tools.map((tool) => {
+        const schema = tool.inputSchema && typeof tool.inputSchema === "object"
+            ? tool.inputSchema
+            : {};
+        const properties = schema.properties && typeof schema.properties === "object"
+            ? schema.properties
+            : {};
+        return {
+            ...tool,
+            inputSchema: {
+                ...schema,
+                properties: {
+                    ...properties,
+                    _diagnostic_telemetry: DIAGNOSTIC_TELEMETRY_SCHEMA,
+                },
+            },
+        };
+    });
+}
+const BASE_TOOLS = TOOLS;
+const ACTIVE_TOOLS = DIAGNOSTIC_MODE_ENABLED
+    ? withDiagnosticTelemetrySchema(BASE_TOOLS)
+    : BASE_TOOLS;
 function renderToolsDoc() {
     const lines = [
         "# kibi-mcp Tools",
@@ -67,7 +119,7 @@ function renderToolsDoc() {
         "| Tool | Summary | Required Parameters |",
         "| --- | --- | --- |",
     ];
-    for (const tool of TOOLS) {
+    for (const tool of ACTIVE_TOOLS) {
         const required = Array.isArray(tool.inputSchema?.required)
             ? tool.inputSchema.required.join(", ")
             : "none";
@@ -239,10 +291,70 @@ function getHelpText(topic) {
 let prologProcess = null;
 let isInitialized = false;
 let activeBranchName = "develop";
+let ensurePrologTail = Promise.resolve();
 // Shutdown tracking state
 let isShuttingDown = false;
 let shutdownTimeout = null;
 const inFlightRequests = new Map();
+let diagnosticUsageLogPath = null;
+function extractToolCallPayload(args) {
+    const { _diagnostic_telemetry, ...businessArgs } = args;
+    const telemetry = _diagnostic_telemetry && typeof _diagnostic_telemetry === "object"
+        ? _diagnostic_telemetry
+        : null;
+    return { businessArgs, telemetry };
+}
+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",
+    });
+}
+function extractContradictionSignal(tool, args, result) {
+    if (tool !== "kb_upsert") {
+        return undefined;
+    }
+    const id = typeof args.id === "string" ? args.id : undefined;
+    if (!id) {
+        return undefined;
+    }
+    const structured = result && typeof result === "object"
+        ? result
+            .structuredContent
+        : undefined;
+    if (!structured || typeof structured !== "object") {
+        return undefined;
+    }
+    const rawCount = structured.contradiction_pairs_detected;
+    const count = typeof rawCount === "number" ? rawCount : Number(rawCount);
+    if (!Number.isFinite(count) || count < 0) {
+        return undefined;
+    }
+    return {
+        attempted_entity_id: id,
+        contradiction_pairs_detected: count,
+    };
+}
+async function probeContradictionsForReq(reqId) {
+    if (!prologProcess?.isRunning()) {
+        return { count: null, error: "prolog_process_not_running" };
+    }
+    const escaped = reqId.replace(/'/g, "\\'");
+    const goal = `aggregate_all(count, (contradicting_reqs(A, B, _), (A = '${escaped}' ; B = '${escaped}' ; A = 'file:///${escaped}' ; B = 'file:///${escaped}')), Count)`;
+    const result = await prologProcess.query(goal);
+    if (!result.success) {
+        return { count: null, error: result.error ?? "probe_query_failed" };
+    }
+    const count = Number(result.bindings.Count);
+    if (!Number.isFinite(count) || count < 0) {
+        return { count: null, error: "invalid_probe_count" };
+    }
+    return { count };
+}
 function ensureBranchKbExists(workspaceRoot, branch) {
     if (!isValidBranchName(branch)) {
         throw new Error(`Invalid branch name: ${branch}`);
@@ -309,7 +421,7 @@ async function initiateGracefulShutdown(exitCode = 0) {
     // Exit
     process.exit(exitCode);
 }
-async function ensureProlog() {
+async function ensurePrologUnsafe() {
     const workspaceRoot = resolveWorkspaceRoot();
     // Determine target branch: respect KIBI_BRANCH override or resolve from git
     const envBranch = process.env.KIBI_BRANCH?.trim();
@@ -410,6 +522,20 @@ async function ensureProlog() {
     debugLog(`[KIBI-MCP] KB attached: ${kbPath}`);
     return prologProcess;
 }
+async function ensureProlog() {
+    const previous = ensurePrologTail;
+    let release;
+    ensurePrologTail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    try {
+        return await ensurePrologUnsafe();
+    }
+    finally {
+        release();
+    }
+}
 function jsonSchemaToZod(schema) {
     if (!schema || typeof schema !== "object") {
         return z.any();
@@ -512,32 +638,89 @@ function jsonSchemaToZod(schema) {
 }
 function addTool(server, name, description, inputSchema, handler) {
     const wrappedHandler = async (args) => {
+        let telemetry = null;
+        let businessArgs = {};
+        const startedAt = new Date();
         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}`);
             }
+            if (DIAGNOSTIC_MODE_ENABLED) {
+                const payload = extractToolCallPayload(args);
+                telemetry = payload.telemetry;
+                businessArgs = payload.businessArgs;
+            }
+            else {
+                businessArgs = args;
+            }
             // Check if shutting down before processing
             if (isShuttingDown) {
                 throw new Error(`Tool ${name} rejected: server is shutting down`);
             }
             // Extract or generate requestId from args
-            const requestIdArg = args._requestId;
+            const requestIdArg = businessArgs._requestId;
             const requestId = typeof requestIdArg === "string"
                 ? requestIdArg
                 : `${name}-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
             // Log tool call for debugging (to stderr to avoid breaking stdio protocol)
             if (process.env.KIBI_MCP_DEBUG) {
-                console.error(`[KIBI-MCP] Tool called: ${name} (requestId: ${requestId}) with args:`, JSON.stringify(args));
+                console.error(`[KIBI-MCP] Tool called: ${name} (requestId: ${requestId}) with args:`, JSON.stringify(businessArgs));
             }
             // Track the handler promise in inFlightRequests Map
-            const handlerPromise = handler(args);
+            const handlerPromise = handler(businessArgs);
             inFlightRequests.set(requestId, handlerPromise);
             try {
                 // Execute handler
                 const result = await handlerPromise;
+                const finishedAt = new Date();
+                const contradictionSignal = extractContradictionSignal(name, businessArgs, result);
+                let contradictionSignalFinal = contradictionSignal;
+                if (name === "kb_upsert" && typeof businessArgs.id === "string") {
+                    const probe = businessArgs.type === "req"
+                        ? await probeContradictionsForReq(businessArgs.id)
+                        : { count: null, error: "non_req_entity" };
+                    contradictionSignalFinal = {
+                        attempted_entity_id: businessArgs.id,
+                        contradiction_pairs_detected: probe.count !== null ? probe.count : -1,
+                        probe_error: probe.error,
+                    };
+                }
+                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,
+                    contradiction_signal: contradictionSignalFinal,
+                });
                 return result;
             }
+            catch (error) {
+                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)
                 inFlightRequests.delete(requestId);
@@ -556,8 +739,12 @@ function addTool(server, name, description, inputSchema, handler) {
 }
 export async function startServer() {
     loadDefaultEnvFile();
-    const server = new McpServer({ name: "kibi-mcp", version: "0.2.0" });
-    attachMcpcat(server);
+    if (DIAGNOSTIC_MODE_ENABLED) {
+        const workspaceRoot = resolveWorkspaceRoot();
+        diagnosticUsageLogPath = path.join(workspaceRoot, ".kb", "usage.log");
+        process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
+    }
+    const server = new McpServer({ name: "kibi-mcp", version: "0.2.1" });
     for (const prompt of PROMPTS) {
         server.prompt(prompt.name, prompt.description, async () => ({
             messages: [
@@ -580,7 +767,7 @@ export async function startServer() {
         }));
     }
     const toolDef = (name) => {
-        const t = TOOLS.find((t) => t.name === name);
+        const t = ACTIVE_TOOLS.find((t) => t.name === name);
         if (!t)
             throw new Error(`Unknown tool: ${name}`);
         return t;

package/dist/tools/symbols.js

@@ -44,9 +44,9 @@
 */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { resolveWorkspaceRoot } from "../workspace.js";
-import { enrichSymbolCoordinates, } from "kibi-cli/extractors/symbols-coordinator";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
+import { enrichSymbolCoordinates, } from "kibi-cli/extractors/symbols-coordinator";
+import { resolveWorkspaceRoot } from "../workspace.js";
 const COMMENT_BLOCK = `# symbols.yaml
 # AUTHORED fields (edit freely):
 #   id, title, sourceFile, links, status, tags, owner, priority
@@ -177,11 +177,18 @@ export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = re
     }
     return { refreshed, found: true };
 }
-function resolveManifestPath(workspaceRoot) {
+export function resolveManifestPath(workspaceRoot) {
     const configPath = path.join(workspaceRoot, ".kb", "config.json");
     if (existsSync(configPath)) {
         try {
             const config = JSON.parse(readFileSync(configPath, "utf8"));
+            // Prefer paths.symbols (new standard) over symbolsManifest (legacy)
+            if (config.paths?.symbols) {
+                return path.isAbsolute(config.paths.symbols)
+                    ? config.paths.symbols
+                    : path.resolve(workspaceRoot, config.paths.symbols);
+            }
+            // Backward compatibility: check legacy symbolsManifest field
             if (config.symbolsManifest) {
                 return path.isAbsolute(config.symbolsManifest)
                     ? config.symbolsManifest

package/dist/tools/upsert.js

@@ -118,6 +118,10 @@ export async function handleKbUpsert(prolog, args) {
         }
         // Save KB to disk
         await prolog.query("kb_save");
+        let contradictionPairsDetected;
+        if (type === "req") {
+            contradictionPairsDetected = await detectContradictionPairs(prolog, id);
+        }
         if (type === "symbol") {
             try {
                 await refreshCoordinatesForSymbolId(id);
@@ -133,13 +137,16 @@ export async function handleKbUpsert(prolog, args) {
             content: [
                 {
                     type: "text",
-                    text: `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
+                    text: contradictionPairsDetected && contradictionPairsDetected > 0
+                        ? `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s). Contradiction probe detected ${contradictionPairsDetected} potential conflict pair(s).`
+                        : `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
                 },
             ],
             structuredContent: {
                 created,
                 updated,
                 relationships_created: relationshipsCreated,
+                contradiction_pairs_detected: contradictionPairsDetected,
             },
         };
     }
@@ -148,6 +155,17 @@ export async function handleKbUpsert(prolog, args) {
         throw new Error(`Upsert execution failed: ${message}`);
     }
 }
+async function detectContradictionPairs(prolog, reqId) {
+    const escaped = escapeAtom(reqId);
+    const goal = `aggregate_all(count, (contradicting_reqs(A, B, _), (A = '${escaped}' ; B = '${escaped}' ; A = 'file:///${escaped}' ; B = 'file:///${escaped}')), Count)`;
+    const result = await prolog.query(goal);
+    if (!result.success) {
+        return 0;
+    }
+    const raw = result.bindings.Count;
+    const count = Number(raw);
+    return Number.isFinite(count) ? count : 0;
+}
 /**
  * Build Prolog property list from entity object
  * Returns simple Key=Value format without typed literals

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,8 +9,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.2.0",
-    "kibi-core": "^0.1.6",
+    "kibi-cli": "^0.2.3",
+    "kibi-core": "^0.1.7",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"
@@ -27,7 +27,10 @@
     "build": "tsc -p tsconfig.json",
     "prepack": "npm run build"
   },
-  "files": ["dist", "bin"],
+  "files": [
+    "dist",
+    "bin"
+  ],
   "engines": {
     "node": ">=18",
     "bun": ">=1.0"

package/dist/mcpcat.js

@@ -1,129 +0,0 @@
-/*
- 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/>.
-*/
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
-import { createHash } from "node:crypto";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import * as mcpcat from "mcpcat";
-import { resolveWorkspaceRoot } from "./workspace.js";
-const projectId = (process.env.MCPCAT_PROJECT_ID ?? "").trim();
-const trackedIdentity = resolveTrackedIdentity();
-/**
- * Attach mcpcat analytics tracking to the MCP server.
- *
- * NOTE ON SESSIONS: With stdio transport, many MCP clients (including OpenCode)
- * spawn a new process for each tool call. This means each tool call gets a new
- * MCP session ID, resulting in single-tool-call "sessions" in mcpcat.
- *
- * This is expected behavior for stdio transport - each process IS a different
- * session. User identity (via the identify() function) still provides useful
- * aggregation across all tool calls from the same user/machine.
- *
- * For true session aggregation, clients would need to either:
- * 1. Use HTTP transport with persistent connections
- * 2. Maintain long-lived stdio connections across multiple tool calls
- * 3. Implement custom session headers
- */
-export function attachMcpcat(server) {
-    if (!projectId) {
-        return;
-    }
-    try {
-        mcpcat.track(server, projectId, {
-            identify: async () => trackedIdentity,
-            enableReportMissing: false, // Don't add get_more_tools tool - it's internal
-            enableTracing: true,
-            enableToolCallContext: false, // Don't inject context parameter into tools
-        });
-        if (process.env.KIBI_MCP_DEBUG) {
-            console.error(`[KIBI-MCP] MCPcat tracking enabled for project ${projectId}`);
-        }
-    }
-    catch (error) {
-        const details = error instanceof Error ? error.message : String(error);
-        console.error(`[KIBI-MCP] MCPcat tracking attach failed: ${details}`);
-    }
-}
-function resolveTrackedIdentity() {
-    const explicitUserId = readEnv("MCPCAT_USER_ID");
-    if (explicitUserId) {
-        return {
-            userId: explicitUserId,
-            userName: readEnv("MCPCAT_USER_NAME") ?? "local-operator",
-            userData: { identitySource: "env" },
-        };
-    }
-    const repoRoot = findRepoRoot(resolveWorkspaceRoot());
-    const repoName = path.basename(repoRoot);
-    const username = readEnv("USER") ?? readEnv("USERNAME") ?? "unknown-user";
-    const host = os.hostname() || "unknown-host";
-    const stableId = createHash("sha256")
-        .update(`${host}:${username}:${repoRoot}`)
-        .digest("hex")
-        .slice(0, 24);
-    return {
-        userId: `anon_${stableId}`,
-        userName: `local-${repoName}`,
-        userData: { identitySource: "host-user-repo-hash", repo: repoName },
-    };
-}
-function readEnv(name) {
-    const value = process.env[name]?.trim();
-    return value ? value : null;
-}
-function findRepoRoot(startDir) {
-    let current = path.resolve(startDir);
-    while (true) {
-        const gitMarker = path.join(current, ".git");
-        if (fs.existsSync(gitMarker)) {
-            return current;
-        }
-        const parent = path.dirname(current);
-        if (parent === current) {
-            return path.resolve(startDir);
-        }
-        current = parent;
-    }
-}