kibi-mcp 0.3.2 → 0.4.0

package/dist/diagnostics.js

@@ -0,0 +1,124 @@
+/*
+ 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.",
+        },
+    },
+};
+// implements REQ-002
+export function deriveDiagnosticFields(toolName, args, telemetry, result) {
+    const fields = {
+        telemetry_status: telemetry ? "provided" : "missing",
+    };
+    const structuredContent = result && typeof result === "object" && "structuredContent" in result
+        ? result.structuredContent
+        : undefined;
+    if (toolName === "kb_query" || toolName === "kb_search") {
+        const resultCount = Number(structuredContent?.count ?? 0);
+        fields.result_count = resultCount;
+        fields.zero_results = resultCount === 0;
+        fields.result_summary =
+            resultCount === 0 ? "0 results" : `${resultCount} results`;
+    }
+    if (toolName === "kb_check") {
+        const violationCount = Number(structuredContent?.count ?? 0);
+        fields.violation_count = violationCount;
+        fields.requested_rules = Array.isArray(args.rules) ? args.rules : [];
+        fields.result_summary =
+            violationCount === 0
+                ? "0 violations"
+                : `${violationCount} violations`;
+    }
+    if (!fields.result_summary) {
+        fields.result_summary = `${toolName} completed`;
+    }
+    return fields;
+}
+/**
+ * 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/docs.js

@@ -104,8 +104,13 @@ export const PROMPTS = [
             "",
             "Treat this server as a branch-aware knowledge graph interface for software traceability.",
             "",
-            "The server exposes 4 public tools for KB operations:",
-            "- `kb_query`: Read-only lookup of entities by type, ID, tags, or source file",
+            "The server exposes a curated public tool surface for KB operations:",
+            "- `kb_search`: Discovery across metadata and markdown body text",
+            "- `kb_query`: Exact lookup of entities by type, ID, tags, or source file",
+            "- `kb_status`: Branch, snapshot, and freshness inspection",
+            "- `kb_find_gaps`: Bulk missing/present relationship analysis",
+            "- `kb_coverage`: Curated coverage reporting",
+            "- `kb_graph`: Bounded graph traversal from seed IDs",
             "- `kb_upsert`: Create or update entities and their relationships",
             "- `kb_delete`: Remove entities by ID (with dependency safety checks)",
             "- `kb_check`: Validate KB integrity against configurable rules",
@@ -113,7 +118,7 @@ export const PROMPTS = [
             "Core modeling principles:",
             "- 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 `kb_query` first to confirm current state before any mutation.",
+            "- Use `kb_search` first for discovery, then `kb_query` for exact follow-up 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.",
@@ -128,7 +133,7 @@ export const PROMPTS = [
             "",
             "Follow this sequence for reliable operation:",
             "",
-            "1. **Query-first**: Always call `kb_query` to confirm current state before any mutation.",
+            "1. **Discover first**: Call `kb_search` for exploratory discovery, then `kb_query` to confirm exact current state before mutation.",
             "2. **Create-before-link**: Create endpoint entities with `kb_upsert` before linking them.",
             "3. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
             "4. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property`.",
@@ -167,8 +172,8 @@ function registerDocResources() {
         "kibi-mcp is a stdio MCP server for querying and mutating the Kibi knowledge base.",
         "",
         "Scope:",
-        "- Entity CRUD-like operations for KB records",
-        "- Validation of KB integrity after changes",
+        "- Read-only discovery and reporting (`kb_search`, `kb_query`, `kb_status`, `kb_find_gaps`, `kb_coverage`, `kb_graph`)",
+        "- KB mutation and validation (`kb_upsert`, `kb_delete`, `kb_check`)",
         "- Automatic branch-local attachment for the active workspace",
         "",
         "Use this server when you need branch-local, machine-readable project memory.",
@@ -188,6 +193,11 @@ function registerDocResources() {
     const examples = [
         "# kibi-mcp Examples",
         "",
+        "## Discover before mutating",
+        '1. `kb_search` with `{ "query": "login flow" }` to discover related requirements, tests, and ADRs',
+        '2. `kb_query` with `{ "type": "req", "sourceFile": "src/auth/login.ts" }` for exact follow-up',
+        '3. `kb_status` with `{}` when branch attachment or freshness confidence matters',
+        "",
         "## Model requirements as reusable facts",
         '1. `kb_query` with `{ "type": "fact" }` to find existing fact IDs before creating new ones',
         "2. `kb_upsert` for the fact entity first (create-before-link)",
@@ -195,6 +205,11 @@ function registerDocResources() {
         "4. Reuse the same constrained fact ID across related requirements; vary property facts only when semantics differ",
         '5. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }` for targeted validation',
         "",
+        "## Find missing coverage",
+        '1. `kb_find_gaps` with `{ "type": "req", "missingRelationships": ["specified_by", "verified_by"] }` to find under-linked requirements',
+        '2. `kb_coverage` with `{ "by": "req", "includePassing": false }` to review evaluated coverage rows',
+        '3. `kb_graph` with `{ "seedIds": ["REQ-001"], "direction": "both", "depth": 2 }` to inspect neighboring entities',
+        "",
         "## Add a requirement and link it to a test",
         '1. `kb_query` with `{ "type": "test" }` to check for existing test IDs',
         '2. `kb_query` with `{ "id": "REQ-XXX" }` to verify the requirement exists',

package/dist/server/tools.js

@@ -17,12 +17,18 @@
  */
 import process from "node:process";
 import { z } from "zod";
