kibi-mcp 0.16.0 → 0.16.1

package/dist/server/tools.js

@@ -30,9 +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 = {
@@ -79,6 +81,7 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbDelete,
     handleKbFindGaps,
     handleKbGraph,
+    handleSparql,
     handleKbQuery,
     handleKbSearch,
     handleKbStatus,
@@ -86,6 +89,7 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbSkillsLoad,
     handleKbSkillsRead,
     handleKbUpsert,
+    handleKbValidateUpsert,
     handleKbModelRequirement,
     handleKbSuggestPredicates,
     handleKbAutopilotGenerate,
@@ -393,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);

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})]`;
+}

package/dist/tools/suggest-predicates.js

@@ -525,6 +525,9 @@ export async function handleKbSuggestPredicates(prolog, args) {
     })
         .slice(0, maxCandidates)
         .map((scored) => buildSuggestion(scored.schema, text, subject, scored.score));
+    if (candidates.length === 0) {
+        warnings.push("No predicate candidate met minScore. If this is recurring domain language, create a fact_kind=predicate_schema fact; otherwise keep the generated review:ontology-gap observation. Do not invent unsupported predicate names without a predicate_schema.");
+    }
     const recommendedAction = candidates.length > 0 ? "apply_requires_predicate" : "record_ontology_gap";
     const firstCandidate = candidates[0];
     const applyPlan = firstCandidate

package/dist/tools/upsert.js

@@ -19,6 +19,7 @@ import path from "node:path";
 */
 import Ajv from "ajv";
 import { escapeAtom, toPrologAtom, toPrologString, } from "kibi-cli/prolog/codec";
+import { SYMBOL_ROLES, getBehavioralSymbolNames, getNonBehavioralSymbolNames, inferSymbolRole, isAllowedGranularityReason, isTraceabilityRelationshipType, } from "kibi-cli/public/symbol-granularity";
 import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
 import { Project, ScriptKind } from "ts-morph";
@@ -46,72 +47,136 @@ const validateEntity = ajv.compile({
                 "legacy-link",
             ],
         },
+        symbol_role: {
+            type: "string",
+            enum: [...SYMBOL_ROLES],
+        },
     },
 });
 const validateRelationship = ajv.compile(relationshipSchema);
-const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
-    "implements",
-    "covered_by",
-    "executable_for",
+const PROPERTY_ALIAS_HINTS = new Map([
+    ["subjectKey", "subject_key"],
+    ["propertyKey", "property_key"],
+    ["predicateName", "predicate_name"],
+    ["predicateArgs", "predicate_args"],
+    ["canonicalKey", "canonical_key"],
+    ["closedWorld", "closed_world"],
 ]);
-const ALLOWED_GRANULARITY_REASONS = new Set([
-    "config-artifact",
-    "module-level-behavior",
-    "extractor-miss",
-    "legacy-link",
-]);
-/**
- * Handle kb.upsert tool calls
- * Accepts { type, id, properties } — the flat format matching the tool schema.
- * Validates the assembled entity against JSON Schema before Prolog writes.
- * implements REQ-002, REQ-011
- */
-export async function handleKbUpsert(prolog, args) {
-    const { type, id, properties, relationships = [] } = args;
-    if (!type || !id) {
-        throw new Error("'type' and 'id' are required for upsert");
+const PROPERTY_VALUE_FIELDS = [
+    "value_string",
+    "value_int",
+    "value_number",
+    "value_bool",
+];
+function valueFieldHint(value) {
+    if (typeof value === "boolean") {
+        return `Use value_type: "bool" plus value_bool: ${String(value)}.`;
     }
-    // Assemble full entity from flat args + properties
-    const entity = {
-        id,
-        type,
-        ...properties,
-    };
-    // Fill in defaults for optional required fields
-    if (!entity.created_at) {
-        entity.created_at = new Date().toISOString();
+    if (typeof value === "number") {
+        return Number.isInteger(value)
+            ? `Use value_type: "int" plus value_int: ${String(value)}.`
+            : `Use value_type: "number" plus value_number: ${String(value)}.`;
     }
-    if (!entity.updated_at) {
-        entity.updated_at = new Date().toISOString();
+    if (typeof value === "string") {
+        return `Use value_type: "string" plus value_string: ${JSON.stringify(value)}.`;
     }
-    if (!entity.source) {
-        entity.source = "mcp://kibi/upsert";
+    return "Use value_type plus exactly one of value_string, value_int, value_number, or value_bool.";
+}
+function ajvErrorParams(error) {
+    return error.params;
+}
+function factKindShapeHints(entity) {
+    if (entity.type !== "fact")
+        return [];
+    if (entity.fact_kind === "property_value") {
+        const missing = [
+            "subject_key",
+            "property_key",
+            "operator",
+            "value_type",
+        ].filter((field) => entity[field] === undefined);
+        const presentValueFields = PROPERTY_VALUE_FIELDS.filter((field) => entity[field] !== undefined);
+        const hints = [];
+        if (missing.length > 0) {
+            hints.push(`fact_kind 'property_value' requires ${missing.join(", ")}.`);
+        }
+        if (presentValueFields.length !== 1) {
+            hints.push("fact_kind 'property_value' requires exactly one typed value field: value_string, value_int, value_number, or value_bool.");
+        }
+        if (hints.length > 0) {
+            hints.push("Next action: use kb_model_requirement for prose claims, or provide subject_key, property_key, operator, value_type, and one value_* field in kb_upsert.properties.");
+        }
+        return hints;
     }
-    const entities = [entity];
-    // Validate all entities
-    for (let i = 0; i < entities.length; i++) {
-        const ent = entities[i];
-        if (!validateEntity(ent)) {
-            const errors = validateEntity.errors || [];
-            const errorMessages = errors
-                .map((e) => `${e.instancePath || "root"}: ${e.message}`)
-                .join("; ");
-            throw new Error(`Entity validation failed: ${errorMessages}`);
+    if (entity.fact_kind === "predicate") {
+        const predicateArgs = entity.predicate_args;
+        const hasPredicateArgs = Array.isArray(predicateArgs) && predicateArgs.length > 0;
+        const missing = [
+            ...(entity.predicate_name === undefined ? ["predicate_name"] : []),
+            ...(!hasPredicateArgs ? ["predicate_args"] : []),
+            ...(entity.canonical_key === undefined ? ["canonical_key"] : []),
+        ];
+        const hints = [];
+        if (missing.length > 0) {
+            hints.push(`fact_kind 'predicate' requires ${missing.join(", ")}.`);
         }
+        if (hints.length > 0) {
+            hints.push("Next action: call kb_suggest_predicates before hand-writing ontology predicate facts.");
+        }
+        return hints;
     }
-    // Validate all relationships
-    for (let i = 0; i < relationships.length; i++) {
-        const rel = relationships[i];
-        if (!validateRelationship(rel)) {
-            const errors = validateRelationship.errors || [];
-            const errorMessages = errors
-                .map((e) => `${e.instancePath || "root"}: ${e.message}`)
-                .join("; ");
-            throw new Error(`Relationship validation failed at index ${i}: ${errorMessages}`);
+    return [];
+}
+function formatEntityValidationErrors(entity, errors) {
+    const messages = errors.map((error) => {
+        const path = error.instancePath || "root";
+        const params = ajvErrorParams(error);
+        if (error.keyword === "additionalProperties" && params.additionalProperty) {
+            const property = params.additionalProperty;
+            const suggested = PROPERTY_ALIAS_HINTS.get(property);
+            if (property === "value") {
+                return `${path}: unknown property 'value'. ${valueFieldHint(entity.value)} Do not use generic value in kb_upsert.properties.`;
+            }
+            if (suggested) {
+                return `${path}: unknown property '${property}'. Did you mean '${suggested}'? kb_upsert.properties uses snake_case typed fact fields.`;
+            }
+        }
+        if (error.keyword === "enum" && params.allowedValues) {
+            return `${path}: ${error.message}. Allowed values: ${params.allowedValues.map(String).join(", ")}`;
+        }
+        return `${path}: ${error.message}`;
+    });
+    const extraHints = factKindShapeHints(entity);
+    for (const [alias, canonical] of PROPERTY_ALIAS_HINTS) {
+        if (Object.prototype.hasOwnProperty.call(entity, alias)) {
+            extraHints.push(`Unknown property '${alias}'. Use '${canonical}' in kb_upsert.properties.`);
         }
     }
-    validateRelationshipSources(id, relationships);
-    validateSymbolGranularity(entity, relationships);
+    if (Object.prototype.hasOwnProperty.call(entity, "value")) {
+        extraHints.push(valueFieldHint(entity.value));
+    }
+    if (Object.keys(entity).some((key) => PROPERTY_ALIAS_HINTS.has(key)) ||
+        Object.prototype.hasOwnProperty.call(entity, "value")) {
+        extraHints.push("Next action: if starting from prose, call kb_model_requirement and apply its sequential applyPlan instead of guessing field names.");
+    }
+    return [...messages, ...extraHints].join("; ");
+}
+function validateFactModelingShape(entity) {
+    const hints = factKindShapeHints(entity);
+    if (hints.length > 0) {
+        throw new Error(`Entity validation failed: ${hints.join("; ")}`);
+    }
+}
+/**
+ * Handle kb.upsert tool calls
+ * Accepts { type, id, properties } — the flat format matching the tool schema.
+ * Validates the assembled entity against JSON Schema before Prolog writes.
+ * implements REQ-002, REQ-011
+ */
+export async function handleKbUpsert(prolog, args) {
+    const { entity, relationships } = validateKbUpsertArgs(args);
+    const type = entity.type;
+    const entities = [entity];
     // Validate strict-lane fact_kind pairing for constrains/requires_property
     // implements REQ-011
     await validateStrictLanePairing(prolog, relationships);
@@ -193,12 +258,12 @@ export async function handleKbUpsert(prolog, args) {
         }
         if (type === "symbol") {
             try {
-                await refreshCoordinatesForSymbolIdImpl(id);
+                await refreshCoordinatesForSymbolIdImpl(entity.id);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 if (isMcpDebugEnabled()) {
-                    console.warn(`[KIBI-MCP] Symbol coordinate auto-refresh failed for ${id}: ${message}`);
+                    console.warn(`[KIBI-MCP] Symbol coordinate auto-refresh failed for ${String(entity.id)}: ${message}`);
                 }
             }
         }
@@ -206,7 +271,7 @@ export async function handleKbUpsert(prolog, args) {
             content: [
                 {
                     type: "text",
-                    text: `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
+                    text: `Upserted ${String(entity.id)} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
                 },
             ],
             structuredContent: {
@@ -221,6 +286,45 @@ export async function handleKbUpsert(prolog, args) {
         throw new Error(`Upsert execution failed: ${message}`);
     }
 }
+export function validateKbUpsertArgs(args) {
+    const { type, id, properties, relationships = [] } = args;
+    if (!type || !id) {
+        throw new Error("'type' and 'id' are required for upsert");
+    }
+    const entity = {
+        id,
+        type,
+        ...properties,
+    };
+    if (!entity.created_at) {
+        entity.created_at = new Date().toISOString();
+    }
+    if (!entity.updated_at) {
+        entity.updated_at = new Date().toISOString();
+    }
+    if (!entity.source) {
+        entity.source = "mcp://kibi/upsert";
+    }
+    if (!validateEntity(entity)) {
+        const errors = validateEntity.errors || [];
+        const errorMessages = formatEntityValidationErrors(entity, errors);
+        throw new Error(`Entity validation failed: ${errorMessages}`);
+    }
+    validateFactModelingShape(entity);
+    for (let i = 0; i < relationships.length; i++) {
+        const rel = relationships[i];
+        if (!validateRelationship(rel)) {
+            const errors = validateRelationship.errors || [];
+            const errorMessages = errors
+                .map((e) => `${e.instancePath || "root"}: ${e.message}`)
+                .join("; ");
+            throw new Error(`Relationship validation failed at index ${i}: ${errorMessages}`);
+        }
+    }
+    validateRelationshipSources(id, relationships);
+    validateSymbolGranularity(entity, relationships);
+    return { entity, relationships };
+}
 function chooseScriptKind(filePath) {
     const lower = filePath.toLowerCase();
     if (lower.endsWith(".tsx"))
@@ -235,58 +339,69 @@ function chooseScriptKind(filePath) {
     return ScriptKind.JS;
 }
 function hasTraceabilityRelationship(relationships) {
-    return relationships.some((relationship) => typeof relationship.type === "string" &&
-        TRACEABILITY_RELATIONSHIP_TYPES.has(relationship.type));
+    return relationships.some((relationship) => isTraceabilityRelationshipType(relationship.type));
 }
 function hasAllowedGranularityReason(entity) {
-    const reason = entity.granularity_reason;
-    return typeof reason === "string" && ALLOWED_GRANULARITY_REASONS.has(reason);
+    return isAllowedGranularityReason(entity.granularity_reason);
 }
-function collectNarrowExportNames(filePath, content) {
+function createSymbolCandidate(name, kind) {
+    return {
+        name,
+        kind,
+        role: inferSymbolRole(kind),
+    };
+}
+function collectGranularSymbolCandidates(filePath, content) {
     const project = new Project({ skipAddingFilesFromTsConfig: true });
     const sourceFile = project.createSourceFile(`${filePath}::granularity`, content, {
         overwrite: true,
         scriptKind: chooseScriptKind(filePath),
     });
-    const names = new Set();
+    const candidates = [];
     const methodNameCounts = new Map();
+    const bareMethodCandidates = new Map();
     for (const fn of sourceFile.getFunctions()) {
         if (fn.isExported()) {
             const name = fn.getName();
             if (name)
-                names.add(name);
+                candidates.push(createSymbolCandidate(name, "function"));
         }
     }
     for (const cls of sourceFile.getClasses()) {
         if (cls.isExported()) {
             const name = cls.getName();
             if (name)
-                names.add(name);
+                candidates.push(createSymbolCandidate(name, "class"));
             for (const method of cls.getMethods()) {
                 const methodName = method.getName();
-                if (name)
-                    names.add(`${name}.${methodName}`);
+                if (name) {
+                    candidates.push(createSymbolCandidate(`${name}.${methodName}`, "method"));
+                }
+                bareMethodCandidates.set(methodName, createSymbolCandidate(methodName, "method"));
                 methodNameCounts.set(methodName, (methodNameCounts.get(methodName) ?? 0) + 1);
             }
         }
     }
     for (const [methodName, count] of methodNameCounts) {
-        if (count === 1)
-            names.add(methodName);
+        const candidate = bareMethodCandidates.get(methodName);
+        if (count === 1 && candidate)
+            candidates.push(candidate);
     }
     for (const iface of sourceFile.getInterfaces()) {
-        if (iface.isExported())
-            names.add(iface.getName());
+        if (iface.isExported()) {
+            candidates.push(createSymbolCandidate(iface.getName(), "interface"));
+        }
     }
     for (const alias of sourceFile.getTypeAliases()) {
-        if (alias.isExported())
-            names.add(alias.getName());
+        if (alias.isExported()) {
+            candidates.push(createSymbolCandidate(alias.getName(), "type"));
+        }
     }
     for (const en of sourceFile.getEnums()) {
         if (en.isExported())
-            names.add(en.getName());
+            candidates.push(createSymbolCandidate(en.getName(), "enum"));
     }
-    return [...names].sort();
+    return candidates.sort((a, b) => a.name.localeCompare(b.name));
 }
 function validateSymbolGranularity(entity, relationships) {
     if (entity.type !== "symbol")
@@ -304,12 +419,20 @@ function validateSymbolGranularity(entity, relationships) {
         : path.resolve(process.cwd(), entity.sourceFile);
     if (!existsSync(sourcePath))
         return;
-    const narrowNames = collectNarrowExportNames(entity.sourceFile, readFileSync(sourcePath, "utf8"));
-    if (narrowNames.length === 0)
+    const candidates = collectGranularSymbolCandidates(entity.sourceFile, readFileSync(sourcePath, "utf8"));
+    const candidateNames = [
+        ...new Set(candidates.map((candidate) => candidate.name)),
+    ];
+    if (candidateNames.includes(entity.title))
         return;
-    if (narrowNames.includes(entity.title))
+    const behavioralNames = getBehavioralSymbolNames(candidates);
+    if (behavioralNames.length === 0)
         return;
-    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available: ${narrowNames.join(", ")}. Move relationships to the narrow symbol or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, or legacy-link.`);
+    const nonBehavioralNames = getNonBehavioralSymbolNames(candidates);
+    const ignoredSymbolsMessage = nonBehavioralNames.length > 0
+        ? ` Non-behavioral symbols in the file were ignored for this decision: ${nonBehavioralNames.join(", ")}.`
+        : "";
+    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralNames.join(", ")}. Move relationships to a behavioral symbol, add a manifest behavioral anchor, or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, or legacy-link.${ignoredSymbolsMessage}`);
 }
 export const __test__ = {
     // implements REQ-vscode-traceability
@@ -333,6 +456,7 @@ function buildPropertyList(entity) {
         "owner",
         "priority",
         "severity",
+        "symbol_role",
         // Typed fact enum fields must be atoms for Prolog validation
         "fact_kind",
         "operator",

package/dist/tools/validate-upsert.js

@@ -0,0 +1,37 @@
+import { validateKbUpsertArgs } from "./upsert.js";
+export async function handleKbValidateUpsert(args) {
+    try {
+        const { entity } = validateKbUpsertArgs(args);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "kb_validate_upsert: payload is valid for kb_upsert preflight checks. No mutation was performed.",
+                },
+            ],
+            structuredContent: {
+                valid: true,
+                errors: [],
+                warnings: [],
+                normalizedPreview: entity,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `kb_validate_upsert: payload is invalid. ${message}`,
+                },
+            ],
+            structuredContent: {
+                valid: false,
+                errors: [message],
+                warnings: [],
+                normalizedPreview: null,
+            },
+        };
+    }
+}

package/dist/tools-config.js

@@ -270,9 +270,31 @@ const BASE_TOOLS = [
             },
         },
     },
+    {
+        name: "kb_sparql_remote",
+        description: "Opt-in remote SPARQL query tool for external HTTP(S) RDF endpoints. This does not query Kibi's local RDF store directly, stores no credentials, and depends on network availability.",
+        inputSchema: {
+            type: "object",
+            required: ["endpoint", "query"],
+            properties: {
+                endpoint: {
+                    type: "string",
+                    description: "Remote SPARQL endpoint URL. Must start with http:// or https://.",
+                },
+                query: {
+                    type: "string",
+                    description: "SPARQL SELECT query to send to the remote endpoint.",
+                },
+                timeoutMs: {
+                    type: "number",
+                    description: "Optional positive timeout in milliseconds for the remote query.",
+                },
+            },
+        },
+    },
     {
         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`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. 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 kb_model_requirement before hand-writing strict property facts from prose, and kb_suggest_predicates before hand-writing ontology predicate facts. 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`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
         inputSchema: {
             type: "object",
             required: ["type", "id", "properties"],
@@ -351,6 +373,18 @@ const BASE_TOOLS = [
                             ],
                             description: "Optional justification for a coarse file/module-level symbol traceability relationship when narrower function/class/type symbols exist.",
                         },
+                        symbol_role: {
+                            type: "string",
+                            enum: [
+                                "behavioral",
+                                "structural",
+                                "type-shape",
+                                "config",
+                                "module",
+                                "unknown",
+                            ],
+                            description: "Optional role classification for symbol entities. Example: 'behavioral'.",
+                        },
                         fact_kind: {
                             type: "string",
                             enum: [
@@ -361,15 +395,15 @@ const BASE_TOOLS = [
                                 "predicate_schema",
                                 "predicate",
                             ],
-                            description: "Optional fact lane kind for fact entities. Strict lane uses 'subject' and 'property_value'; context lane uses 'observation' or 'meta'.",
+                            description: "Optional fact lane kind for fact entities. Strict lane uses 'subject' and 'property_value'; context lane uses 'observation' or 'meta'; ontology lane uses 'predicate_schema' or 'predicate'. Use kb_model_requirement or kb_suggest_predicates when starting from prose.",
                         },
                         subject_key: {
                             type: "string",
-                            description: "Optional canonical subject key for strict fact entities. Example: 'user.session'.",
+                            description: "Snake_case only. Optional canonical subject key for strict fact entities. Example: 'user.session'. Do not use subjectKey in kb_upsert.properties.",
                         },
                         property_key: {
                             type: "string",
-                            description: "Optional canonical property key for property_value facts. Example: 'session.timeout_minutes'.",
+                            description: "Snake_case only. Optional canonical property key for property_value facts. Example: 'session.timeout_minutes'. Do not use propertyKey in kb_upsert.properties.",
                         },
                         operator: {
                             type: "string",
@@ -379,7 +413,7 @@ const BASE_TOOLS = [
                         value_type: {
                             type: "string",
                             enum: ["string", "int", "number", "bool"],
-                            description: "Optional typed value discriminator for property_value facts.",
+                            description: "Optional typed value discriminator for property_value facts. Pair with exactly one value_string, value_int, value_number, or value_bool; do not use generic value.",
                         },
                         value_string: {
                             type: "string",
@@ -420,12 +454,12 @@ const BASE_TOOLS = [
                         },
                         predicate_name: {
                             type: "string",
-                            description: "Optional predicate name for ontology predicate facts.",
+                            description: "Optional predicate name for ontology predicate facts. Prefer kb_suggest_predicates before hand-writing predicate_name.",
                         },
                         predicate_args: {
                             type: "array",
                             items: { type: "string" },
-                            description: "Optional ordered predicate arguments for ontology predicate facts.",
+                            description: "Optional ordered predicate arguments for ontology predicate facts. Prefer kb_suggest_predicates before hand-writing predicate_args.",
                         },
                     },
                     required: ["title", "status"],
@@ -473,6 +507,38 @@ const BASE_TOOLS = [
             },
         },
     },
+    {
+        name: "kb_validate_upsert",
+        description: "Validate a kb_upsert payload without mutating the KB. Use this read-only preflight when modeling strict facts or predicates and you want actionable schema/modeling errors before calling kb_upsert.",
+        inputSchema: {
+            type: "object",
+            required: ["type", "id", "properties"],
+            properties: {
+                type: {
+                    type: "string",
+                    enum: [
+                        "req",
+                        "scenario",
+                        "test",
+                        "adr",
+                        "flag",
+                        "event",
+                        "symbol",
+                        "fact",
+                    ],
+                },
+                id: { type: "string" },
+                properties: {
+                    type: "object",
+                    description: "Entity properties to validate using the same snake_case field names accepted by kb_upsert.",
+                },
+                relationships: {
+                    type: "array",
+                    items: { type: "object" },
+                },
+            },
+        },
+    },
     {
         name: "kb_delete",
         description: "Delete entities by ID. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. Side effects: mutates and saves KB; skips entities with dependents.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,8 +9,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.12.4",
-    "kibi-core": "^0.6.0",
+    "kibi-cli": "^0.12.5",
+    "kibi-core": "^0.6.1",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"