kibi-mcp 0.22.0 → 1.0.0

package/dist/server/tools-runtime.js

@@ -1,16 +1,15 @@
-import { getSpec } from "kibi-cli/operations";
-import { nodeGit } from "kibi-cli/operations/node-ports";
+import { getSpec, nodeFilesystem, nodeGit } from "kibi-runtime";
 import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, classifyDiagnosticError, deriveDiagnosticFields, extractToolCallPayload, } from "../diagnostics.js";
 import { isMcpDebugEnabled } from "../env.js";
 import { createMcpRuntime } from "../runtime/mcp-runtime.js";
 import { TOOLS } from "../tools-config.js";
-import { handleKbAutopilotGenerate } from "../tools/autopilot-generate.js";
 import { handleKbCheck } from "../tools/check.js";
 import { handleKbCoverage } from "../tools/coverage.js";
 import { handleKbDelete } from "../tools/delete.js";
 import { handleKbFindGaps } from "../tools/find-gaps.js";
 import { handleKbGraph } from "../tools/graph.js";
 import { handleKbModelRequirement } from "../tools/model-requirement.js";
+import { handleKbPlanBootstrap } from "../tools/plan-bootstrap.js";
 import { handleKbQuery } from "../tools/query.js";
 import { handleKbSearch } from "../tools/search.js";
 import { handleKbSemanticAdvisor } from "../tools/semantic-advisor.js";
