kibi-mcp 0.2.3 → 0.3.0

package/dist/tools/query.js

@@ -1,27 +1,4 @@
-/*
- 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/>.
-*/
-/**
- * Escape a string for embedding inside a single-quoted Prolog atom.
- * Doubles single-quote characters per ISO Prolog standard.
- */
-function escapeAtomContent(value) {
-    return value.replace(/'/g, "''");
-}
+import { escapeAtomContent, parseEntityFromBinding, parseEntityFromList, parseListOfLists, } from "kibi-cli/prolog/codec";
 export const VALID_ENTITY_TYPES = [
     "req",
     "scenario",
@@ -68,13 +45,15 @@ export async function handleKbQuery(prolog, args) {
             goal = `findall(['${safeId}',Type,Props], kb_entity('${safeId}', Type, Props), Results)`;
         }
         else if (tags && tags.length > 0) {
-            const tagList = `[${tags.map((t) => `'${escapeAtomContent(t)}'`).join(",")}]`;
+            // 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), memberchk(tags=Tags, Props), member(Tag, Tags), member(Tag, ${tagList})), Results)`;
+                goal = `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
             }
             else {
-                goal = `findall([Id,Type,Props], (kb_entity(Id, Type, Props), memberchk(tags=Tags, Props), member(Tag, Tags), member(Tag, ${tagList})), Results)`;
+                goal = "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
             }
         }
         else if (type) {
@@ -101,6 +80,9 @@ export async function handleKbQuery(prolog, args) {
         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);
         // Build human-readable text with entity IDs and titles
@@ -138,234 +120,34 @@ export async function handleKbQuery(prolog, args) {
         throw new Error(`Query execution failed: ${message}`);
     }
 }
-/**
- * Parse a Prolog list of lists into a JavaScript array.
- * Input: "[[a,b,c],[d,e,f]]"
- * Output: [["a", "b", "c"], ["d", "e", "f"]]
- */
-export function parseListOfLists(listStr) {
-    const cleaned = listStr.trim().replace(/^\[/, "").replace(/\]$/, "");
-    if (cleaned === "") {
-        return [];
+function hasAnyTag(entity, requestedTags) {
+    const expected = new Set(requestedTags.map(normalizeTagValue));
+    const rawTags = entity.tags;
+    if (!Array.isArray(rawTags) || rawTags.length === 0) {
+        return false;
     }
-    const results = [];
-    let depth = 0;
-    let current = "";
-    let currentList = [];
-    for (let i = 0; i < cleaned.length; i++) {
-        const char = cleaned[i];
-        if (char === "[") {
-            depth++;
-            if (depth > 1)
-                current += char;
-        }
-        else if (char === "]") {
-            depth--;
-            if (depth === 0) {
-                if (current) {
-                    currentList.push(current.trim());
-                    current = "";
-                }
-                if (currentList.length > 0) {
-                    results.push(currentList);
-                    currentList = [];
-                }
-            }
-            else {
-                current += char;
-            }
-        }
-        else if (char === "," && depth === 1) {
-            if (current) {
-                currentList.push(current.trim());
-                current = "";
-            }
-        }
-        else if (char === "," && depth === 0) {
-            // Skip comma between lists
-        }
-        else {
-            current += char;
+    for (const tag of rawTags) {
+        if (expected.has(normalizeTagValue(tag))) {
+            return true;
         }
     }
-    return results;
-}
-/**
- * Parse a single entity from Prolog binding format.
- * Input: "[abc123, req, [id=abc123, title=\"Test\", ...]]"
- */
-export function parseEntityFromBinding(bindingStr) {
-    const cleaned = bindingStr.trim().replace(/^\[/, "").replace(/\]$/, "");
-    const parts = splitTopLevel(cleaned, ",");
-    if (parts.length < 3) {
-        return {};
-    }
-    const id = parts[0].trim();
-    const type = parts[1].trim();
-    const propsStr = parts.slice(2).join(",").trim();
-    const props = parsePropertyList(propsStr);
-    return { ...props, id: normalizeEntityId(stripOuterQuotes(id)), type };
+    return false;
 }
-/**
- * Parse entity from array returned by parseListOfLists.
- * Input: ["abc123", "req", "[id=abc123, title=\"Test\", ...]"]
- */
-export function parseEntityFromList(data) {
-    if (data.length < 3) {
-        return {};
-    }
-    const id = data[0].trim();
-    const type = data[1].trim();
-    const propsStr = data[2].trim();
-    const props = parsePropertyList(propsStr);
-    return { ...props, id: normalizeEntityId(stripOuterQuotes(id)), type };
+function normalizeTagValue(tag) {
+    return String(tag).trim();
 }
-/**
- * Parse Prolog property list into JavaScript object.
- */
-export function parsePropertyList(propsStr) {
-    const props = {};
-    let cleaned = propsStr.trim();
-    if (cleaned.startsWith("[")) {
-        cleaned = cleaned.substring(1);
-    }
-    if (cleaned.endsWith("]")) {
-        cleaned = cleaned.substring(0, cleaned.length - 1);
-    }
-    const pairs = splitTopLevel(cleaned, ",");
-    for (const pair of pairs) {
-        const eqIndex = pair.indexOf("=");
-        if (eqIndex === -1)
-            continue;
-        const key = pair.substring(0, eqIndex).trim();
-        const value = pair.substring(eqIndex + 1).trim();
-        if (key === "..." || value === "..." || value === "...|...") {
+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;
         }
-        const parsed = parsePrologValue(value);
-        props[key] = parsed;
-    }
-    return props;
-}
-/**
- * Parse a single Prolog value, handling typed literals and URIs.
- */
-export function parsePrologValue(valueInput) {
-    const value = valueInput.trim();
-    // Handle typed literal: ^^("value", type)
-    if (value.startsWith("^^(")) {
-        const innerStart = value.indexOf("(") + 1;
-        let depth = 1;
-        let innerEnd = innerStart;
-        for (let i = innerStart; i < value.length; i++) {
-            if (value[i] === "(")
-                depth++;
-            if (value[i] === ")") {
-                depth--;
-                if (depth === 0) {
-                    innerEnd = i;
-                    break;
-                }
-            }
-        }
-        const innerContent = value.substring(innerStart, innerEnd);
-        const parts = splitTopLevel(innerContent, ",");
-        if (parts.length >= 2) {
-            let literalValue = parts[0].trim();
-            if (literalValue.startsWith('"') && literalValue.endsWith('"')) {
-                literalValue = literalValue.substring(1, literalValue.length - 1);
-            }
-            // Handle array notation
-            if (literalValue.startsWith("[") && literalValue.endsWith("]")) {
-                const listContent = literalValue.substring(1, literalValue.length - 1);
-                if (listContent === "") {
-                    return [];
-                }
-                return splitTopLevel(listContent, ",").map((item) => item.trim());
-            }
-            return literalValue;
-        }
-    }
-    // Handle URI
-    if (value.startsWith("file:///")) {
-        const lastSlash = value.lastIndexOf("/");
-        if (lastSlash !== -1) {
-            return value.substring(lastSlash + 1);
-        }
-        return value;
-    }
-    // Handle quoted string
-    if (value.startsWith('"') && value.endsWith('"')) {
-        return value.substring(1, value.length - 1);
-    }
-    // Handle quoted atom
-    if (value.startsWith("'") && value.endsWith("'")) {
-        return value.substring(1, value.length - 1);
-    }
-    // Handle list
-    if (value.startsWith("[") && value.endsWith("]")) {
-        const listContent = value.substring(1, value.length - 1);
-        if (listContent === "") {
-            return [];
-        }
-        const items = splitTopLevel(listContent, ",").map((item) => {
-            return parsePrologValue(item.trim());
-        });
-        return items;
-    }
-    return value;
-}
-/**
- * Split a string by delimiter at the top level (not inside brackets or quotes).
- */
-export function splitTopLevel(str, delimiter) {
-    const results = [];
-    let current = "";
-    let depth = 0;
-    let inQuotes = false;
-    for (let i = 0; i < str.length; i++) {
-        const char = str[i];
-        const prevChar = i > 0 ? str[i - 1] : "";
-        if (char === '"' && prevChar !== "\\") {
-            inQuotes = !inQuotes;
-            current += char;
-        }
-        else if (!inQuotes && (char === "[" || char === "(")) {
-            depth++;
-            current += char;
-        }
-        else if (!inQuotes && (char === "]" || char === ")")) {
-            depth--;
-            current += char;
-        }
-        else if (!inQuotes && depth === 0 && char === delimiter) {
-            if (current) {
-                results.push(current);
-                current = "";
-            }
-        }
-        else {
-            current += char;
-        }
-    }
-    if (current) {
-        results.push(current);
-    }
-    return results;
-}
-function stripOuterQuotes(value) {
-    if (value.startsWith("'") && value.endsWith("'")) {
-        return value.slice(1, -1);
-    }
-    if (value.startsWith('"') && value.endsWith('"')) {
-        return value.slice(1, -1);
-    }
-    return value;
-}
-function normalizeEntityId(value) {
-    if (!value.startsWith("file:///")) {
-        return value;
+        seen.add(key);
+        deduped.push(entity);
     }
-    const idx = value.lastIndexOf("/");
-    return idx === -1 ? value : value.slice(idx + 1);
+    return deduped;
 }

package/dist/tools/suggest-shared-facts.js

@@ -1,20 +1,3 @@
-/*
- 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 { parseAtomList } from "./prolog-list.js";
 /**
  * Handle analyze_shared_facts tool calls
@@ -96,7 +79,7 @@ function analyzeSharedConcepts(requirements, existingFacts, minFreq) {
         const capitalizedTerms = originalText.matchAll(/\b([A-Z][a-z]+)\b/g);
         // Extract repeated phrases (2+ words)
         // Extract repeated phrases (2+ words)
-        const words = text.split(/\s+/).filter(w => w.length > 3);
+        const words = text.split(/\s+/).filter((w) => w.length > 3);
         for (let i = 0; i < words.length - 1; i++) {
             const phrase = `${words[i]} ${words[i + 1]}`;
             if (!conceptCounts.has(phrase)) {
@@ -133,6 +116,6 @@ function analyzeSharedConcepts(requirements, existingFacts, minFreq) {
 function capitalizeConcept(concept) {
     return concept
         .split(/\s+/)
-        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
         .join(" ");
 }

package/dist/tools/symbols.js

@@ -15,33 +15,6 @@
  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 { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";

package/dist/tools/upsert.js

@@ -16,18 +16,10 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import Ajv from "ajv";
+import { escapeAtom, toPrologAtom } from "kibi-cli/prolog/codec";
 import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
-function escapeAtom(value) {
-    return value.replace(/'/g, "''");
-}
-function toPrologAtom(value) {
-    const simplePrologAtom = /^[a-z][a-zA-Z0-9_]*$/;
-    return simplePrologAtom.test(value)
-        ? value
-        : `'${value.replace(/'/g, "''")}'`;
-}
 const ajv = new Ajv({ strict: false });
 const validateEntity = ajv.compile(entitySchema);
 const validateRelationship = ajv.compile(relationshipSchema);
