kibi-mcp 0.1.6 → 0.2.1

package/dist/server.js

@@ -15,7 +15,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/>.
 */
+import fs from "node:fs";
 import { createRequire } from "node:module";
+import path from "node:path";
 /*
  How to apply this header to source files (examples)
 
@@ -47,24 +49,67 @@ import process from "node:process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 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 { handleKbBranchEnsure, handleKbBranchGc, } from "./tools/branch.js";
 import { handleKbCheck } from "./tools/check.js";
-import { handleKbContext } from "./tools/context.js";
-import { handleKbCoverageReport, } from "./tools/coverage-report.js";
 import { handleKbDelete } from "./tools/delete.js";
-import { handleKbDerive } from "./tools/derive.js";
-import { handleKbImpact } from "./tools/impact.js";
-import { handleKbListEntityTypes, handleKbListRelationshipTypes, } from "./tools/list-types.js";
-import { handleKbQueryRelationships, } from "./tools/query-relationships.js";
 import { handleKbQuery } from "./tools/query.js";
-import { handleSuggestSharedFacts, } from "./tools/suggest-shared-facts.js";
-import { handleKbSymbolsRefresh, } from "./tools/symbols.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",
@@ -74,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";
@@ -93,9 +138,9 @@ const PROMPTS = [
             "",
             "- Encode requirements as linked facts: `req --constrains--> fact` plus `req --requires_property--> fact`.",
             "- Reuse canonical fact IDs across requirements; shared constrained facts make contradictions detectable.",
-            "- Use read tools first (`kb_query`, `kb_query_relationships`, `kbcontext`) to establish context.",
-            "- Use mutation tools (`kb_upsert`, `kb_delete`, branch tools) only after you can justify the change.",
-            "- Use inference tools (`kb_derive`, `kb_impact`, `kb_coverage_report`) for deterministic analysis.",
+            "- Use `kb_query` first to confirm current state before any mutation.",
+            "- Use `kb_upsert` and `kb_delete` only for intentional, traceable KB changes.",
+            "- Run `kb_check` after meaningful mutations to catch integrity issues early.",
             "- Prefer explicit IDs and enum values to avoid invalid parameters.",
             "- Assume every write can affect downstream traceability queries.",
         ].join("\n"),
@@ -108,15 +153,13 @@ const PROMPTS = [
             "",
             "Follow this sequence for reliable operation:",
             "",
-            "1. **Discover**: Call `kb_list_entity_types`/`kb_list_relationship_types` if you are unsure about allowed values.",
-            "2. **Inspect**: Call `kb_query` or `kbcontext` to confirm current state before any mutation.",
-            "3. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property`.",
-            "4. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first.",
-            "5. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
-            "6. **Verify integrity**: Call `kb_check` after mutations.",
-            "7. **Assess impact**: Call `kb_impact`, `kb_derive`, or `kb_coverage_report` as needed.",
+            "1. **Inspect**: Call `kb_query` to confirm current state before any mutation.",
+            "2. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property`.",
+            "3. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first.",
+            "4. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
+            "5. **Verify integrity**: Call `kb_check` after mutations.",
             "",
-            "If a tool returns empty results, do not assume failure. Re-check filters (type, id, tags, sourceFile, or relationship type).",
+            "If a tool returns empty results, do not assume failure. Re-check filters (type, id, tags, sourceFile, limit, or offset).",
         ].join("\n"),
     },
     {
@@ -129,10 +172,8 @@ const PROMPTS = [
             "",
             "- `kb_upsert` validates entity and relationship payloads against JSON Schema.",
             "- `kb_delete` blocks deletion when dependents still reference the entity.",
-            "- `kb_branch_gc` may permanently remove stale branch KB directories when `dry_run` is `false`.",
             "- Relationship and rule names are strict enums; unknown values fail validation.",
-            "- Branch names are sanitized; path traversal patterns are rejected.",
-            "- `kb_symbols_refresh` can rewrite the symbols manifest unless `dryRun` is enabled.",
+            "- Branch KB setup is automatic at server startup; lifecycle maintenance stays outside the public MCP tool surface.",
         ].join("\n"),
     },
 ];
@@ -144,9 +185,8 @@ function registerDocResources() {
         "",
         "Scope:",
         "- Entity CRUD-like operations for KB records",
-        "- Relationship inspection",
-        "- Validation and branch KB maintenance",
-        "- Deterministic inference for traceability and impact analysis",
+        "- Validation of KB integrity after changes",
+        "- Automatic branch-local attachment for the active workspace",
         "",
         "Use this server when you need branch-local, machine-readable project memory.",
     ].join("\n");
@@ -157,7 +197,7 @@ function registerDocResources() {
         "",
         "- `-32602 INVALID_PARAMS`: Tool arguments are missing/invalid. Recover by checking enum values and required fields.",
         "- `-32601 METHOD_NOT_FOUND`: Unknown MCP method. Recover by using supported methods (`tools/*`, `prompts/*`, `resources/*`).",
-        "- `-32000 PROLOG_QUERY_FAILED`: Prolog query failed. Recover by validating IDs, rule names, and relationship types.",
+        "- `-32000 PROLOG_QUERY_FAILED`: Prolog query failed. Recover by validating IDs, rule names, and branch KB availability.",
         "- `VALIDATION_ERROR` message: `kb_upsert` payload failed schema checks. Recover by fixing required fields and enum values.",
         "- Delete blocked by dependents: `kb_delete` detected incoming references. Recover by removing/rewiring relationships first.",
         "- Empty results: filters may be too strict. Recover by loosening type/id/tags/source filters and retrying.",
@@ -171,20 +211,10 @@ function registerDocResources() {
         "3. Reuse the same constrained fact ID across related requirements; vary property facts only when semantics differ",
         '4. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }`',
         "",
-        "## Discover requirement coverage gaps",
-        '1. `kb_query` with `{ "type": "req", "limit": 20 }`',
-        '2. `kb_coverage_report` with `{ "type": "req" }`',
-        '3. `kb_derive` with `{ "rule": "coverage_gap" }`',
-        "",
         "## Add a requirement and link it to a test",
         "1. `kb_query` for existing IDs to avoid collisions",
         "2. `kb_upsert` with entity payload and `relationships` containing `verified_by`",
         '3. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }`',
-        "",
-        "## Safe cleanup of stale branch KBs",
-        '1. `kb_branch_gc` with `{ "dry_run": true }`',
-        "2. Review `structuredContent.stale`",
-        '3. `kb_branch_gc` with `{ "dry_run": false }` only when deletion is intended',
     ].join("\n");
     return [
         {
@@ -261,10 +291,86 @@ 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}`);
+    }
+    const branchPath = resolveKbPath(workspaceRoot, branch);
+    if (fs.existsSync(branchPath)) {
+        return;
+    }
+    const templateBranch = ["develop", "main"].find((candidate) => candidate !== branch &&
+        fs.existsSync(resolveKbPath(workspaceRoot, candidate)));
+    if (!templateBranch) {
+        throw new Error(`No template branch KB found for '${branch}'. Expected '.kb/branches/develop' or '.kb/branches/main'.`);
+    }
+    // Use clean snapshot copy that excludes volatile artifacts
+    copyCleanSnapshot(resolveKbPath(workspaceRoot, templateBranch), branchPath);
+}
 function debugLog(...args) {
     if (process.env.KIBI_MCP_DEBUG) {
         console.error(...args);
@@ -315,10 +421,56 @@ 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();
+    let targetBranch;
+    if (envBranch) {
+        // KIBI_BRANCH override is set - use it without re-resolving from git
+        if (!isValidBranchName(envBranch)) {
+            throw new Error(`Invalid branch name from KIBI_BRANCH: '${envBranch}'`);
+        }
+        targetBranch = envBranch;
+    }
+    else {
+        // No override - resolve active branch from git (may change between requests)
+        const branchResult = resolveActiveBranch(workspaceRoot);
+        if ("error" in branchResult) {
+            const diagnostic = getBranchDiagnostic(undefined, branchResult.error);
+            console.error(`[KIBI-MCP] ${diagnostic}`);
+            throw new Error(`Failed to resolve active branch: ${branchResult.error}`);
+        }
+        targetBranch = branchResult.branch;
+    }
+    // Check if we need to switch branches
     if (isInitialized && prologProcess?.isRunning()) {
+        if (targetBranch === activeBranchName) {
+            // Still on the same branch - return existing connection
+            return prologProcess;
+        }
+        // Branch changed - need to detach and re-attach
+        debugLog(`[KIBI-MCP] Branch changed: ${activeBranchName} -> ${targetBranch}`);
+        // Detach from old KB
+        const detachResult = await prologProcess.query("kb_detach");
+        if (!detachResult.success) {
+            debugLog(`[KIBI-MCP] Warning: failed to detach from old KB: ${detachResult.error || "Unknown error"}`);
+            // Continue anyway - we'll try to attach to the new KB
+        }
+        // Ensure new branch KB exists
+        ensureBranchKbExists(workspaceRoot, targetBranch);
+        const newKbPath = resolveKbPath(workspaceRoot, targetBranch);
+        // Attach to new branch KB
+        const attachResult = await prologProcess.query(`kb_attach('${newKbPath}')`);
+        if (!attachResult.success) {
+            throw new Error(`Failed to attach to new branch KB: ${attachResult.error || "Unknown error"}`);
+        }
+        activeBranchName = targetBranch;
+        debugLog(`[KIBI-MCP] Re-attached to branch: ${targetBranch}`);
+        debugLog(`[KIBI-MCP] KB path: ${newKbPath}`);
         return prologProcess;
     }
+    // First initialization
     debugLog("[KIBI-MCP] Initializing Prolog process...");
     prologProcess = new PrologProcess({ timeout: 120000 });
     await prologProcess.start();
@@ -355,33 +507,12 @@ async function ensureProlog() {
             debugLog("[KIBI-MCP] Failed to create require() for debug lookup:", err.message);
         }
     }
-    const workspaceRoot = resolveWorkspaceRoot();
-    let branch = process.env.KIBI_BRANCH || "develop";
-    let gitBranch;
-    if (!process.env.KIBI_BRANCH) {
-        try {
-            const { execSync } = await import("node:child_process");
-            const detected = execSync("git branch --show-current", {
-                cwd: workspaceRoot,
-                encoding: "utf8",
-                timeout: 3000,
-            }).trim();
-            if (detected) {
-                gitBranch = detected === "master" ? "develop" : detected;
-                branch = gitBranch;
-            }
-        }
-        catch {
-            // fall back to develop
-        }
-    }
     debugLog("[KIBI-MCP] Branch selection:");
     debugLog(`[KIBI-MCP]   KIBI_BRANCH env: ${process.env.KIBI_BRANCH || "not set"}`);
-    debugLog(`[KIBI-MCP]   Git branch: ${gitBranch || "n/a"}`);
-    debugLog(`[KIBI-MCP]   Attached to: ${branch}`);
-    debugLog("[KIBI-MCP] To change branch: set KIBI_BRANCH=<branch> and restart");
-    activeBranchName = branch;
-    const kbPath = resolveKbPath(workspaceRoot, branch);
+    debugLog(`[KIBI-MCP]   Resolved branch: ${targetBranch}`);
+    activeBranchName = targetBranch;
+    ensureBranchKbExists(workspaceRoot, targetBranch);
+    const kbPath = resolveKbPath(workspaceRoot, targetBranch);
     const attachResult = await prologProcess.query(`kb_attach('${kbPath}')`);
     if (!attachResult.success) {
         throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
@@ -391,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();
@@ -493,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);
@@ -537,8 +739,12 @@ function addTool(server, name, description, inputSchema, handler) {
 }
 export async function startServer() {
     loadDefaultEnvFile();
-    const server = new McpServer({ name: "kibi-mcp", version: "0.1.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: [
@@ -561,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;
@@ -582,49 +788,6 @@ export async function startServer() {
         const prolog = await ensureProlog();
         return handleKbCheck(prolog, args);
     });
-    addTool(server, "kb_branch_ensure", toolDef("kb_branch_ensure").description, toolDef("kb_branch_ensure").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbBranchEnsure(prolog, args);
-    });
-    addTool(server, "kb_branch_gc", toolDef("kb_branch_gc").description, toolDef("kb_branch_gc").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbBranchGc(prolog, args);
-    });
-    addTool(server, "kb_query_relationships", toolDef("kb_query_relationships").description, toolDef("kb_query_relationships").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbQueryRelationships(prolog, args);
-    });
-    addTool(server, "kb_derive", toolDef("kb_derive").description, toolDef("kb_derive").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbDerive(prolog, args);
-    });
-    addTool(server, "kb_impact", toolDef("kb_impact").description, toolDef("kb_impact").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbImpact(prolog, args);
-    });
-    addTool(server, "kb_coverage_report", toolDef("kb_coverage_report").description, toolDef("kb_coverage_report").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbCoverageReport(prolog, args);
-    });
-    addTool(server, "kb_symbols_refresh", toolDef("kb_symbols_refresh").description, toolDef("kb_symbols_refresh").inputSchema, async (args) => handleKbSymbolsRefresh(args));
-    addTool(server, "kb_list_entity_types", toolDef("kb_list_entity_types").description, toolDef("kb_list_entity_types").inputSchema, handleKbListEntityTypes);
-    addTool(server, "kb_list_relationship_types", toolDef("kb_list_relationship_types").description, toolDef("kb_list_relationship_types").inputSchema, handleKbListRelationshipTypes);
-    addTool(server, "kbcontext", toolDef("kbcontext").description, toolDef("kbcontext").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbContext(prolog, args, activeBranchName);
-    });
-    addTool(server, "get_help", toolDef("get_help").description, toolDef("get_help").inputSchema, async (args) => {
-        const topic = typeof args?.topic === "string" ? args.topic : undefined;
-        const text = getHelpText(topic);
-        return {
-            content: [{ type: "text", text }],
-            structuredContent: { topic: topic ?? "overview" },
-        };
-    });
-    addTool(server, "analyze_shared_facts", toolDef("analyze_shared_facts").description, toolDef("analyze_shared_facts").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleSuggestSharedFacts(prolog, args);
-    });
     const transport = new StdioServerTransport();
     transport.onerror = (error) => {
         // Stdio transport surfaces JSON parse / schema validation failures via onerror.

package/dist/tools/check.js

@@ -44,6 +44,15 @@
 */
 import * as path from "node:path";
 import { parsePairList } from "./prolog-list.js";
