kibi-mcp 0.15.3 → 0.16.1

package/dist/diagnostics.js

@@ -37,7 +37,7 @@ let diagnosticUsageLogPath = null;
 export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
     diagnosticUsageLogPath = null;
     if (!enabled) {
-        Reflect.deleteProperty(process.env, "KIBI_MCP_DIAGNOSTIC_MODE");
+        process.env.KIBI_MCP_DIAGNOSTIC_MODE = "0";
         return;
     }
     const workspaceRoot = resolveWorkspaceRoot();

package/dist/server/docs.js

@@ -38,6 +38,7 @@ function renderToolsDoc() {
     lines.push("");
     lines.push("Modeling note: Kibi has eight core entity types grouped into common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).");
     lines.push("Only strict domain facts (`fact_kind: subject` + `property_value`) participate in contradiction inference; use `flag` for runtime/config gates and `fact_kind: observation` or `meta` for bug/workaround notes.");
+    lines.push("Predicate flow: before writing ontology prose, call `kb_suggest_predicates`; apply a suggested `fact_kind: predicate` via `requires_predicate`, or record the returned `review:ontology-gap` observation when no predicate fits.");
     return lines.join("\n");
 }
 export const PROMPTS = [
@@ -135,8 +136,9 @@ export const PROMPTS = [
             "3. **Create-before-link**: Create endpoint entities with `kb_upsert` before linking them.",
             "4. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
             "5. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property` (automated via `kb_model_requirement`).",
-            "5. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
-            "6. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need.",
+            "6. **Suggest predicates before prose**: For ontology-lane requirements, spell out the prose claim and call `kb_suggest_predicates` before writing `fact_kind: observation`. Apply the selected `fact_kind: predicate` applyPlan, then attach the returned `relationshipPlan` as `requires_predicate` while preserving existing req metadata; use the returned `review:ontology-gap` observation when no predicate fits.",
+            "7. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
+            "8. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need.",
             "",
             "If a tool returns empty results, do not assume failure. Re-check filters (type, id, tags, sourceFile, limit, or offset).",
         ].join("\n"),
@@ -203,16 +205,16 @@ 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',
         "",
+        "## Model requirements as ontology predicates",
+        '1. Spell out the requirement prose and call `kb_suggest_predicates` with `{ "text": "...", "requirementId": "REQ-..." }`',
+        "2. If candidates are returned, apply the top or user-selected `structuredContent.applyPlan` to create `fact_kind: predicate`, then attach `structuredContent.relationshipPlan` with `requires_predicate` while preserving existing req metadata",
+        "3. If no candidate fits, apply or review the returned `review:ontology-gap` observation instead of silently writing prose",
+        "",
         "Note: Kibi has eight core entity types. Create or reuse `fact` entities first, then create `req` entities and link with `constrains` and `requires_property` (create-before-link).",
         "Only strict domain facts are contradiction-safe. Use `flag` for runtime/config gates; use `fact` with `fact_kind: observation` or `meta` for bug/workaround notes.",
         "",
         "## Find missing coverage",
         '1. `kb_find_gaps` with `{ "type": "req", "missingRelationships": ["specified_by", "verified_by"] }` to find under-linked requirements',
-        "",
-        "## Find missing coverage",
-        "",
-        "## 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',
         "",

package/dist/server/tools.js

@@ -30,8 +30,11 @@ import { handleKbModelRequirement, } from "../tools/model-requirement.js";
 import { handleKbQuery } from "../tools/query.js";
 import { handleKbSearch } from "../tools/search.js";
 import { handleKbSkillsList, handleKbSkillsLoad, handleKbSkillsRead, } from "../tools/skills.js";
+import { handleSparql } from "../tools/sparql.js";
 import { handleKbStatus } from "../tools/status.js";
+import { handleKbSuggestPredicates, } from "../tools/suggest-predicates.js";
 import { handleKbUpsert } from "../tools/upsert.js";
+import { handleKbValidateUpsert } from "../tools/validate-upsert.js";
 const DEFAULT_TOOL_TIMEOUT_MS = 90_000;
 const TOOL_TIMEOUT_ENV = "KIBI_MCP_TOOL_TIMEOUT_MS";
 const defaultToolsServerDeps = {
@@ -78,6 +81,7 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbDelete,
     handleKbFindGaps,
     handleKbGraph,
+    handleSparql,
     handleKbQuery,
     handleKbSearch,
     handleKbStatus,
@@ -85,7 +89,9 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbSkillsLoad,
     handleKbSkillsRead,
     handleKbUpsert,
+    handleKbValidateUpsert,
     handleKbModelRequirement,
+    handleKbSuggestPredicates,
     handleKbAutopilotGenerate,
 };
 // implements REQ-008
@@ -391,10 +397,17 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbGraph(prolog, args);
     }, runtime);