@@ -96,6 +95,7 @@ const operationRuntime = createMcpRuntime({
     attachedBranchKbPath: async () => (await getSessionModule()).attachedBranchKbPath,
     ensureProlog: async () => (await getSessionModule()).ensureProlog(),
     adaptProlog,
+    fs: nodeFilesystem,
     git: nodeGit,
     net: { fetch: (input, init) => globalThis.fetch(input, init) },
     refreshAttachedBranchStamp: async () => {
@@ -148,5 +148,5 @@ export const DEFAULT_TOOLS_RUNTIME = {
     handleKbValidateUpsert,
     handleKbModelRequirement,
     handleKbSuggestPredicates,
-    handleKbAutopilotGenerate,
+    handleKbPlanBootstrap,
 };

package/dist/server/tools.js

@@ -16,7 +16,8 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 import process from "node:process";
-import { executeOperation, } from "kibi-cli/operations/runtime-types";
+import { executeOperation } from "kibi-runtime";
+import { operationData, toKibiResult } from "kibi-runtime";
 import { isMcpDebugEnabled } from "../env.js";
 import { appendDiagnosticErrorUsage, appendDiagnosticSuccessUsage, } from "./diagnostic-usage.js";
 import { jsonSchemaToZod } from "./json-schema-to-zod.js";
@@ -26,6 +27,10 @@ export { jsonSchemaToZod } from "./json-schema-to-zod.js";
 export { _resetSessionModulePromise, _setToolsServerDepsForTests };
 const DEFAULT_TOOL_TIMEOUT_MS = 90_000;
 const TOOL_TIMEOUT_ENV = "KIBI_MCP_TOOL_TIMEOUT_MS";
+// Give cancellation and the Prolog reset a short bounded grace period, but do
+// not hold the MCP request open for the full five-second shutdown budget when
+// a handler never observes AbortSignal.
+const TOOL_TIMEOUT_GRACE_MS = 100;
 // implements REQ-008
 function debugLog(...args) {
     if (isMcpDebugEnabled()) {
@@ -45,7 +50,13 @@ function getToolTimeoutMs() {
 }
 // implements REQ-002
 function createToolTimeoutError(toolName, timeoutMs) {
-    return new Error(`Tool ${toolName} timed out after ${timeoutMs}ms`);
+    const error = new Error(`Tool ${toolName} timed out after ${timeoutMs}ms`);
+    Object.assign(error, { code: "KIBI_TOOL_TIMEOUT", toolName, timeoutMs });
+    return error;
+}
+function isToolTimeoutError(value) {
+    return (value instanceof Error &&
+        value.code === "KIBI_TOOL_TIMEOUT");
 }
 // implements REQ-002
 async function withToolTimeout(toolName, operation, onTimeout) {
@@ -57,8 +68,19 @@ async function withToolTimeout(toolName, operation, onTimeout) {
             new Promise((_, reject) => {
                 timeout = setTimeout(() => {
                     const error = createToolTimeoutError(toolName, timeoutMs);
-                    reject(error);
-                    void onTimeout(error, timeoutMs);
+                    // Do not report the timeout until cancellation/reset has completed
+                    // and the original request has reached a terminal state. This is
+                    // especially important for source-first mutations: a caller must
+                    // never retry while the authoritative journal is still deciding its
+                    // outcome.
+                    void onTimeout(error, timeoutMs)
+                        .then(async () => {
+                        await Promise.race([
+                            operation.then(() => undefined, () => undefined),
+                            new Promise((resolve) => setTimeout(resolve, TOOL_TIMEOUT_GRACE_MS)),
+                        ]);
+                    })
+                        .finally(() => reject(error));
                 }, timeoutMs);
             }),
         ]);
@@ -74,7 +96,7 @@ export function addTool(server, name, description, inputSchema, handler,
 // INTENTIONAL: DEFAULT_TOOLS_RUNTIME is typed as ToolsRuntime<PrologProcess>; the
 // generic TProlog parameter exists so tests can inject a mock type. The cast is safe
 // because the runtime object satisfies the full ToolsRuntime contract at runtime.
-runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations) {
+runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
     const wrappedHandler = async (args) => {
         const startedAt = new Date();
         const diagnosticModeEnabled = runtime.diagnosticModeEnabled();
@@ -127,6 +149,8 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations) {
                             error instanceof Error ? error.message : String(error);
                     }
                 });
+                const data = operationData(result);
+                const envelope = toKibiResult(operationSpec, data);
                 // Log usage in diagnostic mode
                 if (diagnosticModeEnabled) {
                     await appendDiagnosticSuccessUsage({
@@ -137,10 +161,22 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations) {
                         businessArgs,
                         telemetry,
                         startedAt,
-                        result,
+                        result: envelope,
                     });
                 }
-                return result;
+                if (result !== null &&
+                    typeof result === "object" &&
+                    !Array.isArray(result) &&
+                    "content" in result) {
+                    return {
+                        ...result,
+                        structuredContent: envelope,
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(envelope) }],
+                    structuredContent: envelope,
+                };
             }
             catch (error) {
                 // Log error in diagnostic mode
@@ -157,6 +193,48 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations) {
                         resetState: { resetAttempted, resetSucceeded, resetError },
                     });
                 }
+                if (isToolTimeoutError(error) &&
+                    operationSpec.effects.some((effect) => effect === "kb-write" || effect === "workspace-write")) {
+                    const recoveryActions = [
+                        {
+                            operation: "kb_status",
+                            reason: "Determine whether the mutation crossed the authoritative source/journal commit boundary before taking any further action.",
+                            required: true,
+                        },
+                        {
+                            operation: "kb_apply_plan",
+                            reason: "If status exposes a recovery journal, replay that typed journal action; never retry the timed-out mutation request.",
+                            required: true,
+                        },
+                    ];
+                    const timeoutData = {
+                        effectFailures: [
+                            {
+                                kind: "mutation",
+                                errorCode: "MUTATION_OUTCOME_UNKNOWN",
+                                detail: {
+                                    requestId,
+                                    timeoutMs: error.timeoutMs,
+                                },
+                            },
+                        ],
+                        nextActions: recoveryActions,
+                    };
+                    const envelope = toKibiResult(operationSpec, timeoutData, {
+                        status: "error",
+                        nextActions: recoveryActions,
+                        error: {
+                            code: "MUTATION_OUTCOME_UNKNOWN",
+                            message: "The mutation timed out after cancellation; its commit state is indeterminate. Inspect status and replay the typed recovery action if required.",
+                            retryable: false,
+                            details: { requestId, tool: name },
+                        },
+                    });
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(envelope) }],
+                        structuredContent: envelope,
+                    };
+                }
                 throw error;
             }
             finally {
@@ -176,6 +254,7 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations) {
     server.registerTool(name, {
         description,
         inputSchema: jsonSchemaToZod(inputSchema),
+        ...(outputSchema ? { outputSchema: jsonSchemaToZod(outputSchema) } : {}),
         ...(annotations ? { annotations } : {}),
     }, wrappedHandler);
 }

