kibi-mcp 0.14.0 → 0.14.2

package/bin/kibi-mcp

@@ -18,6 +18,59 @@
 */
 const args = globalThis.Bun?.argv?.slice(2) ?? process.argv.slice(2);
 
+async function importStartupResolution() {
+  try {
+    return await import("../dist/startup-resolution.js");
+  } catch {
+    return await import("../src/startup-resolution.ts");
+  }
+}
+
+async function serverEntrypointUrl() {
+  const { existsSync } = await import("node:fs");
+  const distUrl = new URL("../dist/server.js", import.meta.url);
+  if (existsSync(distUrl)) {
+    return distUrl.href;
+  }
+  return new URL("../src/server.ts", import.meta.url).href;
+}
+
+async function buildResolution() {
+  const {
+    compareMcpResolution,
+    formatResolutionJson,
+    readRunningPackageInfo,
+    resolveProjectLocalMcp,
+  } = await importStartupResolution();
+  const running = readRunningPackageInfo(await serverEntrypointUrl());
+  const projectLocal = resolveProjectLocalMcp(process.cwd());
+  const comparison = compareMcpResolution(running, projectLocal);
+  const result = {
+    packageName: "kibi-mcp",
+    packageVersion: running.version,
+    version: running.version,
+    resolved: running.entrypoint,
+    cwd: process.cwd(),
+    running,
+    projectLocal,
+    ...comparison,
+  };
+
+  return { result, json: formatResolutionJson(result) };
+}
+
+async function importServer(entrypoint) {
+  if (entrypoint) {
+    const { pathToFileURL } = await import("node:url");
+    return await import(pathToFileURL(entrypoint).href);
+  }
+  try {
+    return await import("../dist/server.js");
+  } catch {
+    return await import("../src/server.ts");
+  }
+}
+
 function printHelp() {
   process.stdout.write(`Usage: kibi-mcp [options]
 
@@ -25,6 +78,7 @@ Starts the Kibi MCP server over stdio.
 
 Options:
   --diagnostic-mode  enable diagnostic logging to .kb/usage.log
+  --print-resolution print kibi-mcp startup resolution JSON and exit
   -h, --help         show help
 `);
 }
@@ -33,6 +87,11 @@ if (args.includes("-h") || args.includes("--help")) {
   printHelp();
   process.exitCode = 0;
 } else {
+  if (args.includes("--print-resolution")) {
+    const { json } = await buildResolution();
+    process.stdout.write(json);
+    process.exitCode = 0;
+  } else {
   if (args.includes("--diagnostic-mode") && !process.argv.includes("--diagnostic-mode")) {
     process.argv.push("--diagnostic-mode");
   }
@@ -43,7 +102,31 @@ if (args.includes("-h") || args.includes("--help")) {
     process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
   }
 
-  const { startServer } = await import("../dist/server.js");
+  const { result, json } = await buildResolution();
+  if (process.env.KIBI_MCP_DEBUG === "1" || args.includes("--diagnostic-mode")) {
+    process.stderr.write(json);
+  }
+
+  if (result.stale) {
+    if (result.projectLocal && process.env.KIBI_MCP_PROJECT_LOCAL_REENTRY !== "1") {
+      process.env.KIBI_MCP_PROJECT_LOCAL_REENTRY = "1";
+      process.stderr.write(
+        `[KIBI-MCP] Re-entering project-local kibi-mcp at ${result.projectLocal.entrypoint}; stale running path was ${result.running.entrypoint}\n`,
+      );
+      const { startServer } = await importServer(result.projectLocal.entrypoint);
+      startServer().catch((error) => {
+        console.error("Fatal error:", error);
+        process.exit(1);
+      });
+    } else {
+      const localEntrypoint = result.projectLocal?.entrypoint ?? "<not resolved>";
+      console.error(
+        `[KIBI-MCP] Refusing stale kibi-mcp startup. project-local entrypoint: ${localEntrypoint}; running entrypoint: ${result.running.entrypoint}`,
+      );
+      process.exit(1);
+    }
+  } else {
+  const { startServer } = await importServer();
 
   if (process.env.KIBI_MCP_DEBUG) {
   const originalStdoutWrite = process.stdout.write.bind(process.stdout);
@@ -84,4 +167,6 @@ if (args.includes("-h") || args.includes("--help")) {
     console.error("Fatal error:", error);
     process.exit(1);
   });
+  }
+  }
 }

