kibi-mcp 0.3.1 → 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/session.js

@@ -101,6 +101,7 @@ export async function initiateGracefulShutdown(exitCode = 0) {
     // Exit
     process.exit(exitCode);
 }
+// implements REQ-008
 async function ensurePrologUnsafe() {
     const workspaceRoot = resolveWorkspaceRoot();
     // Determine target branch: respect KIBI_BRANCH override or resolve from git
@@ -131,7 +132,11 @@ async function ensurePrologUnsafe() {
         }
         // Branch changed - need to detach and re-attach
         debugLog(`[KIBI-MCP] Branch changed: ${activeBranchName} -> ${targetBranch}`);
-        // Detach from old KB
+        // Persist and detach from old KB
+        const saveResult = await prologProcess.query("kb_save");
+        if (!saveResult.success) {
+            throw new Error(`Failed to save old KB before detach: ${saveResult.error || "Unknown error"}`);
+        }
         const detachResult = await prologProcess.query("kb_detach");
         if (!detachResult.success) {
             debugLog(`[KIBI-MCP] Warning: failed to detach from old KB: ${detachResult.error || "Unknown error"}`);

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/check.js

@@ -14,11 +14,11 @@
 
  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 { existsSync } from "node:fs";
+ */
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
-import { parsePairList } from "./prolog-list.js";
+import { resolveWorkspaceRoot } from "../workspace.js";
 const require = createRequire(import.meta.url);
 function resolveChecksPlPath() {
     const overrideChecksPath = process.env.KIBI_CHECKS_PL_PATH;
@@ -38,6 +38,23 @@ function resolveChecksPlPath() {
     }
     throw new Error("Unable to resolve checks.pl path");
 }
+const ALL_RULES = [
+    "must-priority-coverage",
+    "no-dangling-refs",
+    "no-cycles",
+    "required-fields",
+    "symbol-coverage",
+    "symbol-traceability",
+    "deprecated-adr-no-successor",
+    "domain-contradictions",
+];
+const RULE_NAMES = new Set(ALL_RULES);
+const DEFAULT_CHECKS_CONFIG = {
+    rules: Object.fromEntries(ALL_RULES.map((rule) => [rule, true])),
+    symbolTraceability: {
+        requireAdr: false,
+    },
+};
 function formatDiagnosticsForMcp(diagnostics) {
     return diagnostics.map((d) => ({
         category: d.category,
@@ -47,85 +64,96 @@ function formatDiagnosticsForMcp(diagnostics) {
         suggestion: d.suggestion,
     }));
 }
+// implements REQ-002
+function loadChecksConfig(workspaceRoot) {
+    const configPath = path.join(workspaceRoot, ".kb", "config.json");
+    if (!existsSync(configPath)) {
+        return DEFAULT_CHECKS_CONFIG;
+    }
+    try {
+        const content = readFileSync(configPath, "utf8");
+        const parsed = JSON.parse(content);
+        const parsedRules = parsed.checks?.rules;
+        const normalizedRules = {
+            ...DEFAULT_CHECKS_CONFIG.rules,
+        };
+        if (parsedRules && typeof parsedRules === "object") {
+            for (const [key, value] of Object.entries(parsedRules)) {
+                if (typeof value === "boolean") {
+                    normalizedRules[key] = value;
+                }
+                // Ignore non-boolean values (they are not added to normalizedRules, preserving defaults)
+            }
+        }
+        const parsedSt = parsed.checks?.symbolTraceability;
+        const normalizedSt = { ...DEFAULT_CHECKS_CONFIG.symbolTraceability };
+        if (parsedSt && typeof parsedSt === "object") {
+            if (typeof parsedSt.requireAdr === "boolean") {
+                normalizedSt.requireAdr = parsedSt.requireAdr;
+            }
+        }
+        return {
+            rules: normalizedRules,
+            symbolTraceability: normalizedSt,
+        };
+    }
+    catch {
+        return DEFAULT_CHECKS_CONFIG;
+    }
+}
+// implements REQ-002
+function getEffectiveRules(configRules, requestedRules) {
+    const effective = new Set();
+    for (const rule of ALL_RULES) {
+        const enabled = configRules[rule] ?? true;
+        if (enabled) {
+            effective.add(rule);
+        }
+    }
+    if (requestedRules && requestedRules.length > 0) {
+        const allowed = new Set(requestedRules.filter((rule) => RULE_NAMES.has(rule)));
+        for (const rule of Array.from(effective)) {
+            if (!allowed.has(rule)) {
+                effective.delete(rule);
+            }
+        }
+    }
+    return effective;
+}
 /**
  * Handle kb_check tool calls - run validation rules on the KB
  * Reuses validation logic from CLI check command
  */
+// implements REQ-002
 export async function handleKbCheck(prolog, args) {
     const { rules } = args;
     try {
-        const violations = [];
-        let allEntityIds = null;
-        // Run all validation rules (or specific rules if provided)
-        const allRules = [
-            "must-priority-coverage",
-            "no-dangling-refs",
-            "no-cycles",
-            "required-fields",
-            "symbol-coverage",
-            "symbol-traceability",
-            "deprecated-adr-no-successor",
-            "domain-contradictions",
-        ];
-        const rulesToRun = rules && rules.length > 0 ? rules : allRules;
-        const rulesAllowlist = new Set(rulesToRun);
-        const aggregatedViolations = await runAggregatedChecks(prolog, rulesAllowlist);
-        if (aggregatedViolations) {
-            const diagnostics = aggregatedViolations.map((v) => ({
-                category: "SYNC_ERROR",
-                severity: "error",
-                message: v.description,
-                file: v.source,
-                suggestion: v.suggestion,
-            }));
-            const summary = aggregatedViolations.length === 0
-                ? "No violations found"
-                : `${aggregatedViolations.length} violations found`;
+        const workspaceRoot = resolveWorkspaceRoot();
+        const checksConfig = loadChecksConfig(workspaceRoot);
+        const rulesAllowlist = getEffectiveRules(checksConfig.rules, rules);
+        if (rulesAllowlist.size === 0) {
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: summary,
-                    },
-                ],
+                content: [{ type: "text", text: "No violations found" }],
                 structuredContent: {
-                    violations: aggregatedViolations,
-                    count: aggregatedViolations.length,
-                    diagnostics: formatDiagnosticsForMcp(diagnostics),
+                    violations: [],
+                    count: 0,
+                    diagnostics: [],
                 },
             };
         }
-        if (rulesToRun.includes("must-priority-coverage")) {
-            violations.push(...(await checkMustPriorityCoverage(prolog)));
-        }
-        if (rulesToRun.includes("no-dangling-refs")) {
-            violations.push(...(await checkNoDanglingRefs(prolog)));
-        }
-        if (rulesToRun.includes("no-cycles")) {
-            violations.push(...(await checkNoCycles(prolog)));
-        }
-        if (rulesToRun.includes("required-fields")) {
-            if (!allEntityIds) {
-                allEntityIds = await getAllEntityIds(prolog);
-            }
-            violations.push(...(await checkRequiredFields(prolog, allEntityIds)));
-        }
-        if (rulesToRun.includes("symbol-coverage")) {
-            violations.push(...(await checkSymbolCoverage(prolog)));
-        }
-        if (rulesToRun.includes("symbol-traceability")) {
-            violations.push(...(await checkSymbolTraceability(prolog, false)));
-        }
-        const diagnostics = violations.map((v) => ({
+        // Run aggregated checks using same approach as CLI
+        // This now runs ALL rules including symbol-traceability
+        const aggregatedViolations = await runAggregatedChecks(prolog, rulesAllowlist, checksConfig.symbolTraceability.requireAdr);
+        const diagnostics = aggregatedViolations.map((v) => ({
             category: "SYNC_ERROR",
             severity: "error",
             message: v.description,
             file: v.source,
             suggestion: v.suggestion,
         }));
-        const summary = violations.length === 0
+        const summary = aggregatedViolations.length === 0
             ? "No violations found"
-            : `${violations.length} violations found`;
+            : `${aggregatedViolations.length} violations found`;
         return {
             content: [
                 {
@@ -134,8 +162,8 @@ export async function handleKbCheck(prolog, args) {
                 },
             ],
             structuredContent: {
-                violations,
-                count: violations.length,
+                violations: aggregatedViolations,
+                count: aggregatedViolations.length,
                 diagnostics: formatDiagnosticsForMcp(diagnostics),
             },
         };
@@ -145,341 +173,49 @@ export async function handleKbCheck(prolog, args) {
         throw new Error(`Check execution failed: ${message}`);
     }
 }
-async function runAggregatedChecks(prolog, rulesAllowlist) {
+// implements REQ-002
+async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr) {
+    const violations = [];
     const checksPlPath = resolveChecksPlPath();
     const normalizedChecksPlPath = checksPlPath.replace(/\\/g, "/");
     const checksPlPathEscaped = normalizedChecksPlPath.replace(/'/g, "''");
-    const violations = [];
-    const ruleToPredicate = {
-        "must-priority-coverage": "check_must_priority_coverage",
-        "no-dangling-refs": "check_no_dangling_refs",
-        "no-cycles": "check_no_cycles",
-        "required-fields": "check_required_fields",
-        "symbol-coverage": "check_symbol_coverage",
-    };
-    for (const rule of rulesAllowlist) {
-        const predicate = ruleToPredicate[rule];
-        if (!predicate) {
-            continue;
-        }
-        const query = `(use_module('${checksPlPathEscaped}'), call(checks:${predicate}(Violations)), findall(_{rule:Rule,entityId:EntityId,description:Description,suggestion:Suggestion,source:Source}, member(violation(Rule, EntityId, Description, Suggestion, Source), Violations), Rows), call(checks:atom_json_dict(JsonString, Rows, [])))`;
-        const result = await prolog.query(query);
-        if (!result.success || !result.bindings.JsonString) {
-            return null;
-        }
-        let parsedRows;
-        try {
-            parsedRows = JSON.parse(result.bindings.JsonString);
-            if (typeof parsedRows === "string") {
-                parsedRows = JSON.parse(parsedRows);
-            }
-        }
-        catch {
-            return null;
-        }
-        if (!Array.isArray(parsedRows)) {
-            return null;
-        }
-        for (const row of parsedRows) {
-            if (!row || typeof row !== "object") {
-                continue;
-            }
-            const raw = row;
-            const rule = typeof raw.rule === "string" ? raw.rule : "";
-            if (!rulesAllowlist.has(rule)) {
-                continue;
-            }
-            const entityId = typeof raw.entityId === "string"
-                ? raw.entityId
-                : typeof raw.entity_id === "string"
-                    ? raw.entity_id
-                    : "";
-            const description = typeof raw.description === "string" ? raw.description : "";
-            const suggestion = typeof raw.suggestion === "string" ? raw.suggestion : undefined;
-            const source = typeof raw.source === "string" ? raw.source : undefined;
-            if (!rule || !entityId || !description) {
-                continue;
-            }
-            violations.push({
-                rule,
-                entityId,
-                description,
-                suggestion,
-                source,
-            });
-        }
-    }
-    return violations;
-}
-async function checkSymbolTraceability(prolog, requireAdr) {
-    const violations = [];
+    // Use check_all_json_with_options if available, otherwise fall back to check_all_json
     const requireAdrStr = requireAdr ? "true" : "false";
-    const result = await prolog.query(`findall(violation(Rule, EntityId, Desc, Sugg, Src), checks:symbol_traceability_violation(${requireAdrStr}, violation(Rule, EntityId, Desc, Sugg, Src)), Violations)`);
-    if (!result.success || !result.bindings.Violations) {
-        return violations;
-    }
-    const violationsStr = result.bindings.Violations;
-    if (violationsStr && violationsStr !== "[]") {
-        const violationRegex = /violation\(([^,]+),'?([^',]+)'?,([^,]+),([^,]+),'?([^']*)'?\)/g;
-        let match;
-        do {
-            match = violationRegex.exec(violationsStr);
-            if (match) {
-                violations.push({
-                    rule: match[1].trim().replace(/^'|'$/g, ""),
-                    entityId: match[2].trim(),
-                    description: match[3].trim().replace(/^"|"$/g, ""),
-                    suggestion: match[4].trim().replace(/^"|"$/g, ""),
-                    source: match[5].trim() || undefined,
-                });
-            }
-        } while (match);
-    }
-    return violations;
-}
-async function checkMustPriorityCoverage(prolog) {
-    const violations = [];
-    const gapsResult = await prolog.query("setof([Req,Reason], coverage_gap(Req, Reason), Rows)");
-    if (!gapsResult.success || !gapsResult.bindings.Rows) {
-        return violations;
-    }
-    const gaps = parsePairList(gapsResult.bindings.Rows);
-    for (const [reqId, reason] of gaps) {
-        const entityResult = await prolog.query(`kb_entity('${reqId}', req, Props)`);
-        let source = "";
-        if (entityResult.success && entityResult.bindings.Props) {
-            const propsStr = entityResult.bindings.Props;
-            const sourceMatch = propsStr.match(/source\s*=\s*\^\^?\("([^"]+)"/);
-            if (sourceMatch) {
-                source = sourceMatch[1];
-            }
-        }
-        const missing = [];
-        if (reason.includes("scenario")) {
-            missing.push("scenario");
-        }
-        if (reason.includes("test")) {
-            missing.push("test");
-        }
-        violations.push({
-            rule: "must-priority-coverage",
-            entityId: reqId,
-            description: `Must-priority requirement lacks ${missing.join(" and ")} coverage`,
-            source,
-            suggestion: missing
-                .map((m) => `Create ${m} that covers this requirement`)
-                .join("; "),
-        });
-    }
-    return violations;
-}
-async function getAllEntityIds(prolog, type) {
-    const typeFilter = type ? `, Type = ${type}` : "";
-    const query = `findall(Id, (kb_entity(Id, Type, _)${typeFilter}), Ids)`;
+    const query = `(use_module('${checksPlPathEscaped}'),
+    (   predicate_property(checks:check_all_json_with_options(_, _), _)
+    ->  call(checks:check_all_json_with_options(JsonString, ${requireAdrStr}))
+    ;   call(checks:check_all_json(JsonString))
+    ))`;
     const result = await prolog.query(query);
-    if (!result.success || !result.bindings.Ids) {
-        return [];
-    }
-    const idsStr = result.bindings.Ids;
-    const match = idsStr.match(/\[(.*)\]/);
-    if (!match) {
-        return [];
-    }
-    const content = match[1].trim();
-    if (!content) {
-        return [];
+    if (!result.success) {
+        throw new Error(`Aggregated checks query failed: ${result.error || "Unknown error"}`);
     }
-    return content.split(",").map((id) => id.trim().replace(/^'|'$/g, ""));
-}
-async function checkNoDanglingRefs(prolog) {
-    const violations = [];
-    // Get all entity IDs once
-    const allEntityIds = new Set(await getAllEntityIds(prolog));
-    // Get all relationships by querying all known relationship types
-    const relTypes = [
-        "depends_on",
-        "verified_by",
-        "validates",
-        "specified_by",
-        "relates_to",
-    ];
-    const allRels = [];
-    for (const relType of relTypes) {
-        const relsResult = await prolog.query(`findall([From,To], kb_relationship(${relType}, From, To), Rels)`);
-        if (relsResult.success && relsResult.bindings.Rels) {
-            const relsStr = relsResult.bindings.Rels;
-            const match = relsStr.match(/\[(.*)\]/);
-            if (match) {
-                const content = match[1].trim();
-                if (content) {
-                    const relMatches = content.matchAll(/\[([^,]+),([^\]]+)\]/g);
-                    for (const relMatch of relMatches) {
-                        const fromId = relMatch[1].trim().replace(/^'|'$/g, "");
-                        const toId = relMatch[2].trim().replace(/^'|'$/g, "");
-                        allRels.push({ from: fromId, to: toId });
-                    }
-                }
-            }
-        }
-    }
-    // Check all collected relationships for dangling refs
-    for (const rel of allRels) {
-        if (!allEntityIds.has(rel.from)) {
-            violations.push({
-                rule: "no-dangling-refs",
-                entityId: rel.from,
-                description: `Relationship references non-existent entity: ${rel.from}`,
-                suggestion: "Remove relationship or create missing entity",
-            });
-        }
-        if (!allEntityIds.has(rel.to)) {
-            violations.push({
-                rule: "no-dangling-refs",
-                entityId: rel.to,
-                description: `Relationship references non-existent entity: ${rel.to}`,
-                suggestion: "Remove relationship or create missing entity",
-            });
-        }
-    }
-    return violations;
-}
-async function checkNoCycles(prolog) {
-    const violations = [];
-    // Get all depends_on relationships
-    const depsResult = await prolog.query("findall([From,To], kb_relationship(depends_on, From, To), Deps)");
-    if (!depsResult.success || !depsResult.bindings.Deps) {
-        return violations;
-    }
-    const depsStr = depsResult.bindings.Deps;
-    const match = depsStr.match(/\[(.*)\]/);
-    if (!match) {
-        return violations;
-    }
-    const content = match[1].trim();
-    if (!content) {
-        return violations;
-    }
-    // Build adjacency map
-    const graph = new Map();
-    const depMatches = content.matchAll(/\[([^,]+),([^\]]+)\]/g);
-    for (const depMatch of depMatches) {
-        const from = depMatch[1].trim().replace(/^'|'$/g, "");
-        const to = depMatch[2].trim().replace(/^'|'$/g, "");
-        if (!graph.has(from)) {
-            graph.set(from, []);
+    let violationsDict;
+    try {
+        const jsonString = result.bindings.JsonString;
+        if (!jsonString) {
+            throw new Error("No JSON string in binding");
         }
-        const fromList = graph.get(from);
-        if (fromList) {
-            fromList.push(to);
+        let parsed = JSON.parse(jsonString);
+        if (typeof parsed === "string") {
+            parsed = JSON.parse(parsed);
         }
+        violationsDict = parsed;
     }
-    // DFS to detect cycles
-    const visited = new Set();
-    const recStack = new Set();
-    function hasCycleDFS(node, path) {
-        visited.add(node);
-        recStack.add(node);
-        path.push(node);
-        const neighbors = graph.get(node) || [];
-        for (const neighbor of neighbors) {
-            if (!visited.has(neighbor)) {
-                const cyclePath = hasCycleDFS(neighbor, [...path]);
-                if (cyclePath)
-                    return cyclePath;
-            }
-            else if (recStack.has(neighbor)) {
-                // Cycle detected
-                return [...path, neighbor];
-            }
-        }
-        recStack.delete(node);
-        return null;
+    catch (parseError) {
+        throw new Error(`Failed to parse violations JSON: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
     }
-    // Check each node for cycles
-    for (const node of graph.keys()) {
-        if (!visited.has(node)) {
-            const cyclePath = hasCycleDFS(node, []);
-            if (cyclePath) {
-                const cycleWithSources = [];
-                for (const entityId of cyclePath) {
-                    const entityResult = await prolog.query(`kb_entity('${entityId}', _, Props)`);
-                    let sourceName = entityId;
-                    if (entityResult.success && entityResult.bindings.Props) {
-                        const propsStr = entityResult.bindings.Props;
-                        const sourceMatch = propsStr.match(/source\s*=\s*\^\^?\("([^"]+)"/);
-                        if (sourceMatch) {
-                            sourceName = path.basename(sourceMatch[1], ".md");
-                        }
-                    }
-                    cycleWithSources.push(sourceName);
-                }
+    for (const ruleViolations of Object.values(violationsDict)) {
+        for (const v of ruleViolations) {
+            const isAllowed = rulesAllowlist.has(v.rule);
+            if (isAllowed) {
                 violations.push({
-                    rule: "no-cycles",
-                    entityId: cyclePath[0],
-                    description: `Circular dependency detected: ${cycleWithSources.join(" → ")}`,
-                    suggestion: "Break the cycle by removing one of the depends_on relationships",
+                    rule: v.rule,
+                    entityId: v.entityId,
+                    description: v.description,
+                    suggestion: v.suggestion || undefined,
+                    source: v.source || undefined,
                 });
-                break; // Report only first cycle found
-            }
-        }
-    }
-    return violations;
-}
-async function checkRequiredFields(prolog, allEntityIds) {
-    const violations = [];
-    const required = [
-        "id",
-        "title",
-        "status",
-        "created_at",
-        "updated_at",
-        "source",
-    ];
-    for (const entityId of allEntityIds) {
-        const result = await prolog.query(`kb_entity('${entityId}', Type, Props)`);
-        if (result.success && result.bindings.Props) {
-            // Parse properties list: [key1=value1, key2=value2, ...]
-            const propsStr = result.bindings.Props;
-            const propKeys = new Set();
-            // Extract keys from Props
-            const keyMatches = propsStr.matchAll(/(\w+)\s*=/g);
-            for (const match of keyMatches) {
-                propKeys.add(match[1]);
-            }
-            // Check for missing required fields
-            for (const field of required) {
-                if (!propKeys.has(field)) {
-                    violations.push({
-                        rule: "required-fields",
-                        entityId: entityId,
-                        description: `Missing required field: ${field}`,
-                        suggestion: `Add ${field} to entity definition`,
-                    });
-                }
-            }
-        }
-    }
-    return violations;
-}
-async function checkSymbolCoverage(prolog) {
-    const violations = [];
-    const uncoveredResult = await prolog.query("setof(Symbol, (kb_entity(Symbol, symbol, _), \\+ transitively_implements(Symbol, _)), Symbols)");
-    if (uncoveredResult.success && uncoveredResult.bindings.Symbols) {
-        const symbolsStr = uncoveredResult.bindings.Symbols;
-        const match = symbolsStr.match(/\[(.*)\]/);
-        if (match) {
-            const content = match[1].trim();
-            if (content) {
-                const symbolMatches = content.matchAll(/'([^']+)'/g);
-                for (const symbolMatch of symbolMatches) {
-                    const symbolId = symbolMatch[1];
-                    violations.push({
-                        rule: "symbol-coverage",
-                        entityId: symbolId,
-                        description: "Code symbol is not traceable to any functional requirement.",
-                        suggestion: "Update symbols.yaml to link this symbol to a related requirement.",
-                    });
-                }
             }
         }
     }

package/dist/tools/delete.js

@@ -51,7 +51,10 @@ export async function handleKbDelete(prolog, args) {
             }
         }
         // Save KB to disk
-        await prolog.query("kb_save");
+        const saveResult = await prolog.query("kb_save");
+        if (!saveResult.success) {
+            throw new Error(`Failed to save KB after delete: ${saveResult.error || "Unknown error"}`);
+        }
         prolog.invalidateCache();
         return {
             content: [

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/upsert.js

@@ -27,6 +27,7 @@ const validateRelationship = ajv.compile(relationshipSchema);
  * Handle kb.upsert tool calls
  * Accepts { type, id, properties } — the flat format matching the tool schema.
  * Validates the assembled entity against JSON Schema before Prolog writes.
+ * implements REQ-002, REQ-011
  */
 export async function handleKbUpsert(prolog, args) {
     const { type, id, properties, relationships = [] } = args;
@@ -80,49 +81,56 @@ export async function handleKbUpsert(prolog, args) {
         for (const entity of entities) {
             const id = entity.id;
             const type = entity.type;
-            // Check if entity exists
+            // Check if entity exists before transaction (to determine created vs updated)
             const checkGoal = `once(kb_entity('${escapeAtom(id)}', _, _))`;
             const checkResult = await prolog.query(checkGoal);
             const isUpdate = checkResult.success;
             // Build property list for Prolog
             const props = buildPropertyList(entity);
-            // Assert entity (upsert)
+            // Build relationship goals
+            const relationshipGoals = [];
+            for (const rel of relationships) {
+                const relType = rel.type;
+                const from = rel.from;
+                const to = rel.to;
+                const metadata = buildRelationshipMetadata(rel);
+                relationshipGoals.push(`kb_assert_relationship(${relType}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${metadata})`);
+            }
+            // Build atomic transaction goal wrapping entity + all relationships
+            // implements REQ-002, REQ-011
+            let transactionGoal;
+            if (relationshipGoals.length === 0) {
+                // Simple case: just entity
+                transactionGoal = `rdf_transaction((kb_assert_entity(${type}, ${props})))`;
+            }
+            else {
+                // Entity + relationships in one transaction
+                const goals = [
+                    `kb_assert_entity(${type}, ${props})`,
+                    ...relationshipGoals,
+                ].join(", ");
+                transactionGoal = `rdf_transaction((${goals}))`;
+            }
+            const txResult = await prolog.query(transactionGoal);
+            if (!txResult.success) {
+                throw new Error(`Failed to upsert entity ${id}: ${txResult.error || "Unknown error"} (goal: ${transactionGoal})`);
+            }
+            // Update counters
             if (isUpdate) {
-                // Update counter only. kb_assert_entity implements upsert semantics in Prolog.
                 updated++;
             }
             else {
                 created++;
             }
-            const assertGoal = `kb_assert_entity(${type}, ${props})`;
-            const assertResult = await prolog.query(assertGoal);
-            if (!assertResult.success) {
-                throw new Error(`Failed to assert entity ${id}: ${assertResult.error || "Unknown error"}`);
-            }
+            relationshipsCreated += relationships.length;
         }
-        // Process relationships
-        for (const rel of relationships) {
-            const relType = rel.type;
-            const from = rel.from;
-            const to = rel.to;
-            // Build metadata
-            const metadata = buildRelationshipMetadata(rel);
-            const relGoal = `kb_assert_relationship(${relType}, '${escapeAtom(from)}', '${escapeAtom(to)}', ${metadata})`;
-            const relResult = await prolog.query(relGoal);
-            if (!relResult.success) {
-                throw new Error(`Failed to assert relationship ${relType} from ${from} to ${to}: ${relResult.error || "Unknown error"}`);
-            }
-            relationshipsCreated++;
-        }
-        // Note: kb_save is intentionally NOT called here for performance.
-        // Callers that need durability across restarts should explicitly call kb_save.
-        // This allows batching multiple upserts before a single disk write.
-        prolog.invalidateCache();
-        // Save KB to disk to ensure durability across process restarts
-        await prolog.query("kb_save");
-        prolog.invalidateCache();
-        // multiple upserts and save once at the end for better performance.
+        // Save KB to disk after all entities/relationships are written to ensure
+        // durability across process restarts.
         prolog.invalidateCache();
+        const saveResult = await prolog.query("kb_save");
+        if (!saveResult.success) {
+            throw new Error(`Failed to save KB after upsert: ${saveResult.error || "Unknown error"}`);
+        }
         let contradictionPairsDetected;
         if (type === "req" && !args._skipContradictionCheck) {
             contradictionPairsDetected = await detectContradictionPairs(prolog, id);

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.1",
+  "version": "0.3.3",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,7 +9,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.2.6",
+    "kibi-cli": "^0.2.7",
     "kibi-core": "^0.1.10",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.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",