package/dist/server.js

@@ -21,18 +21,33 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { initializeDiagnosticMode } from "./diagnostics.js";
 import { loadDefaultEnvFile } from "./env.js";
 import { setupDocsAndPrompts } from "./server/docs.js";
+import { KIBI_ICONS } from "./server/icons.js";
 import { registerAllTools } from "./server/tools.js";
 import { connectTransport, setupTransportHandlers, } from "./server/transport.js";
 // Read version from package.json to prevent drift
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const VERSION = packageJson.version ?? "0.1.0";
+const SERVER_INSTRUCTIONS = [
+    "Kibi is a branch-local requirements knowledge base for software traceability.",
+    "Start with kb_search for discovery, then kb_query for exact lookups before any mutation.",
+    "Model requirements as linked facts via kb_model_requirement or kb_upsert (create endpoints before linking them).",
+    "Mutate sequentially with kb_upsert and kb_delete; validate with kb_check during iteration and run an unfiltered kb_check before completion.",
+    "Confirm branch freshness with kb_status. For first-time repository setup, use the kibi-bootstrap prompt.",
+].join(" ");
 export async function startServer() {
     // Load environment configuration
     loadDefaultEnvFile();
     // Initialize diagnostic mode if --diagnostic-mode flag is present
     initializeDiagnosticMode();
     // Create MCP server
-    const server = new McpServer({ name: "kibi-mcp", version: VERSION });
+    const server = new McpServer({
+        name: "kibi-mcp",
+        title: "Kibi MCP",
+        description: "Agent-native requirements compiler: branch-local knowledge base for requirements, scenarios, tests, facts, and code-symbol traceability.",
+        websiteUrl: "https://github.com/Looted/kibi",
+        version: VERSION,
+        icons: KIBI_ICONS,
+    }, { instructions: SERVER_INSTRUCTIONS });
     // Setup documentation resources and prompts
     setupDocsAndPrompts(server);
     // Register all KB tools

package/dist/tools/check-impact.js

@@ -15,7 +15,7 @@
  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 { analyzeChangedFileImpact, } from "kibi-cli/public/impact-diagnostics";
+import { analyzeChangedFileImpact, } from "kibi-runtime";
 export function hasImpactOptions(args) {
     return Boolean(args.includeImpactDiagnostics ||
         args.staged ||

package/dist/tools/check.js

@@ -1,4 +1,4 @@
-import { checkSpec } from "kibi-cli/operations";
+import { checkSpec } from "kibi-runtime";
 import { resolveWorkspaceRoot } from "../workspace.js";
 /**
  * Handle kb_check tool calls - run validation rules on the KB

package/dist/tools/core-module.js

@@ -1,7 +1,15 @@
 import path from "node:path";
-import { PrologProcess, resolveKbPlPath } from "kibi-cli/prolog";
-import { escapeAtomContent } from "kibi-cli/prolog/codec";
+import { PrologProcess, resolveKbPlPath } from "kibi-runtime";
+import { escapeAtomContent } from "kibi-runtime";
 import { getCoreModulePathOverride, getKbPlPathOverride } from "../env.js";
+function isPrologProcess(value) {
+    return (value instanceof PrologProcess ||
+        (value !== null &&
+            typeof value === "object" &&
+            typeof value.query === "function" &&
+            typeof value.invalidateCache ===
+                "function"));
+}
 // implements REQ-002, REQ-013
 export function resolveCorePlPath(fileName) {
     const override = getCoreModulePathOverride(fileName);
@@ -20,7 +28,7 @@ export function resolveCorePlPath(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)) {
+    if (!isPrologProcess(prolog)) {
         const mockedResult = await prolog.query(`(use_module('${modulePath}'), ${goal})`);
         if (!mockedResult.success) {
             throw new Error(`${errorLabel} query failed: ${mockedResult.error || "Unknown error"}`);

package/dist/tools/coverage.js

@@ -1,4 +1,4 @@
-import { executeCoverage, } from "kibi-cli/operations";
+import { executeCoverage, } from "kibi-runtime";
 import { createDiscoveryContext } from "./discovery-adapter.js";
 // implements REQ-002, REQ-013
 export async function handleKbCoverage(prolog, args, context) {

package/dist/tools/delete.js

@@ -1,4 +1,4 @@
-import { deleteSpec } from "kibi-cli/operations";
+import { deleteSpec } from "kibi-runtime";
 import { createMutationContext } from "./mutation-context.js";
 // implements REQ-kibi-operation-interface-parity
 export async function handleKbDelete(prolog, args) {

package/dist/tools/discovery-adapter.js

@@ -2,11 +2,16 @@ import { resolveWorkspaceRoot } from "../workspace.js";
 export function createDiscoveryContext(prolog, baseContext) {
     // implements REQ-kibi-operation-interface-parity
     let lastResult = null;
+    const mode = prolog
+        .useOneShotMode;
     const port = {
         query: async (goal) => {
             lastResult = await prolog.query(goal);
             return lastResult;
         },
+        oneShotMode: mode === undefined
+            ? typeof globalThis.Bun !== "undefined"
+            : Boolean(mode),
         nextSolution: async () => {
             const result = lastResult;
             lastResult = null;

package/dist/tools/entity-query.js

@@ -1 +1 @@
-export { VALID_ENTITY_TYPES, buildEntityGoal, dedupeEntities, loadEntities, paginateResults, validateEntityType, } from "kibi-cli/operations";
+export { VALID_ENTITY_TYPES, buildEntityGoal, dedupeEntities, loadEntities, paginateResults, validateEntityType, } from "kibi-runtime";

package/dist/tools/find-gaps.js

@@ -1,4 +1,11 @@
-import { executeFindGaps } from "kibi-cli/operations";
+import { executeFindGaps } from "kibi-runtime";
+function oneShotMode(prolog) {
+    const mode = prolog
+        .useOneShotMode;
+    return mode === undefined
+        ? typeof globalThis.Bun !== "undefined"
+        : Boolean(mode);
+}
 // implements REQ-002, REQ-013
 export async function handleKbFindGaps(prolog, args) {
     return executeFindGaps({ ...args }, {
@@ -7,6 +14,7 @@ export async function handleKbFindGaps(prolog, args) {
         clock: () => new Date(),
         prolog: {
             query: (goal) => prolog.query(goal),
+            oneShotMode: oneShotMode(prolog),
             nextSolution: async () => null,
             save: () => prolog.query("kb_save"),
         },

package/dist/tools/graph.js

@@ -1,4 +1,11 @@
-import { executeGraph } from "kibi-cli/operations";
+import { executeGraph } from "kibi-runtime";
+function oneShotMode(prolog) {
+    const mode = prolog
+        .useOneShotMode;
+    return mode === undefined
+        ? typeof globalThis.Bun !== "undefined"
+        : Boolean(mode);
+}
 // implements REQ-002, REQ-013
 export async function handleKbGraph(prolog, args) {
     return executeGraph({ ...args }, {
@@ -7,6 +14,7 @@ export async function handleKbGraph(prolog, args) {
         clock: () => new Date(),
         prolog: {
             query: (goal) => prolog.query(goal),
+            oneShotMode: oneShotMode(prolog),
             nextSolution: async () => null,
             save: () => prolog.query("kb_save"),
         },

package/dist/tools/model-requirement.js

@@ -1,5 +1,5 @@
-import { modelRequirementSpec, } from "kibi-cli/operations";
-import { estimateNormativeSignalConfidence, extractRequirementClaim, getWorkspaceMigrationWarning, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, } from "kibi-cli/operations/modeling/model-requirement";
+import { modelRequirementSpec } from "kibi-runtime";
+import { estimateNormativeSignalConfidence, extractRequirementClaim, getWorkspaceMigrationWarning, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, } from "kibi-runtime";
 import { resolveWorkspaceRoot } from "../workspace.js";
 export { estimateNormativeSignalConfidence, extractRequirementClaim, getWorkspaceMigrationWarning, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, };
 export async function handleKbModelRequirement(_prolog, args) {

package/dist/tools/mutation-context.js

@@ -1,13 +1,5 @@
 import * as fs from "node:fs/promises";
 import { resolveWorkspaceRoot } from "../workspace.js";
-const filesystem = {
-    readFile: (filePath) => fs.readFile(filePath, "utf8"),
-    writeFile: (filePath, data) => fs.writeFile(filePath, data, "utf8"),
-    mkdir: async (directoryPath) => {
-        await fs.mkdir(directoryPath, { recursive: true });
-    },
-    stat: (filePath) => fs.stat(filePath),
-};
 // implements REQ-kibi-operation-interface-parity
 export function createMutationContext(prolog) {
     const port = prolog === undefined
@@ -22,7 +14,21 @@ export function createMutationContext(prolog) {
         workspaceRoot: resolveWorkspaceRoot(),
         signal: new AbortController().signal,
         clock: () => new Date(),
-        fs: filesystem,
+        // The thin direct handler remains a compiled-KB compatibility surface.
+        // Production MCP registration supplies sourceFirst through the shared
+        // operation runtime while this adapter still exposes filesystem reads for
+        // symbol-granularity validation.
+        sourceFirst: false,
+        ...(process.env.KIBI_WORKSPACE !== undefined ? { fs: filesystem } : {}),
         ...(port === undefined ? {} : { prolog: port }),
     };
 }
+const filesystem = {
+    readFile: (filePath) => fs.readFile(filePath, "utf8"),
+    writeFile: (filePath, data) => fs.writeFile(filePath, data, "utf8"),
+    mkdir: async (directoryPath) => {
+        await fs.mkdir(directoryPath, { recursive: true });
+    },
+    stat: (filePath) => fs.stat(filePath),
+    unlink: (filePath) => fs.unlink(filePath),
+};

package/dist/tools/plan-bootstrap.js

@@ -0,0 +1,21 @@
+import { executePlanBootstrap, } from "kibi-runtime";
+import { nodeFilesystem, nodeGit } from "kibi-runtime";
+import { resolveWorkspaceRoot } from "../workspace.js";
+function isOperationContext(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        "workspaceRoot" in value &&
+        "signal" in value);
+}
+// implements REQ-mcp-kibi-bootstrap-bootstrap-v1, REQ-kibi-operation-interface-parity
+// implements REQ-KIBI-BOOTSTRAP-PLAN
+export async function handleKbPlanBootstrap(input, context) {
+    if (!isOperationContext(context))
+        throw new TypeError("Invalid bootstrap adapter invocation");
+    return executePlanBootstrap(input, {
+        ...context,
+        workspaceRoot: context.workspaceRoot || resolveWorkspaceRoot(),
+        fs: context.fs ?? nodeFilesystem,
+        git: context.git ?? nodeGit,
+    });
+}

package/dist/tools/prolog-list.js

@@ -15,7 +15,7 @@
  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 { splitTopLevel } from "kibi-cli/prolog/codec";
+import { splitTopLevel } from "kibi-runtime";
 // implements REQ-002
 export function parseAtomList(raw) {
     const trimmed = raw.trim();

package/dist/tools/query.js

@@ -1,4 +1,4 @@
-import { VALID_ENTITY_TYPES, querySpec } from "kibi-cli/operations";
+import { VALID_ENTITY_TYPES, querySpec } from "kibi-runtime";
 import { createDiscoveryContext } from "./discovery-adapter.js";
 export { VALID_ENTITY_TYPES };
 export async function handleKbQuery(prolog, args) {

package/dist/tools/relationship-validation.js

@@ -1,4 +1,4 @@
-import { formatInvalidRelationshipError, formatInvalidRelationshipTuple, formatRelationshipSourceMismatch, validateLiveRelationshipTargets as validateSharedTargets, } from "kibi-cli/operations/mutation/relationships";
+import { formatInvalidRelationshipError, formatInvalidRelationshipTuple, formatRelationshipSourceMismatch, validateLiveRelationshipTargets as validateSharedTargets, } from "kibi-runtime";
 export { formatInvalidRelationshipError, formatInvalidRelationshipTuple, formatRelationshipSourceMismatch, };
 export async function validateLiveRelationshipTargets(prolog, entity, relationships) {
     const port = {

package/dist/tools/search.js

@@ -1,4 +1,4 @@
-import { searchSpec } from "kibi-cli/operations";
+import { searchSpec } from "kibi-runtime";
 import { createDiscoveryContext } from "./discovery-adapter.js";
 export async function handleKbSearch(prolog, args) {
     // implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery

package/dist/tools/semantic-advisor.js

@@ -1,4 +1,4 @@
-import { executeSemanticAdvisor } from "kibi-cli/operations";
+import { executeSemanticAdvisor } from "kibi-runtime";
 export async function handleKbSemanticAdvisor(args) {
     return executeSemanticAdvisor(args);
 }

package/dist/tools/skills.js

@@ -1,5 +1,5 @@
-import { skillsListSpec, skillsLoadSpec, skillsReadSpec, } from "kibi-cli/operations";
-import { loadBundledSkill } from "kibi-cli/skills";
+import { skillsListSpec, skillsLoadSpec, skillsReadSpec, } from "kibi-runtime";
+import { loadBundledSkill } from "kibi-runtime";
 function runtimeContext() {
     return {
         workspaceRoot: process.cwd(),

package/dist/tools/sparql.js

@@ -1,4 +1,4 @@
-import { sparqlRemoteSpec } from "kibi-cli/operations";
+import { sparqlRemoteSpec } from "kibi-runtime";
 // implements REQ-002, REQ-013, REQ-kibi-operation-interface-parity
 export async function handleSparql(prologOrArgs, legacyArgs) {
     const args = legacyArgs ?? ("endpoint" in prologOrArgs ? prologOrArgs : undefined);

package/dist/tools/status.js

@@ -1,4 +1,4 @@
-import { statusSpec } from "kibi-cli/operations";
+import { statusSpec } from "kibi-runtime";
 import { createDiscoveryContext } from "./discovery-adapter.js";
 export async function handleKbStatus(prolog, args, context) {
     // implements REQ-kibi-operation-interface-parity

package/dist/tools/suggest-predicates.js

@@ -1,4 +1,4 @@
-import { suggestPredicatesSpec, } from "kibi-cli/operations";
+import { suggestPredicatesSpec } from "kibi-runtime";
 import { resolveWorkspaceRoot } from "../workspace.js";
 import { createDiscoveryContext } from "./discovery-adapter.js";
 export async function handleKbSuggestPredicates(prolog, args) {