+import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, deriveDiagnosticFields, extractToolCallPayload, } from "../diagnostics.js";
+import { handleKbCoverage } from "../tools/coverage.js";
 import { TOOLS } from "../tools-config.js";
 import { handleKbCheck } from "../tools/check.js";
 import { handleKbDelete } from "../tools/delete.js";
+import { handleKbFindGaps } from "../tools/find-gaps.js";
+import { handleKbGraph } from "../tools/graph.js";
 import { handleKbQuery } from "../tools/query.js";
+import { handleKbSearch } from "../tools/search.js";
+import { handleKbStatus } from "../tools/status.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 +137,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 +165,49 @@ 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();
+                    const diagnosticFields = deriveDiagnosticFields(name, businessArgs, telemetry, result);
+                    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,
+                        ...diagnosticFields,
+                    });
+                }
+                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)
@@ -173,6 +225,7 @@ function addTool(server, name, description, inputSchema, handler) {
     };
     server.registerTool(name, { description, inputSchema: jsonSchemaToZod(inputSchema) }, wrappedHandler);
 }
+// implements REQ-002, REQ-013
 export function registerAllTools(server) {
     const toolDef = (name) => {
         const t = ACTIVE_TOOLS.find((t) => t.name === name);
@@ -184,6 +237,26 @@ export function registerAllTools(server) {
         const prolog = await ensureProlog();
         return handleKbQuery(prolog, args);
     });
+    addTool(server, "kb_search", toolDef("kb_search").description, toolDef("kb_search").inputSchema, async (args) => {
+        const prolog = await ensureProlog();
+        return handleKbSearch(prolog, args);
+    });
+    addTool(server, "kb_status", toolDef("kb_status").description, toolDef("kb_status").inputSchema, async (args) => {
+        const prolog = await ensureProlog();
+        return handleKbStatus(prolog, args);
+    });
+    addTool(server, "kb_find_gaps", toolDef("kb_find_gaps").description, toolDef("kb_find_gaps").inputSchema, async (args) => {
+        const prolog = await ensureProlog();
+        return handleKbFindGaps(prolog, args);
+    });
+    addTool(server, "kb_coverage", toolDef("kb_coverage").description, toolDef("kb_coverage").inputSchema, async (args) => {
+        const prolog = await ensureProlog();
+        return handleKbCoverage(prolog, args);
+    });
+    addTool(server, "kb_graph", toolDef("kb_graph").description, toolDef("kb_graph").inputSchema, async (args) => {
+        const prolog = await ensureProlog();
+        return handleKbGraph(prolog, args);
+    });
     addTool(server, "kb_upsert", toolDef("kb_upsert").description, toolDef("kb_upsert").inputSchema, async (args) => {
         const prolog = await ensureProlog();
         return handleKbUpsert(prolog, args);

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

@@ -64,6 +64,24 @@ function formatDiagnosticsForMcp(diagnostics) {
         suggestion: d.suggestion,
     }));
 }