+function formatDiagnosticsForMcp(diagnostics) {
+    return diagnostics.map((d) => ({
+        category: d.category,
+        severity: d.severity,
+        message: d.message,
+        file: d.file,
+        suggestion: d.suggestion,
+    }));
+}
 /**
  * Handle kb_check tool calls - run validation rules on the KB
  * Reuses validation logic from CLI check command
@@ -77,7 +86,13 @@ export async function handleKbCheck(prolog, args) {
         if (rulesToRun.includes("symbol-coverage")) {
             violations.push(...(await checkSymbolCoverage(prolog)));
         }
-        // Return MCP structured response
+        const diagnostics = violations.map((v) => ({
+            category: "SYNC_ERROR",
+            severity: "error",
+            message: v.description,
+            file: v.source,
+            suggestion: v.suggestion,
+        }));
         const summary = violations.length === 0
             ? "No violations found"
             : `${violations.length} violations found`;
@@ -91,6 +106,7 @@ export async function handleKbCheck(prolog, args) {
             structuredContent: {
                 violations,
                 count: violations.length,
+                diagnostics: formatDiagnosticsForMcp(diagnostics),
             },
         };
     }

package/dist/tools/context.js

@@ -15,18 +15,8 @@
  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 async function handleKbContext(prolog, args, activeBranch) {
-    const { sourceFile, branch } = args;
-    if (branch && activeBranch && branch !== activeBranch) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error: branch parameter is not supported server-side; set KIBI_BRANCH at startup or restart server on the desired branch. (Requested: ${branch}, Active: ${activeBranch})`,
-                },
-            ],
-        };
-    }
+export async function handleKbContext(prolog, args) {
+    const { sourceFile } = args;
     try {
         const safeSource = sourceFile.replace(/'/g, "\\'");
         const entityGoal = `findall([Id,Type,Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, Type, Props)), Results)`;

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/dist/tools-config.js

@@ -234,215 +234,19 @@ export const TOOLS = [
             properties: {
                 rules: {
                     type: "array",
-                    items: { type: "string" },
+                    items: {
+                        type: "string",
+                        enum: [
+                            "must-priority-coverage",
+                            "no-dangling-refs",
+                            "no-cycles",
+                            "required-fields",
+                            "symbol-coverage",
+                        ],
+                    },
                     description: "Optional rule subset. Allowed: must-priority-coverage, no-dangling-refs, no-cycles, required-fields, symbol-coverage. If omitted, server runs all.",
                 },
             },
         },
     },
-    {
-        name: "kb_branch_ensure",
-        description: "Ensure a branch KB exists, creating it from develop when missing. Use when targeting non-develop branches. Do not use to switch git branches. Side effects: creates .kb/branches/<branch>.",
-        inputSchema: {
-            type: "object",
-            required: ["branch"],
-            properties: {
-                branch: {
-                    type: "string",
-                    description: "Required git branch name. Example: 'feature/auth-hardening'. Path traversal patterns are rejected.",
-                },
-            },
-        },
-    },
-    {
-        name: "kb_branch_gc",
-        description: "Find or delete stale branch KB directories not present in git. Use for repository hygiene. Do not use if you need historical branch KBs. Side effects: can delete branch KB folders when dry_run is false.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                dry_run: {
-                    type: "boolean",
-                    default: true,
-                    description: "Optional safety flag. true = report only; false = delete stale branch KBs. Default: true.",
-                },
-            },
-        },
-    },
-    {
-        name: "kb_query_relationships",
-        description: "Read relationship edges with optional from/to/type filters. Use for traceability traversal. Do not use to create links. No mutation side effects.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                from: {
-                    type: "string",
-                    description: "Optional source entity ID filter. Example: 'REQ-001'.",
-                },
-                to: {
-                    type: "string",
-                    description: "Optional target entity ID filter. Example: 'TEST-010'.",
-                },
-                type: {
-                    type: "string",
-                    enum: [
-                        "depends_on",
-                        "specified_by",
-                        "verified_by",
-                        "validates",
-                        "implements",
-                        "covered_by",
-                        "constrained_by",
-                        "constrains",
-                        "requires_property",
-                        "guards",
-                        "publishes",
-                        "consumes",
-                        "supersedes",
-                        "relates_to",
-                    ],
-                    description: "Optional relationship type filter. Allowed enum values only. Example: 'implements'.",
-                },
-            },
-        },
-    },
-    {
-        name: "kb_derive",
-        description: "Run deterministic inference predicates and return rows. Use for impact, coverage, and consistency analysis. Do not use for entity CRUD. No mutation side effects.",
-        inputSchema: {
-            type: "object",
-            required: ["rule"],
-            properties: {
-                rule: {
-                    type: "string",
-                    enum: [
-                        "transitively_implements",
-                        "transitively_depends",
-                        "impacted_by_change",
-                        "affected_symbols",
-                        "coverage_gap",
-                        "untested_symbols",
-                        "stale",
-                        "orphaned",
-                        "conflicting",
-                        "deprecated_still_used",
-                        "current_adr",
-                        "adr_chain",
-                        "superseded_by",
-                        "domain_contradictions",
-                    ],
-                    description: "Required inference rule name. Allowed values are the enum options. Example: 'coverage_gap'.",
-                },
-                params: {
-                    type: "object",
-                    description: "Optional rule-specific parameters. Example: { changed: 'REQ-001' } for impacted_by_change.",
-                },
-            },
-        },
-    },
-    {
-        name: "kb_impact",
-        description: "Return entities impacted by a changed entity ID. Use for quick change blast radius checks. Do not use for general querying. No mutation side effects.",
-        inputSchema: {
-            type: "object",
-            required: ["entity"],
-            properties: {
-                entity: {
-                    type: "string",
-                    description: "Required changed entity ID. Example: 'REQ-001'.",
-                },
-            },
-        },
-    },
-    {
-        name: "kb_coverage_report",
-        description: "Compute aggregate traceability coverage for requirements and/or symbols. Use for health snapshots. Do not use for raw entity dumps. No mutation side effects.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                type: {
-                    type: "string",
-                    enum: ["req", "symbol"],
-                    description: "Optional focus scope: 'req' or 'symbol'. Omit to include both.",
-                },
-            },
-        },
-    },
-    {
-        name: "kb_symbols_refresh",
-        description: "Refresh generated symbol coordinates in the symbols manifest. Use after refactors that move symbols. Do not use for semantic edits. Side effects: may rewrite symbols.yaml unless dryRun is true.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                dryRun: {
-                    type: "boolean",
-                    default: false,
-                    description: "Optional preview mode. true = report only, false = apply file updates. Default: false.",
-                },
-            },
-        },
-    },
-    {
-        name: "kb_list_entity_types",
-        description: "List supported entity type names. Use when building valid tool arguments. Do not use for entity data retrieval. No mutation side effects.",
-        inputSchema: { type: "object", properties: {} },
-    },
-    {
-        name: "kb_list_relationship_types",
-        description: "List supported relationship type names. Use before asserting or filtering relationships. Do not use for graph traversal. No mutation side effects.",
-        inputSchema: { type: "object", properties: {} },
-    },
-    {
-        name: "kbcontext",
-        description: "Return KB entities linked to a source file plus first-hop relationships. Use for file-centric traceability. Do not use for cross-repo search. No mutation side effects.",
-        inputSchema: {
-            type: "object",
-            required: ["sourceFile"],
-            properties: {
-                sourceFile: {
-                    type: "string",
-                    description: "Required source path substring. Example: 'src/auth/login.ts'.",
-                },
-                branch: {
-                    type: "string",
-                    description: "Optional branch hint for clients. Must match the server's active branch or will return an error.",
-                },
-            },
-        },
-    },
-    {
-        name: "get_help",
-        description: "Returns documentation for this MCP server. Call this first if you are unsure how to proceed or which tool to use. Available topics: overview, tools, workflow, constraints, examples, errors.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                topic: {
-                    type: "string",
-                    enum: [
-                        "overview",
-                        "tools",
-                        "workflow",
-                        "constraints",
-                        "examples",
-                        "errors",
-                        "branching",
-                    ],
-                    description: "Optional documentation section. Omit to return overview. Example: 'workflow'.",
-                },
-            },
-        },
-    },
-    {
-        name: "analyze_shared_facts",
-        description: "Analyze requirements and suggest shared domain facts for extraction. LLMs call this to identify missed semantic opportunities before upserting. Lightweight heuristic: finds overlapping capitalized terms and repeated phrases across requirements.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                min_frequency: {
-                    type: "number",
-                    default: 2,
-                    description: "Minimum frequency threshold for shared concepts. Default: 2. Example: 3 to only show concepts mentioned in 3+ requirements.",
-                },
-            },
-        },
-    },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "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.1.7",
-    "kibi-core": "^0.1.6",
+    "kibi-cli": "^0.2.2",
+    "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;
-    }
-}