package/dist/server/docs.js

@@ -33,6 +33,7 @@ function renderToolsDoc() {
         const required = Array.isArray(tool.inputSchema?.required)
             ? tool.inputSchema.required.join(", ")
             : "none";
+        lines.push(`| \`${tool.name}\` | ${tool.description} | ${required || "none"} |`);
     }
     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).");

package/dist/server/tools.js

@@ -10,6 +10,7 @@ import { handleKbGraph } from "../tools/graph.js";
 import { handleKbQuery } from "../tools/query.js";
 import { handleKbSearch } from "../tools/search.js";
 import { handleKbStatus } from "../tools/status.js";
+import { handleKbSkillsList, handleKbSkillsLoad, handleKbSkillsRead, } from "../tools/skills.js";
 import { handleKbUpsert } from "../tools/upsert.js";
 import { handleKbModelRequirement, } from "../tools/model-requirement.js";
 import { handleKbAutopilotGenerate, } from "../tools/autopilot-generate.js";
@@ -59,6 +60,9 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbQuery,
     handleKbSearch,
     handleKbStatus,
+    handleKbSkillsList,
+    handleKbSkillsLoad,
+    handleKbSkillsRead,
     handleKbUpsert,
     handleKbModelRequirement,
     handleKbAutopilotGenerate,
@@ -299,6 +303,9 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbStatus(prolog, args);
     }, runtime);