+function formatViolationText(violations) {
+    if (violations.length === 0) {
+        return "No violations found";
+    }
+    const details = violations.map((violation) => {
+        const parts = [
+            violation.rule,
+            violation.entityId,
+            violation.source ?? "unknown-source",
+            violation.description,
+        ];
+        if (violation.suggestion) {
+            parts.push(`Suggestion: ${violation.suggestion}`);
+        }
+        return `- ${parts.join(" | ")}`;
+    });
+    return `${violations.length} violations found\n${details.join("\n")}`;
+}
 // implements REQ-002
 function loadChecksConfig(workspaceRoot) {
     const configPath = path.join(workspaceRoot, ".kb", "config.json");
@@ -151,9 +169,7 @@ export async function handleKbCheck(prolog, args) {
             file: v.source,
             suggestion: v.suggestion,
         }));
-        const summary = aggregatedViolations.length === 0
-            ? "No violations found"
-            : `${aggregatedViolations.length} violations found`;
+        const summary = formatViolationText(aggregatedViolations);
         return {
             content: [
                 {

package/dist/tools/core-module.js

@@ -0,0 +1,83 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { PrologProcess } from "kibi-cli/prolog";
+import { escapeAtomContent } from "kibi-cli/prolog/codec";
+const require = createRequire(import.meta.url);
+// implements REQ-002, REQ-013
+export function resolveCorePlPath(fileName) {
+    const envKey = `KIBI_${fileName.replace(/\W/g, "_").toUpperCase()}_PATH`;
+    const override = process.env[envKey];
+    if (override && existsSync(override)) {
+        return override;
+    }
+    try {
+        const installedPath = require.resolve(`kibi-core/src/${fileName}`);
+        if (existsSync(installedPath)) {
+            return installedPath;
+        }
+    }
+    catch { }
+    const localPath = path.join(process.cwd(), "packages/core/src", fileName);
+    if (existsSync(localPath)) {
+        return localPath;
+    }
+    throw new Error(`Unable to resolve core module path for ${fileName}`);
+}
+// implements REQ-002, REQ-013
+export async function runJsonModuleQuery(prolog, fileName, goal, errorLabel) {
+    const modulePath = escapeAtomContent(resolveCorePlPath(fileName).replace(/\\/g, "/"));
+    if (!(prolog instanceof PrologProcess)) {
+        const mockedResult = await prolog.query(`(use_module('${modulePath}'), ${goal})`);
+        if (!mockedResult.success) {
+            throw new Error(`${errorLabel} query failed: ${mockedResult.error || "Unknown error"}`);
+        }
+        const mockedJson = mockedResult.bindings.JsonString;
+        if (!mockedJson) {
+            throw new Error(`${errorLabel} query returned no JsonString binding`);
+        }
+        let mockedParsed = JSON.parse(mockedJson);
+        if (typeof mockedParsed === "string") {
+            mockedParsed = JSON.parse(mockedParsed);
+        }
+        return mockedParsed;
+    }
+    const oneShotCapable = prolog;
+    prolog.invalidateCache();
+    const result = oneShotCapable.useOneShotMode
+        ? await prolog.query(`(use_module('${modulePath}'), ${goal})`)
+        : await runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel);
+    if (!result.success) {
+        throw new Error(`${errorLabel} query failed: ${result.error || "Unknown error"}`);
+    }
+    const rawJson = result.bindings.JsonString;
+    if (!rawJson) {
+        throw new Error(`${errorLabel} query returned no JsonString binding`);
+    }
+    let parsed = JSON.parse(rawJson);
+    if (typeof parsed === "string") {
+        parsed = JSON.parse(parsed);
+    }
+    return parsed;
+}
+async function runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel) {
+    const loadResult = await prolog.query(`use_module('${modulePath}')`);
+    if (!loadResult.success) {
+        throw new Error(`${errorLabel} module load failed: ${loadResult.error || "Unknown error"}`);
+    }
+    return prolog.query(goal);
+}
+// implements REQ-002, REQ-013
+export function toPrologAtom(value) {
+    if (!value) {
+        return "none";
+    }
+    return `'${escapeAtomContent(value)}'`;
+}
+// implements REQ-002, REQ-013
+export function toPrologList(values) {
+    if (!values || values.length === 0) {
+        return "[]";
+    }
+    return `[${values.map((value) => `'${escapeAtomContent(value)}'`).join(",")}]`;
+}

package/dist/tools/coverage.js

@@ -0,0 +1,28 @@
+import { runJsonModuleQuery, toPrologList } from "./core-module.js";
+// implements REQ-002, REQ-013
+export async function handleKbCoverage(prolog, args) {
+    const by = args.by ?? "req";
+    const limit = args.limit ?? 100;
+    const offset = args.offset ?? 0;
+    const includePassing = args.includePassing ?? false;
+    const includeTransitive = args.includeTransitive ?? true;
+    try {
+        const payload = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:coverage_report_json('${by}', ${toPrologList(args.tags)}, ${includePassing}, ${includeTransitive}, ${limit}, ${offset}, JsonString)`, "Coverage execution");
+        const summary = payload?.summary ?? {};
+        const fullyCovered = Number(summary.fullyCovered ?? 0);
+        const total = Number(summary.total ?? 0);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Coverage summary: ${fullyCovered} fully covered out of ${total}.`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Coverage execution failed: ${message}`);
+    }
+}

package/dist/tools/entity-query.js

@@ -0,0 +1,110 @@
+import { escapeAtomContent, parseEntityFromBinding, parseEntityFromList, parseListOfLists, } from "kibi-cli/prolog/codec";
+export const VALID_ENTITY_TYPES = [
+    "req",
+    "scenario",
+    "test",
+    "adr",
+    "flag",
+    "event",
+    "symbol",
+    "fact",
+];
+// implements REQ-002, REQ-013
+export function validateEntityType(type) {
+    if (type && !VALID_ENTITY_TYPES.includes(type)) {
+        throw new Error(`Invalid type '${type}'. Valid types: ${VALID_ENTITY_TYPES.join(", ")}. Use a single type value, or omit this parameter to query all entities.`);
+    }
+}
+// implements REQ-002, REQ-013
+export function buildEntityGoal(args) {
+    const { type, id, tags, sourceFile } = args;
+    if (sourceFile) {
+        const safeSource = escapeAtomContent(sourceFile);
+        if (type) {
+            const safeType = escapeAtomContent(type);
+            return `findall([Id,'${safeType}',Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, '${safeType}', Props)), Results)`;
+        }
+        return `findall([Id,Type,Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, Type, Props)), Results)`;
+    }
+    if (id && type) {
+        const safeId = escapeAtomContent(id);
+        const safeType = escapeAtomContent(type);
+        return `findall(['${safeId}','${safeType}',Props], kb_entity('${safeId}', '${safeType}', Props), Results)`;
+    }
+    if (id) {
+        const safeId = escapeAtomContent(id);
+        return `findall(['${safeId}',Type,Props], kb_entity('${safeId}', Type, Props), Results)`;
+    }
+    if (tags && tags.length > 0) {
+        if (type) {
+            const safeType = escapeAtomContent(type);
+            return `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
+        }
+        return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
+    }
+    if (type) {
+        const safeType = escapeAtomContent(type);
+        return `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
+    }
+    return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
+}
+// implements REQ-002, REQ-013
+export async function loadEntities(prolog, args) {
+    validateEntityType(args.type);
+    const goal = buildEntityGoal(args);
+    const queryResult = await prolog.query(goal);
+    let results = [];
+    if (!queryResult.success) {
+        throw new Error(queryResult.error || "Query failed with unknown error");
+    }
+    if (queryResult.bindings.Results) {
+        const entitiesData = parseListOfLists(queryResult.bindings.Results);
+        for (const data of entitiesData) {
+            results.push(parseEntityFromList(data));
+        }
+    }
+    else if (queryResult.bindings.Result) {
+        results = [parseEntityFromBinding(queryResult.bindings.Result)];
+    }
+    if (args.tags && args.tags.length > 0) {
+        const requestedTags = args.tags;
+        results = dedupeEntities(results.filter((entity) => hasAnyTag(entity, requestedTags)));
+    }
+    return dedupeEntities(results);
+}
+// implements REQ-002
+export function paginateResults(results, limit = 100, offset = 0) {
+    return results.slice(offset, offset + limit);
+}
+function hasAnyTag(entity, requestedTags) {
+    const expected = new Set(requestedTags.map(normalizeTagValue));
+    const rawTags = entity.tags;
+    if (!Array.isArray(rawTags) || rawTags.length === 0) {
+        return false;
+    }
+    for (const tag of rawTags) {
+        if (expected.has(normalizeTagValue(tag))) {
+            return true;
+        }
+    }
+    return false;
+}
+function normalizeTagValue(tag) {
+    return String(tag).trim();
+}
+// implements REQ-002
+export function dedupeEntities(entities) {
+    const seen = new Set();
+    const deduped = [];
+    for (const entity of entities) {
+        const id = String(entity.id ?? "");
+        const type = String(entity.type ?? "");
+        const key = `${type}::${id}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(entity);
+    }
+    return deduped;
+}