+    addTool(server, "kb_sparql_remote", toolDef("kb_sparql_remote").description, toolDef("kb_sparql_remote").inputSchema, async (args) => {
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleSparql(prolog, args);
+    }, runtime);
     addTool(server, "kb_upsert", toolDef("kb_upsert").description, toolDef("kb_upsert").inputSchema, async (args) => {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbUpsert(prolog, args);
     }, runtime);
+    addTool(server, "kb_validate_upsert", toolDef("kb_validate_upsert").description, toolDef("kb_validate_upsert").inputSchema, async (args) => {
+        return runtime.handleKbValidateUpsert(args);
+    }, runtime);
     addTool(server, "kb_delete", toolDef("kb_delete").description, toolDef("kb_delete").inputSchema, async (args) => {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbDelete(prolog, args);
@@ -407,6 +420,10 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbModelRequirement(prolog, args);
     }, runtime);
+    addTool(server, "kb_suggest_predicates", toolDef("kb_suggest_predicates").description, toolDef("kb_suggest_predicates").inputSchema, async (args) => {
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbSuggestPredicates(prolog, args);
+    }, runtime);
     addTool(server, "kb_autopilot_generate", toolDef("kb_autopilot_generate").description, toolDef("kb_autopilot_generate").inputSchema, async (args) => {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbAutopilotGenerate(prolog, args);

package/dist/tools/autopilot-discovery.js

@@ -847,7 +847,7 @@ export async function classifyActivationState(workspaceRoot, prolog) {
     }
 }
 // Recursively collect markdown files under `dir`, excluding known ignore dirs.
-function collectMarkdownFiles(dir, workspaceRoot, vendoredRoots) {
+export function collectMarkdownFiles(dir, workspaceRoot, vendoredRoots) {
     const results = [];
     if (!fs.existsSync(dir))
         return results;

package/dist/tools/autopilot-generate.js

@@ -6,6 +6,25 @@ import { buildGenericMarkdownCandidates, buildNormativeRequirementCandidates, bu
 import { discoverProviderEvidence, resolveActivationPolicy, } from "./autopilot-discovery.js";
 import { loadEntities } from "./entity-query.js";
 import { getWorkspaceMigrationWarning } from "./model-requirement.js";
+const defaultAutopilotGenerateDeps = {
+    buildGenericMarkdownCandidates,
+    buildNormativeRequirementCandidates,
+    buildProviderEvidenceCandidates,
+    buildSymbolManifestCandidates,
+    buildTypedMarkdownCandidates,
+    collectSourceOnlyAuthoringSignals,
+    discoverProviderEvidence,
+    getWorkspaceMigrationWarning,
+    loadEntities,
+    resolveActivationPolicy,
+};
+let autopilotGenerateDeps = defaultAutopilotGenerateDeps;
+export function _setAutopilotGenerateDepsForTests(deps) {
+    autopilotGenerateDeps = { ...defaultAutopilotGenerateDeps, ...deps };
+}
+export function _resetAutopilotGenerateDepsForTests() {
+    autopilotGenerateDeps = defaultAutopilotGenerateDeps;
+}
 function clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
 }
@@ -377,7 +396,7 @@ _prolog, args) {
     // Gather existing entity ids to suppress duplicates
     let existingIds = new Set();
     try {
-        const entities = await loadEntities(prolog, {});
+        const entities = await autopilotGenerateDeps.loadEntities(prolog, {});
         for (const e of entities) {
             const id = String(e.id ?? "");
             if (id)
@@ -389,10 +408,10 @@ _prolog, args) {
         existingIds = new Set();
     }
     const workspaceRoot = resolveWorkspaceRoot();
-    const activation = await resolveActivationPolicy(workspaceRoot, prolog);
+    const activation = await autopilotGenerateDeps.resolveActivationPolicy(workspaceRoot, prolog);
     const activationState = activation.activationState;
-    const activationDiscovery = discoverProviderEvidence(workspaceRoot, activation);
-    const migrationWarning = await getWorkspaceMigrationWarning(workspaceRoot);
+    const activationDiscovery = autopilotGenerateDeps.discoverProviderEvidence(workspaceRoot, activation);
+    const migrationWarning = await autopilotGenerateDeps.getWorkspaceMigrationWarning(workspaceRoot);
     const declaredContext = normalizeBootstrapContext(bootstrapContext);
     const discoveredCandidatePaths = activationDiscovery.evidence.reduce((acc, item) => {
         const relativePath = item.relativePath;
@@ -414,7 +433,7 @@ _prolog, args) {
             markdownFiles: [],
             evidence: candidateDiscovery.evidence.filter((item) => item.kind !== "generic_markdown"),
         };
-    let sourceOnlySignals = collectSourceOnlyAuthoringSignals(guidanceDiscovery, {
+    let sourceOnlySignals = autopilotGenerateDeps.collectSourceOnlyAuthoringSignals(guidanceDiscovery, {
         ids: existingIds,
         workspaceRoot,
     }, normalizedMinConfidence);
@@ -435,28 +454,31 @@ _prolog, args) {
         return `${entityType}::${String(title).trim().toLowerCase().replace(/\s+/g, " ")}`;
     }
     if (activation.allowCandidateGeneration) {
-        typedMarkdownCandidates = buildTypedMarkdownCandidates(candidateDiscovery, {
-            ids: existingIds,
-            workspaceRoot,
-        });
-        manifestCandidates = buildSymbolManifestCandidates(candidateDiscovery, {
+        typedMarkdownCandidates =
+            autopilotGenerateDeps.buildTypedMarkdownCandidates(candidateDiscovery, {
+                ids: existingIds,
+                workspaceRoot,
+            });
+        manifestCandidates = autopilotGenerateDeps.buildSymbolManifestCandidates(candidateDiscovery, {
             ids: existingIds,
             workspaceRoot,
         });
         if (includeGenericMarkdown) {
-            genericCandidates = buildGenericMarkdownCandidates(candidateDiscovery, {
+            genericCandidates = autopilotGenerateDeps.buildGenericMarkdownCandidates(candidateDiscovery, {
                 ids: existingIds,
                 workspaceRoot,
             }, normalizedMinConfidence);
-            normativeRequirementCandidates = buildNormativeRequirementCandidates(candidateDiscovery, {
+            normativeRequirementCandidates =
+                autopilotGenerateDeps.buildNormativeRequirementCandidates(candidateDiscovery, {
+                    ids: existingIds,
+                    workspaceRoot,
+                }, normalizedMinConfidence);
+        }
+        providerEvidenceCandidates =
+            autopilotGenerateDeps.buildProviderEvidenceCandidates(candidateDiscovery, {
                 ids: existingIds,
                 workspaceRoot,
             }, normalizedMinConfidence);
-        }
-        providerEvidenceCandidates = buildProviderEvidenceCandidates(candidateDiscovery, {
-            ids: existingIds,
-            workspaceRoot,
-        }, normalizedMinConfidence);
         allCandidates = [
             ...typedMarkdownCandidates,
             ...manifestCandidates,

package/dist/tools/model-requirement.js

@@ -308,6 +308,15 @@ export async function handleKbModelRequirement(_prolog, args) {
     });
     const applyPlan = strictWriteSetToApplyPlan(writeSet);
     const migrationWarning = await getWorkspaceMigrationWarning();
+    const warnings = writeSet.isStrict
+        ? []
+        : [
+            {
+                kind: "low_confidence_observation_downgrade",
+                message: `Claim confidence ${writeSet.confidence.toFixed(2)} is below the strict threshold 0.70, so Kibi emitted an observation fact instead of strict subject/property facts.`,
+                nextAction: "If this is normative, provide subjectKey, propertyKey, operator, and value explicitly, then apply the returned strict write-set sequentially.",
+            },
+        ];
     const strictSummary = writeSet.isStrict
         ? `Modeled strict requirement into ${applyPlan.length} sequential applyPlan step(s).`
         : "Modeled a non-blocking observation review artifact; deterministic claim extraction stayed below the strict threshold.";
@@ -322,6 +331,7 @@ export async function handleKbModelRequirement(_prolog, args) {
         confidence: writeSet.confidence,
         extractionMode: extracted.extractionMode,
         extractionWarnings: extracted.extractionWarnings,
+        warnings,
         migrationWarning,
     };
     return {

package/dist/tools/sparql.js

@@ -0,0 +1,96 @@
+import { runJsonModuleQuery, toPrologAtom } from "./core-module.js";
+// implements REQ-002, REQ-013
+export async function handleSparql(prolog, args) {
+    validateSparqlArgs(args);
+    try {
+        const payload = await runJsonModuleQuery(prolog, "sparql_client.pl", `kibi_sparql_client:remote_sparql_select_json(${toPrologAtom(args.endpoint)}, ${toPrologAtom(args.query)}, ${toSparqlOptions(args)}, JsonString)`, "SPARQL remote query");
+        const rows = payload?.rows ?? [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Remote SPARQL query returned ${rows.length} row${rows.length === 1 ? "" : "s"}.`,
+                },
+            ],
+            ...(payload !== undefined ? { structuredContent: payload } : {}),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`SPARQL remote query failed: ${message}`);
+    }
+}
+function validateSparqlArgs(args) {
+    if (!args.endpoint || args.endpoint.trim().length === 0) {
+        throw new Error("SPARQL endpoint is required");
+    }
+    if (!args.query || args.query.trim().length === 0) {
+        throw new Error("SPARQL query is required");
+    }
+    if (!isRemoteHttpEndpoint(args.endpoint)) {
+        throw new Error("SPARQL endpoint must be an http:// or https:// URL");
+    }
+    if (!isSelectQuery(args.query)) {
+        throw new Error("SPARQL query must be a SELECT query");
+    }
+    if (!isPublicRemoteEndpoint(args.endpoint)) {
+        throw new Error("SPARQL endpoint must target a public remote host");
+    }
+    if (args.timeoutMs !== undefined &&
+        (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+        throw new Error("SPARQL timeoutMs must be a positive number when provided");
+    }
+}
+function isRemoteHttpEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function isSelectQuery(query) {
+    return /^\s*select\b/i.test(query);
+}
+function isPublicRemoteEndpoint(endpoint) {
+    const url = new URL(endpoint);
+    const host = normalizeHostname(url.hostname);
+    return !isLocalOrPrivateHost(host);
+}
+function normalizeHostname(hostname) {
+    return hostname
+        .toLowerCase()
+        .replace(/^\[/, "")
+        .replace(/\]$/, "")
+        .replace(/\.$/, "");
+}
+function isLocalOrPrivateHost(host) {
+    if (host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host === "0.0.0.0" ||
+        host === "::1" ||
+        (host.includes(":") &&
+            (host.startsWith("fe80:") ||
+                host.startsWith("fc") ||
+                host.startsWith("fd")))) {
+        return true;
+    }
+    const octets = host.split(".").map((part) => Number(part));
+    if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet))) {
+        return false;
+    }
+    const [first = -1, second = -1] = octets;
+    return (first === 10 ||
+        first === 127 ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168));
+}
+function toSparqlOptions(args) {
+    if (args.timeoutMs === undefined) {
+        return "[]";
+    }
+    const timeoutSeconds = Math.max(1, Math.ceil(args.timeoutMs / 1000));
+    return `[timeout(${timeoutSeconds})]`;
+}