kibi-mcp 0.3.3 → 0.4.0

package/dist/diagnostics.js

@@ -83,6 +83,35 @@ export const DIAGNOSTIC_TELEMETRY_SCHEMA = {
         },
     },
 };
+// 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.
  */

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,11 +17,16 @@
  */
 import process from "node:process";
 import { z } from "zod";
-import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, extractToolCallPayload, } from "../diagnostics.js";
+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 { activeBranchName, ensureProlog, inFlightRequests, isShuttingDown, prologProcess, } from "./session.js";
 const ACTIVE_TOOLS = TOOLS;
@@ -164,6 +169,7 @@ function addTool(server, name, description, inputSchema, handler) {
                 // 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,
@@ -176,6 +182,7 @@ function addTool(server, name, description, inputSchema, handler) {
                         duration_ms: finishedAt.getTime() - startedAt.getTime(),
                         prolog_pid: prologProcess?.getPid() ?? null,
                         active_branch: activeBranchName,
+                        ...diagnosticFields,
                     });
                 }
                 return result;
@@ -218,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);
@@ -229,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/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,73 +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) {
-            // JS-side fallback until REQ-mcp-tag-filtering-server-side is implemented.
-            if (type) {
-                const safeType = escapeAtomContent(type);
-                goal = `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
-            }
-            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) {
@@ -118,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

@@ -64,6 +64,172 @@ const BASE_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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.3.3",
+  "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"