@@ -122,11 +114,17 @@ export async function handleKbUpsert(prolog, args) {
             }
             relationshipsCreated++;
         }
-        // Save KB to disk
+        // Note: kb_save is intentionally NOT called here for performance.
+        // Callers that need durability across restarts should explicitly call kb_save.
+        // This allows batching multiple upserts before a single disk write.
+        prolog.invalidateCache();
+        // Save KB to disk to ensure durability across process restarts
         await prolog.query("kb_save");
         prolog.invalidateCache();
+        // multiple upserts and save once at the end for better performance.
+        prolog.invalidateCache();
         let contradictionPairsDetected;
-        if (type === "req") {
+        if (type === "req" && !args._skipContradictionCheck) {
             contradictionPairsDetected = await detectContradictionPairs(prolog, id);
         }
         if (type === "symbol") {

package/dist/tools-config.js

@@ -15,37 +15,10 @@
  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
-*/
 export const TOOLS = [
     {
         name: "kb_query",
-        description: "Read entities from the KB with filters. Use for discovery and lookup before edits. Do not use for writes. No mutation side effects.",
+        description: "Read entities from the KB with filters. Use for discovery and lookup before edits. Do not use for writes. No mutation side effects. Tags filter by metadata tags only, not entity IDs.",
         inputSchema: {
             type: "object",
             properties: {
@@ -91,7 +64,7 @@ export const TOOLS = [
     },
     {
         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. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
+        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.",
         inputSchema: {
             type: "object",
             required: ["type", "id", "properties"],
@@ -228,7 +201,7 @@ export const TOOLS = [
     },
     {
         name: "kb_check",
-        description: "Run KB validation rules and return violations. Use before or after mutations. Do not use for point lookups. No write side effects.",
+        description: "Run KB validation rules and return violations. Use before or after mutations. Do not use for point lookups. No write side effects. Prefer explicit rules for faster iteration.",
         inputSchema: {
             type: "object",
             properties: {
@@ -238,13 +211,16 @@ export const TOOLS = [
                         type: "string",
                         enum: [
                             "must-priority-coverage",
+                            "symbol-coverage",
+                            "symbol-traceability",
                             "no-dangling-refs",
                             "no-cycles",
                             "required-fields",
-                            "symbol-coverage",
+                            "deprecated-adr-no-successor",
+                            "domain-contradictions",
                         ],
                     },
-                    description: "Optional rule subset. Allowed: must-priority-coverage, no-dangling-refs, no-cycles, required-fields, symbol-coverage. If omitted, server runs all.",
+                    description: "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions. If omitted, server runs all.",
                 },
             },
         },

package/dist/workspace.js

@@ -15,33 +15,6 @@
  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 fs from "node:fs";
 import path from "node:path";
 const WORKSPACE_ENV_KEYS = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.2.3",
+  "version": "0.3.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.3",
-    "kibi-core": "^0.1.7",
+    "kibi-cli": "^0.2.5",
+    "kibi-core": "^0.1.8",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"