package/dist/tools/find-gaps.js

@@ -0,0 +1,29 @@
+import { runJsonModuleQuery, toPrologAtom, toPrologList } from "./core-module.js";
+import { validateEntityType } from "./entity-query.js";
+// implements REQ-002, REQ-013
+export async function handleKbFindGaps(prolog, args) {
+    validateEntityType(args.type);
+    const limit = args.limit ?? 100;
+    const offset = args.offset ?? 0;
+    try {
+        const payload = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:find_gaps_json(${toPrologAtom(args.type)}, ${toPrologList(args.missingRelationships)}, ${toPrologList(args.presentRelationships)}, ${toPrologList(args.tags)}, ${toPrologAtom(args.sourceFile)}, ${limit}, ${offset}, JsonString)`, "Find-gaps execution");
+        const rows = payload?.rows ?? [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: rows.length === 0
+                        ? "No matching gaps found."
+                        : `Found ${payload?.count ?? rows.length} gap rows. Showing ${rows.length}: ${rows
+                            .map((row) => row.id)
+                            .join(", ")}`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Find-gaps execution failed: ${message}`);
+    }
+}

package/dist/tools/graph.js

@@ -0,0 +1,27 @@
+import { runJsonModuleQuery, toPrologList } from "./core-module.js";
+// implements REQ-002, REQ-013
+export async function handleKbGraph(prolog, args) {
+    const direction = args.direction ?? "outgoing";
+    const depth = args.depth ?? 1;
+    const maxNodes = args.maxNodes ?? 200;
+    const maxEdges = args.maxEdges ?? 500;
+    try {
+        const payload = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:graph_expand_json(${toPrologList(args.seedIds)}, ${toPrologList(args.relationships)}, '${direction}', ${depth}, ${toPrologList(args.entityTypes)}, ${maxNodes}, ${maxEdges}, JsonString)`, "Graph execution");
+        const nodes = payload?.nodes ?? [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: nodes.length === 0
+                        ? "Graph traversal returned no nodes."
+                        : `Graph traversal returned ${nodes.length} nodes and ${(payload?.edges ?? []).length} edges from ${args.seedIds.join(", ")}.`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Graph execution failed: ${message}`);
+    }
+}