+    addTool(server, "kb_skills_list", toolDef("kb_skills_list").description, toolDef("kb_skills_list").inputSchema, async (args) => runtime.handleKbSkillsList(args), runtime);
+    addTool(server, "kb_skills_load", toolDef("kb_skills_load").description, toolDef("kb_skills_load").inputSchema, async (args) => runtime.handleKbSkillsLoad(args), runtime);
+    addTool(server, "kb_skills_read", toolDef("kb_skills_read").description, toolDef("kb_skills_read").inputSchema, async (args) => runtime.handleKbSkillsRead(args), runtime);
     addTool(server, "kb_find_gaps", toolDef("kb_find_gaps").description, toolDef("kb_find_gaps").inputSchema, async (args) => {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbFindGaps(prolog, args);

package/dist/startup-resolution.js

@@ -0,0 +1,110 @@
+/*
+ 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 { existsSync, readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const PACKAGE_NAME = "kibi-mcp";
+const FORBIDDEN_VERSION = "0.13.0";
+function toEntrypointPath(entrypointUrl) {
+    if (entrypointUrl.startsWith("file:")) {
+        return fileURLToPath(entrypointUrl);
+    }
+    return path.resolve(entrypointUrl);
+}
+function readJson(filePath) {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+}
+function nearestPackageJson(startPath) {
+    let current = path.dirname(startPath);
+    while (true) {
+        const candidate = path.join(current, "package.json");
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error(`Unable to find package.json for ${startPath}`);
+        }
+        current = parent;
+    }
+}
+function packageInfoFromEntrypoint(entrypoint) {
+    const normalizedEntrypoint = path.resolve(entrypoint);
+    const packageJsonPath = nearestPackageJson(normalizedEntrypoint);
+    const packageJson = readJson(packageJsonPath);
+    if (packageJson.name && packageJson.name !== PACKAGE_NAME) {
+        throw new Error(`Resolved package ${packageJson.name} for ${normalizedEntrypoint}; expected ${PACKAGE_NAME}`);
+    }
+    return {
+        packageRoot: path.dirname(packageJsonPath),
+        version: packageJson.version ?? "unknown",
+        entrypoint: normalizedEntrypoint,
+    };
+}
+export function readRunningPackageInfo(entrypointUrl) {
+    return packageInfoFromEntrypoint(toEntrypointPath(entrypointUrl));
+}
+export function resolveProjectLocalMcp(cwd) {
+    try {
+        const projectRequire = createRequire(path.join(path.resolve(cwd), "package.json"));
+        const resolved = projectRequire.resolve(PACKAGE_NAME);
+        const entrypoint = realpathSync.native?.(resolved) ?? realpathSync(resolved);
+        return packageInfoFromEntrypoint(entrypoint);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") {
+            return null;
+        }
+        return null;
+    }
+}
+export function compareMcpResolution(running, projectLocal) {
+    const diagnosticText = JSON.stringify({ running, projectLocal });
+    const forbiddenVersionObserved = diagnosticText.includes(FORBIDDEN_VERSION);
+    if (!projectLocal) {
+        return {
+            stale: false,
+            reason: "no project-local kibi-mcp resolved",
+            forbiddenVersionObserved,
+        };
+    }
+    if (running.version !== projectLocal.version) {
+        return {
+            stale: true,
+            reason: `version mismatch: running ${running.version}, project-local ${projectLocal.version}`,
+            forbiddenVersionObserved,
+        };
+    }
+    if (path.resolve(running.packageRoot) !== path.resolve(projectLocal.packageRoot)) {
+        return {
+            stale: true,
+            reason: `package root mismatch: running ${running.packageRoot}, project-local ${projectLocal.packageRoot}`,
+            forbiddenVersionObserved,
+        };
+    }
+    return {
+        stale: false,
+        reason: "running kibi-mcp matches project-local kibi-mcp",
+        forbiddenVersionObserved,
+    };
+}
+export function formatResolutionJson(result) {
+    return `${JSON.stringify(result, null, 2)}\n`;
+}

package/dist/tools/skills.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { listBundledSkills, loadBundledSkill, readBundledSkillResource, } from "kibi-cli/skills";
+// implements REQ-001
+export async function handleKbSkillsList(_args) {
+    try {
+        const skills = listBundledSkills();
+        const ids = skills.map((skill) => skill.id).join(", ") || "none";
+        return {
+            content: [{ type: "text", text: `Found ${skills.length} bundled skills: ${ids}` }],
+            structuredContent: { skills },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Skills list failed: ${message}`);
+    }
+}
+// implements REQ-001
+export async function handleKbSkillsLoad(args) {
+    try {
+        assertNonEmptyString(args.id, "id");
+        const bundle = loadBundledSkill(args.id);
+        const resources = bundle.manifest.resources ?? [];
+        const payload = {
+            metadata: bundle.manifest,
+            body: bundle.body,
+            resources,
+            contentHash: createHash("sha256").update(bundle.body, "utf8").digest("hex"),
+            sourceType: "bundled",
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Loaded bundled skill ${bundle.manifest.id} with ${resources.length} resources`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Skills load failed: ${message}`);
+    }
+}
+// implements REQ-001
+export async function handleKbSkillsRead(args) {
+    try {
+        assertNonEmptyString(args.id, "id");
+        assertNonEmptyString(args.resource, "resource");
+        const resourceContent = readBundledSkillResource(args.id, args.resource);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Read bundled skill resource ${args.id}/${args.resource}`,
+                },
+            ],
+            structuredContent: { content: resourceContent },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Skills read failed: ${message}`);
+    }
+}
+function assertNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${field} must be a non-empty string`);
+    }
+}

package/dist/tools-config.js

@@ -110,6 +110,46 @@ const BASE_TOOLS = [
             properties: {},
         },
     },
+    {
+        name: "kb_skills_list",
+        description: "List bundled Kibi agent skills available for progressive disclosure. Read-only; does not mutate the KB or require Prolog.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "kb_skills_load",
+        description: "Load a bundled Kibi agent skill by ID, returning its manifest metadata, Markdown body, declared resources, content hash, and source type. Read-only; does not execute scripts or require Prolog.",
+        inputSchema: {
+            type: "object",
+            required: ["id"],
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Bundled skill ID to load. Example: 'kibi-usage'.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_skills_read",
+        description: "Read a declared resource from a bundled Kibi agent skill. Resource paths are restricted to the skill manifest; arbitrary file paths are not exposed. Read-only; does not require Prolog.",
+        inputSchema: {
+            type: "object",
+            required: ["id", "resource"],
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Bundled skill ID. Example: 'kibi-usage'.",
+                },
+                resource: {
+                    type: "string",
+                    description: "Manifest-declared resource path to read. Example: 'resources/workflows.md'.",
+                },
+            },
+        },
+    },
     {
         name: "kb_find_gaps",
         description: "Run bulk missing/present relationship analysis over KB entities. Use for questions like which requirements lack scenarios or tests. No mutation side effects.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,7 +9,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.11.0",
+    "kibi-cli": "^0.11.1",
     "kibi-core": "^0.5.3",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",