kibi-mcp 0.2.3 → 0.3.0

package/dist/env.js

@@ -15,33 +15,6 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
 import fs from "node:fs";
 import { resolveEnvFilePath, resolveWorkspaceRoot } from "./workspace.js";
 const DEFAULT_ENV_FILE = ".env";

package/dist/server/docs.js

@@ -0,0 +1,260 @@
+/*
+ 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 { TOOLS } from "../tools-config.js";
+const ACTIVE_TOOLS = TOOLS;
+function renderToolsDoc() {
+    const lines = [
+        "# kibi-mcp Tools",
+        "",
+        "Use this reference to choose the correct tool before calling it.",
+        "",
+        "| Tool | Summary | Required Parameters |",
+        "| --- | --- | --- |",
+    ];
+    for (const tool of ACTIVE_TOOLS) {
+        const required = Array.isArray(tool.inputSchema?.required)
+            ? tool.inputSchema.required.join(", ")
+            : "none";
+        lines.push(`| ${tool.name} | ${tool.description} | ${required} |`);
+    }
+    return lines.join("\n");
+}
+export const PROMPTS = [
+    {
+        name: "init-kibi",
+        description: "Bootstrap Kibi on an existing repository with zero entities.",
+        text: [
+            "# Kibi Initialization Workflow",
+            "",
+            "Use this workflow to retroactively bootstrap Kibi on an existing repository with zero entities.",
+            "",
+            "## Phase 1: Discovery",
+            "1. Scan project structure to identify:",
+            "   - Requirements (docs/requirements/, README, specs)",
+            "   - Tests (unit, integration, e2e)",
+            "   - Architecture decisions (docs/adr/, ARCHITECTURE.md)",
+            "   - Feature flags (environment files, config)",
+            "   - Events (domain events, pub/sub topics)",
+            "   - Core symbols (key functions, classes, modules)",
+            "",
+            "## Phase 2: Fact Extraction",
+            "1. Identify atomic domain facts (invariants, constraints, properties)",
+            "2. Create reusable fact entities with `kb_upsert` using type 'fact'",
+            "3. Use consistent IDs: FACT-XXX with descriptive titles",
+            "",
+            "## Phase 3: Requirement Encoding",
+            "1. Extract requirements from documentation",
+            "2. For each requirement, determine which facts it constrains or requires",
+            "3. Create req entities with `kb_upsert` using type 'req'",
+            "4. Link reqs to facts using `constrains` and `requires_property` relationships",
+            "5. Reuse fact IDs across related requirements for contradiction detection",
+            "",
+            "## Phase 4: Test Linking",
+            "1. Map existing tests to requirements they verify",
+            "2. Create test entities with `kb_upsert` using type 'test'",
+            "3. Link tests to requirements using `verified_by` relationship",
+            "",
+            "## Phase 5: Architecture Documentation",
+            "1. Extract ADRs from docs/adr/ or decision records",
+            "2. Create adr entities with `kb_upsert` using type 'adr'",
+            "3. Link ADRs to symbols they constrain using `constrained_by`",
+            "",
+            "## Phase 6: Event Catalog",
+            "1. Identify domain/system events from code",
+            "2. Create event entities with `kb_upsert` using type 'event'",
+            "3. Link symbols that publish/consume events using `publishes`/`consumes`",
+            "",
+            "## Phase 7: Symbol Mapping",
+            "1. Map key code symbols to requirements",
+            "2. Create symbol entities with `kb_upsert` using type 'symbol'",
+            "3. Link symbols to requirements using `implements`",
+            "",
+            "## Phase 8: Validation",
+            "1. Run `kb_check` with all rules to verify integrity",
+            "2. Fix any dangling references or constraint violations",
+            "3. Re-run validation until clean",
+            "",
+            "## Best Practices",
+            "- Start with high-value entities first (critical requirements, security constraints)",
+            "- Use incremental batches to avoid overwhelming the KB",
+            "- Always call `kb_query` before creating to avoid duplicate entities",
+            "- Run `kb_check` after each batch of changes",
+        ].join("\n"),
+    },
+    {
+        name: "kibi_overview",
+        description: "High-level model for using kibi-mcp safely and effectively.",
+        text: [
+            "# kibi-mcp Overview",
+            "",
+            "Treat this server as a branch-aware knowledge graph interface for software traceability.",
+            "",
+            "The server exposes 4 public tools for KB operations:",
+            "- `kb_query`: Read-only lookup of entities by type, ID, tags, or source file",
+            "- `kb_upsert`: Create or update entities and their relationships",
+            "- `kb_delete`: Remove entities by ID (with dependency safety checks)",
+            "- `kb_check`: Validate KB integrity against configurable rules",
+            "",
+            "Core modeling principles:",
+            "- Encode requirements as linked facts: `req --constrains--> fact` plus `req --requires_property--> fact`.",
+            "- Reuse canonical fact IDs across requirements; shared constrained facts make contradictions detectable.",
+            "- Use `kb_query` first to confirm current state before any mutation.",
+            "- Use `kb_upsert` and `kb_delete` only for intentional, traceable KB changes.",
+            "- Run `kb_check` after meaningful mutations to catch integrity issues early.",
+            "- Prefer explicit IDs and enum values to avoid invalid parameters.",
+            "- Assume every write can affect downstream traceability queries.",
+        ].join("\n"),
+    },
+    {
+        name: "kibi_workflow",
+        description: "Step-by-step call order for discovery, mutation, and verification.",
+        text: [
+            "# kibi-mcp Workflow",
+            "",
+            "Follow this sequence for reliable operation:",
+            "",
+            "1. **Query-first**: Always call `kb_query` to confirm current state before any mutation.",
+            "2. **Create-before-link**: Create endpoint entities with `kb_upsert` before linking them.",
+            "3. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
+            "4. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property`.",
+            "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.",
+            "",
+            "If a tool returns empty results, do not assume failure. Re-check filters (type, id, tags, sourceFile, limit, or offset).",
+        ].join("\n"),
+    },
+    {
+        name: "kibi_constraints",
+        description: "Operational limits, validation rules, and mutation gotchas.",
+        text: [
+            "# kibi-mcp Constraints",
+            "",
+            "Apply these rules before calling write operations:",
+            "",
+            "## Validation Rules",
+            "- `kb_upsert` validates entity and relationship payloads against JSON Schema.",
+            "- `kb_delete` blocks deletion when dependents still reference the entity.",
+            "- Relationship and rule names are strict enums; unknown values fail validation.",
+            "- Branch KB setup is automatic at server startup; lifecycle maintenance stays outside the public MCP tool surface.",
+            "",
+            "## Telemetry-Driven Guardrails",
+            "- The server does not send external telemetry or analytics.",
+            "- All operations are local and branch-scoped.",
+            "- No network requests are made to external services.",
+            "- KB state persists only within the repository's `.kb/` directory.",
+        ].join("\n"),
+    },
+];
+function registerDocResources() {
+    const overview = [
+        "# kibi-mcp Server Overview",
+        "",
+        "kibi-mcp is a stdio MCP server for querying and mutating the Kibi knowledge base.",
+        "",
+        "Scope:",
+        "- Entity CRUD-like operations for KB records",
+        "- Validation of KB integrity after changes",
+        "- Automatic branch-local attachment for the active workspace",
+        "",
+        "Use this server when you need branch-local, machine-readable project memory.",
+    ].join("\n");
+    const errors = [
+        "# kibi-mcp Error Guide",
+        "",
+        "Common failure modes and recoveries:",
+        "",
+        "- `-32602 INVALID_PARAMS`: Tool arguments are missing/invalid. Recover by checking enum values and required fields.",
+        "- `-32601 METHOD_NOT_FOUND`: Unknown MCP method. Recover by using supported methods (`tools/*`, `prompts/*`, `resources/*`).",
+        "- `-32000 PROLOG_QUERY_FAILED`: Prolog query failed. Recover by validating IDs, rule names, and branch KB availability.",
+        "- `VALIDATION_ERROR` message: `kb_upsert` payload failed schema checks. Recover by fixing required fields and enum values.",
+        "- Delete blocked by dependents: `kb_delete` detected incoming references. Recover by removing/rewiring relationships first.",
+        "- Empty results: filters may be too strict. Recover by loosening type/id/tags/source filters and retrying.",
+    ].join("\n");
+    const examples = [
+        "# kibi-mcp Examples",
+        "",
+        "## Model requirements as reusable facts",
+        '1. `kb_query` with `{ "type": "fact" }` to find existing fact IDs before creating new ones',
+        "2. `kb_upsert` for the fact entity first (create-before-link)",
+        "3. `kb_upsert` for the req entity and include `relationships` with `constrains` and `requires_property`",
+        "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',
+        "",
+        "## Add a requirement and link it to a test",
+        '1. `kb_query` with `{ "type": "test" }` to check for existing test IDs',
+        '2. `kb_query` with `{ "id": "REQ-XXX" }` to verify the requirement exists',
+        "3. `kb_upsert` with entity payload and `relationships` containing `verified_by`",
+        '4. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }` for targeted validation',
+        "",
+        "Note: Always use query-first pattern. Specify only needed rules in kb_check for faster validation.",
+    ].join("\n");
+    return [
+        {
+            uri: "kibi://docs/overview",
+            name: "kibi docs overview",
+            description: "Full server description, purpose, and scope.",
+            mimeType: "text/markdown",
+            text: overview,
+        },
+        {
+            uri: "kibi://docs/tools",
+            name: "kibi docs tools",
+            description: "Available tools with summaries and required parameters.",
+            mimeType: "text/markdown",
+            text: renderToolsDoc(),
+        },
+        {
+            uri: "kibi://docs/errors",
+            name: "kibi docs errors",
+            description: "Common error modes and suggested recovery actions.",
+            mimeType: "text/markdown",
+            text: errors,
+        },
+        {
+            uri: "kibi://docs/examples",
+            name: "kibi docs examples",
+            description: "Concrete tool call sequences for common tasks.",
+            mimeType: "text/markdown",
+            text: examples,
+        },
+    ];
+}
+export const DOC_RESOURCES = registerDocResources();
+export function setupDocsAndPrompts(server) {
+    for (const prompt of PROMPTS) {
+        server.prompt(prompt.name, prompt.description, async () => ({
+            messages: [
+                {
+                    role: "user",
+                    content: { type: "text", text: prompt.text },
+                },
+            ],
+        }));
+    }
+    for (const resource of DOC_RESOURCES) {
+        server.resource(resource.name, resource.uri, { description: resource.description, mimeType: resource.mimeType }, async () => ({
+            contents: [
+                {
+                    uri: resource.uri,
+                    mimeType: resource.mimeType,
+                    text: resource.text,
+                },
+            ],
+        }));
+    }
+}

package/dist/server/session.js

@@ -0,0 +1,218 @@
+/*
+ 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 fs from "node:fs";
+import { createRequire } from "node:module";
+import process from "node:process";
+import { PrologProcess } from "kibi-cli/prolog";
+import { copyCleanSnapshot, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, } from "kibi-cli/public/branch-resolver";
+import { resolveKbPath, resolveWorkspaceRoot } from "../workspace.js";
+export let prologProcess = null;
+let isInitialized = false;
+export let activeBranchName = "develop";
+let ensurePrologTail = Promise.resolve();
+export let isShuttingDown = false;
+let shutdownTimeout = null;
+export const inFlightRequests = new Map();
+function debugLog(...args) {
+    if (process.env.KIBI_MCP_DEBUG) {
+        console.error(...args);
+    }
+}
+export function ensureBranchKbExists(workspaceRoot, branch) {
+    if (!isValidBranchName(branch)) {
+        throw new Error(`Invalid branch name: ${branch}`);
+    }
+    const branchPath = resolveKbPath(workspaceRoot, branch);
+    if (fs.existsSync(branchPath)) {
+        return;
+    }
+    // Try to copy from the previously active branch if available
+    const previousBranch = activeBranchName;
+    const previousBranchPath = resolveKbPath(workspaceRoot, previousBranch);
+    if (previousBranch !== branch &&
+        previousBranch !== "develop" &&
+        fs.existsSync(previousBranchPath)) {
+        // Copy from previous branch for continuity
+        copyCleanSnapshot(previousBranchPath, branchPath);
+        debugLog(`[KIBI-MCP] Created branch KB for '${branch}' from '${previousBranch}'`);
+        return;
+    }
+    // No previous branch available - create empty KB
+    fs.mkdirSync(branchPath, { recursive: true });
+    debugLog(`[KIBI-MCP] Created empty branch KB for '${branch}'`);
+}
+export async function initiateGracefulShutdown(exitCode = 0) {
+    if (isShuttingDown) {
+        return;
+    }
+    isShuttingDown = true;
+    debugLog(`[KIBI-MCP] Initiating graceful shutdown (exit code: ${exitCode})`);
+    // Wait for in-flight requests
+    if (inFlightRequests.size > 0) {
+        debugLog(`[KIBI-MCP] Waiting for ${inFlightRequests.size} in-flight requests to complete...`);
+        const timeoutPromise = new Promise((_, reject) => {
+            shutdownTimeout = setTimeout(() => {
+                reject(new Error("Shutdown timeout"));
+            }, 10000); // 10 second timeout
+        });
+        try {
+            await Promise.race([
+                Promise.allSettled(Array.from(inFlightRequests.values())),
+                timeoutPromise,
+            ]);
+            debugLog("[KIBI-MCP] All in-flight requests completed");
+        }
+        catch (_error) {
+            console.error("[KIBI-MCP] Shutdown timeout reached, forcing exit");
+        }
+        finally {
+            if (shutdownTimeout) {
+                clearTimeout(shutdownTimeout);
+                shutdownTimeout = null;
+            }
+        }
+    }
+    // Cleanup Prolog process
+    if (prologProcess?.isRunning()) {
+        debugLog("[KIBI-MCP] Terminating Prolog process...");
+        try {
+            await prologProcess.terminate();
+            debugLog("[KIBI-MCP] Prolog process terminated");
+        }
+        catch (error) {
+            console.error("[KIBI-MCP] Error terminating Prolog:", error);
+        }
+    }
+    // Exit
+    process.exit(exitCode);
+}
+async function ensurePrologUnsafe() {
+    const workspaceRoot = resolveWorkspaceRoot();
+    // Determine target branch: respect KIBI_BRANCH override or resolve from git
+    const envBranch = process.env.KIBI_BRANCH?.trim();
+    let targetBranch;
+    if (envBranch) {
+        // KIBI_BRANCH override is set - use it without re-resolving from git
+        if (!isValidBranchName(envBranch)) {
+            throw new Error(`Invalid branch name from KIBI_BRANCH: '${envBranch}'`);
+        }
+        targetBranch = envBranch;
+    }
+    else {
+        // No override - resolve active branch from git (may change between requests)
+        const branchResult = resolveActiveBranch(workspaceRoot);
+        if ("error" in branchResult) {
+            const diagnostic = getBranchDiagnostic(undefined, branchResult.error);
+            console.error(`[KIBI-MCP] ${diagnostic}`);
+            throw new Error(`Failed to resolve active branch: ${branchResult.error}`);
+        }
+        targetBranch = branchResult.branch;
+    }
+    // Check if we need to switch branches
+    if (isInitialized && prologProcess?.isRunning()) {
+        if (targetBranch === activeBranchName) {
+            // Still on the same branch - return existing connection
+            return prologProcess;
+        }
+        // Branch changed - need to detach and re-attach
+        debugLog(`[KIBI-MCP] Branch changed: ${activeBranchName} -> ${targetBranch}`);
+        // Detach from old KB
+        const detachResult = await prologProcess.query("kb_detach");
+        if (!detachResult.success) {
+            debugLog(`[KIBI-MCP] Warning: failed to detach from old KB: ${detachResult.error || "Unknown error"}`);
+            // Continue anyway - we'll try to attach to the new KB
+        }
+        // Ensure new branch KB exists
+        ensureBranchKbExists(workspaceRoot, targetBranch);
+        const newKbPath = resolveKbPath(workspaceRoot, targetBranch);
+        // Attach to new branch KB
+        const attachResult = await prologProcess.query(`kb_attach('${newKbPath}')`);
+        if (!attachResult.success) {
+            throw new Error(`Failed to attach to new branch KB: ${attachResult.error || "Unknown error"}`);
+        }
+        activeBranchName = targetBranch;
+        debugLog(`[KIBI-MCP] Re-attached to branch: ${targetBranch}`);
+        debugLog(`[KIBI-MCP] KB path: ${newKbPath}`);
+        return prologProcess;
+    }
+    // First initialization
+    debugLog("[KIBI-MCP] Initializing Prolog process...");
+    prologProcess = new PrologProcess({ timeout: 120000 });
+    await prologProcess.start();
+    // Startup debug: resolve which kibi-cli is being used and its version (best-effort).
+    // Gate all output under KIBI_MCP_DEBUG and write only to stderr via debugLog.
+    if (process.env.KIBI_MCP_DEBUG) {
+        try {
+            const req = createRequire(import.meta.url);
+            try {
+                const resolved = req.resolve("kibi-cli/prolog");
+                debugLog(`[KIBI-MCP] require.resolve('kibi-cli/prolog') -> ${resolved}`);
+            }
+            catch (resolveErr) {
+                debugLog("[KIBI-MCP] require.resolve('kibi-cli/prolog') failed:", resolveErr.message);
+            }
+            // Try to read package.json for kibi-cli to get version. This may fail if
+            // the package uses exports blocking package.json access — log explicit failure.
+            try {
+                // prefer direct package.json require; createRequire makes this ESM-friendly
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const pkg = req("kibi-cli/package.json");
+                if (pkg && typeof pkg.version === "string") {
+                    debugLog(`[KIBI-MCP] kibi-cli version: ${pkg.version}`);
+                }
+                else {
+                    debugLog("[KIBI-MCP] kibi-cli package.json read but no version field");
+                }
+            }
+            catch (pkgErr) {
+                debugLog("[KIBI-MCP] Failed to read kibi-cli package.json (exports may restrict access):", pkgErr.message);
+            }
+        }
+        catch (err) {
+            debugLog("[KIBI-MCP] Failed to create require() for debug lookup:", err.message);
+        }
+    }
+    debugLog("[KIBI-MCP] Branch selection:");
+    debugLog(`[KIBI-MCP]   KIBI_BRANCH env: ${process.env.KIBI_BRANCH || "not set"}`);
+    debugLog(`[KIBI-MCP]   Resolved branch: ${targetBranch}`);
+    activeBranchName = targetBranch;
+    ensureBranchKbExists(workspaceRoot, targetBranch);
+    const kbPath = resolveKbPath(workspaceRoot, targetBranch);
+    const attachResult = await prologProcess.query(`kb_attach('${kbPath}')`);
+    if (!attachResult.success) {
+        throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
+    }
+    isInitialized = true;
+    debugLog(`[KIBI-MCP] Prolog process started (PID: ${prologProcess.getPid()})`);
+    debugLog(`[KIBI-MCP] KB attached: ${kbPath}`);
+    return prologProcess;
+}
+export async function ensureProlog() {
+    const previous = ensurePrologTail;
+    let release;
+    ensurePrologTail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    try {
+        return await ensurePrologUnsafe();
+    }
+    finally {
+        release();
+    }
+}