package/dist/tools/query.js

@@ -1,14 +1,5 @@
-import { escapeAtomContent, parseEntityFromBinding, parseEntityFromList, parseListOfLists, } from "kibi-cli/prolog/codec";
-export const VALID_ENTITY_TYPES = [
-    "req",
-    "scenario",
-    "test",
-    "adr",
-    "flag",
-    "event",
-    "symbol",
-    "fact",
-];
+import { loadEntities, paginateResults, } from "./entity-query.js";
+export { VALID_ENTITY_TYPES } from "./entity-query.js";
 /**
  * Handle kb.query tool calls
  * Reuses query logic from CLI command
@@ -16,75 +7,8 @@ export const VALID_ENTITY_TYPES = [
 export async function handleKbQuery(prolog, args) {
     const { type, id, tags, sourceFile, limit = 100, offset = 0 } = args;
     try {
-        let results = [];
-        // Validate type if provided
-        if (type) {
-            if (!VALID_ENTITY_TYPES.includes(type)) {
-                throw new Error(`Invalid type '${type}'. Valid types: ${VALID_ENTITY_TYPES.join(", ")}. Use a single type value, or omit this parameter to query all entities.`);
-            }
-        }
-        // Build Prolog query
-        let goal;
-        if (sourceFile) {
-            const safeSource = escapeAtomContent(sourceFile);
-            if (type) {
-                const safeType = escapeAtomContent(type);
-                goal = `findall([Id,'${safeType}',Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, '${safeType}', Props)), Results)`;
-            }
-            else {
-                goal = `findall([Id,Type,Props], (kb_entities_by_source('${safeSource}', SourceIds), member(Id, SourceIds), kb_entity(Id, Type, Props)), Results)`;
-            }
-        }
-        else if (id && type) {
-            const safeId = escapeAtomContent(id);
-            const safeType = escapeAtomContent(type);
-            goal = `findall(['${safeId}','${safeType}',Props], kb_entity('${safeId}', '${safeType}', Props), Results)`;
-        }
-        else if (id) {
-            const safeId = escapeAtomContent(id);
-            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.
-            if (type) {
-                const safeType = escapeAtomContent(type);
-                goal = `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
-            }
-            else {
-                goal = "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
-            }
-        }
-        else if (type) {
-            const safeType = escapeAtomContent(type);
-            goal = `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
-        }
-        else {
-            goal = "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
-        }
-        const queryResult = await prolog.query(goal);
-        if (queryResult.success) {
-            if (queryResult.bindings.Results) {
-                const entitiesData = parseListOfLists(queryResult.bindings.Results);
-                for (const data of entitiesData) {
-                    const entity = parseEntityFromList(data);
-                    results.push(entity);
-                }
-            }
-            else if (queryResult.bindings.Result) {
-                const entity = parseEntityFromBinding(queryResult.bindings.Result);
-                results = [entity];
-            }
-        }
-        else {
-            throw new Error(queryResult.error || "Query failed with unknown error");
-        }
-        if (tags && tags.length > 0) {
-            results = dedupeEntities(results.filter((entity) => hasAnyTag(entity, tags)));
-        }
-        // Apply pagination
-        const paginated = results.slice(offset, offset + limit);
+        const results = await loadEntities(prolog, { type, id, tags, sourceFile });
+        const paginated = paginateResults(results, limit, offset);
         // Build human-readable text with entity IDs and titles
         let text;
         if (results.length === 0) {
@@ -120,34 +44,3 @@ export async function handleKbQuery(prolog, args) {
         throw new Error(`Query execution failed: ${message}`);
     }
 }
-function hasAnyTag(entity, requestedTags) {
-    const expected = new Set(requestedTags.map(normalizeTagValue));
-    const rawTags = entity.tags;
-    if (!Array.isArray(rawTags) || rawTags.length === 0) {
-        return false;
-    }
-    for (const tag of rawTags) {
-        if (expected.has(normalizeTagValue(tag))) {
-            return true;
-        }
-    }
-    return false;
-}
-function normalizeTagValue(tag) {
-    return String(tag).trim();
-}
-function dedupeEntities(entities) {
-    const seen = new Set();
-    const deduped = [];
-    for (const entity of entities) {
-        const id = String(entity.id ?? "");
-        const type = String(entity.type ?? "");
-        const key = `${type}::${id}`;
-        if (seen.has(key)) {
-            continue;
-        }
-        seen.add(key);
-        deduped.push(entity);
-    }
-    return deduped;
-}

package/dist/tools/search.js

@@ -0,0 +1,37 @@
+import { rankEntities } from "kibi-cli/search-ranking";
+import { loadEntities, paginateResults, validateEntityType, } from "./entity-query.js";
+import { resolveWorkspaceRoot } from "../workspace.js";
+// implements REQ-mcp-search-discovery, REQ-002
+export async function handleKbSearch(prolog, args) {
+    const { query, type, limit = 20, offset = 0 } = args;
+    const trimmedQuery = query.trim();
+    if (!trimmedQuery) {
+        throw new Error("Search execution failed: query must be a non-empty string");
+    }
+    validateEntityType(type);
+    try {
+        const workspaceRoot = resolveWorkspaceRoot();
+        const entities = await loadEntities(prolog, { type });
+        const matches = await rankEntities(entities, trimmedQuery, workspaceRoot);
+        const paginated = paginateResults(matches, limit, offset);
+        const text = matches.length === 0
+            ? `No search results for '${trimmedQuery}'.`
+            : `Found ${matches.length} search results for '${trimmedQuery}'. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
+                .map((match) => `${match.entity.id} [${match.reasons.join(", ")}]`)
+                .join(", ")}`;
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: {
+                results: paginated,
+                count: matches.length,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith("Search execution failed:")) {
+            throw error;
+        }
+        throw new Error(`Search execution failed: ${message}`);
+    }
+}

package/dist/tools/status.js

@@ -0,0 +1,20 @@
+import { runJsonModuleQuery } from "./core-module.js";
+// implements REQ-002, REQ-013
+export async function handleKbStatus(prolog, _args) {
+    try {
+        const payload = await runJsonModuleQuery(prolog, "status.pl", "status:kb_status_json(JsonString)", "Status execution");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Branch ${payload.branch} is ${payload.syncState} (snapshot ${payload.snapshotId}, dirty=${payload.dirty})`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Status execution failed: ${message}`);
+    }
+}

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",
@@ -63,6 +64,172 @@ export const TOOLS = [
             },
         },
     },
+    {
+        name: "kb_search",
+        description: "Search KB entities for discovery using metadata and markdown body text. Use for exploratory lookup before exact follow-up with kb_query. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            required: ["query"],
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Free-text query for metadata and markdown body discovery. Example: 'OAuth login flow'.",
+                },
+                type: {
+                    type: "string",
+                    enum: [
+                        "req",
+                        "scenario",
+                        "test",
+                        "adr",
+                        "flag",
+                        "event",
+                        "symbol",
+                        "fact",
+                    ],
+                    description: "Optional entity type filter to narrow discovery. Example: 'req'.",
+                },
+                limit: {
+                    type: "integer",
+                    default: 20,
+                    description: "Optional max rows to return after ranking. Default: 20.",
+                },
+                offset: {
+                    type: "integer",
+                    default: 0,
+                    description: "Optional zero-based pagination offset. Default: 0.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_status",
+        description: "Report current branch, snapshot, and freshness metadata for the attached KB. Read-only status inspection with no mutation side effects.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "kb_find_gaps",
+        description: "Run bulk missing/present relationship analysis over KB entities. Use for questions like which requirements lack scenarios or tests. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                type: {
+                    type: "string",
+                    enum: [
+                        "req",
+                        "scenario",
+                        "test",
+                        "adr",
+                        "flag",
+                        "event",
+                        "symbol",
+                        "fact",
+                    ],
+                },
+                missingRelationships: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                presentRelationships: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                sourceFile: {
+                    type: "string",
+                },
+                limit: {
+                    type: "integer",
+                    default: 100,
+                },
+                offset: {
+                    type: "integer",
+                    default: 0,
+                },
+            },
+        },
+    },
+    {
+        name: "kb_coverage",
+        description: "Generate curated coverage reports for requirements, symbols, or grouped types. Read-only reporting with no mutation side effects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                by: {
+                    type: "string",
+                    enum: ["req", "symbol", "type"],
+                    default: "req",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                includePassing: {
+                    type: "boolean",
+                    default: false,
+                },
+                includeTransitive: {
+                    type: "boolean",
+                    default: true,
+                },
+                limit: {
+                    type: "integer",
+                    default: 100,
+                },
+                offset: {
+                    type: "integer",
+                    default: 0,
+                },
+            },
+        },
+    },
+    {
+        name: "kb_graph",
+        description: "Run bounded graph traversal from one or more seed IDs across curated relationship types. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            required: ["seedIds"],
+            properties: {
+                seedIds: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                relationships: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                direction: {
+                    type: "string",
+                    enum: ["outgoing", "incoming", "both"],
+                    default: "outgoing",
+                },
+                depth: {
+                    type: "integer",
+                    default: 1,
+                    minimum: 1,
+                    maximum: 5,
+                },
+                entityTypes: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                maxNodes: {
+                    type: "integer",
+                    default: 200,
+                },
+                maxEdges: {
+                    type: "integer",
+                    default: 500,
+                },
+            },
+        },
+    },
     {
         name: "kb_upsert",
         description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
@@ -216,3 +383,31 @@ export const TOOLS = [
         },
     },
 ];
+/**
+ * Inject _diagnostic_telemetry schema into tool inputs when diagnostic mode is enabled.
+ */
+function withDiagnosticTelemetrySchema(tools) {
+    return tools.map((tool) => {
+        const schema = tool.inputSchema;
+        const properties = schema.properties && typeof schema.properties === "object"
+            ? schema.properties
+            : {};
+        return {
+            ...tool,
+            inputSchema: {
+                ...schema,
+                properties: {
+                    ...properties,
+                    _diagnostic_telemetry: DIAGNOSTIC_TELEMETRY_SCHEMA,
+                },
+            },
+        };
+    });
+}
+/**
+ * Active tools list.
+ * In diagnostic mode, all tools include the _diagnostic_telemetry parameter.
+ */
+export const TOOLS = DIAGNOSTIC_MODE_ENABLED
+    ? withDiagnosticTelemetrySchema(BASE_TOOLS)
+    : BASE_TOOLS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,8 +9,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.2.7",
-    "kibi-core": "^0.1.10",
+    "kibi-cli": "^0.3.0",
+    "kibi-core": "^0.2.0",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"
@@ -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",