kibi-mcp 0.2.3 → 0.3.0

package/dist/server.js

@@ -14,857 +14,24 @@
 
  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 path from "node:path";
-/*
- 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 process from "node:process";
+ */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { PrologProcess } from "kibi-cli/prolog";
-import { copyCleanSnapshot, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, } from "kibi-cli/public/branch-resolver";
-import { z } from "zod";
 import { loadDefaultEnvFile } from "./env.js";
-import { TOOLS } from "./tools-config.js";
-import { handleKbCheck } from "./tools/check.js";
-import { handleKbDelete } from "./tools/delete.js";
-import { handleKbQuery } from "./tools/query.js";
-import { handleKbUpsert } from "./tools/upsert.js";
-import { resolveKbPath, resolveWorkspaceRoot } from "./workspace.js";
-const DIAGNOSTIC_MODE_FLAG = "--diagnostic-mode";
-const DIAGNOSTIC_MODE_ENABLED = process.argv.includes(DIAGNOSTIC_MODE_FLAG);
-const DIAGNOSTIC_TELEMETRY_SCHEMA = {
-    type: "object",
-    description: "REQUIRED when diagnostic mode is on. Provide self-reflection metadata about this tool call.",
-    properties: {
-        is_autonomous: {
-            type: "boolean",
-            description: "Set to TRUE if you are calling this tool on your own initiative to retrieve context. Set to FALSE if the user explicitly commanded you to use the knowledge base.",
-        },
-        reasoning: {
-            type: "string",
-            description: "A brief, 1-2 sentence internal thought explaining exactly why you are calling this tool right now and what information you expect to get.",
-        },
-        confidence_score: {
-            type: "number",
-            description: "A score from 0.0 to 1.0 representing your confidence that the exact parameters, IDs, or tags you provided will yield a successful result.",
-        },
-        attempt_number: {
-            type: "integer",
-            description: "If you are retrying this exact task because a previous tool call failed or returned empty results, increment this number (start at 1).",
-        },
-        missing_context: {
-            type: "string",
-            description: "If you had to split your task into multiple steps because this tool lacks a specific filtering or querying capability, describe what parameter is missing. Otherwise, leave empty.",
-        },
-    },
-};
-function withDiagnosticTelemetrySchema(tools) {
-    return tools.map((tool) => {
-        const schema = tool.inputSchema && typeof tool.inputSchema === "object"
-            ? tool.inputSchema
-            : {};
-        const properties = schema.properties && typeof schema.properties === "object"
-            ? schema.properties
-            : {};
-        return {
-            ...tool,
-            inputSchema: {
-                ...schema,
-                properties: {
-                    ...properties,
-                    _diagnostic_telemetry: DIAGNOSTIC_TELEMETRY_SCHEMA,
-                },
-            },
-        };
-    });
-}
-const BASE_TOOLS = TOOLS;
-const ACTIVE_TOOLS = DIAGNOSTIC_MODE_ENABLED
-    ? withDiagnosticTelemetrySchema(BASE_TOOLS)
-    : BASE_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");
-}
-const PROMPTS = [
-    {
-        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.",
-            "",
-            "- 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. **Inspect**: Call `kb_query` to confirm current state before any mutation.",
-            "2. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property`.",
-            "3. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first.",
-            "4. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
-            "5. **Verify integrity**: Call `kb_check` after mutations.",
-            "",
-            "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:",
-            "",
-            "- `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.",
-        ].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` to find existing fact IDs before creating new ones",
-        "2. `kb_upsert` for the req entity and include `relationships` with `constrains` and `requires_property`",
-        "3. Reuse the same constrained fact ID across related requirements; vary property facts only when semantics differ",
-        '4. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }`',
-        "",
-        "## Add a requirement and link it to a test",
-        "1. `kb_query` for existing IDs to avoid collisions",
-        "2. `kb_upsert` with entity payload and `relationships` containing `verified_by`",
-        '3. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }`',
-    ].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,
-        },
-    ];
-}
-const DOC_RESOURCES = registerDocResources();
-function getHelpText(topic) {
-    const normalized = (topic ?? "overview").trim().toLowerCase();
-    if (normalized === "tools") {
-        return renderToolsDoc();
-    }
-    if (normalized === "workflow") {
-        return PROMPTS.find((p) => p.name === "kibi_workflow")?.text ?? "";
-    }
-    if (normalized === "constraints") {
-        return PROMPTS.find((p) => p.name === "kibi_constraints")?.text ?? "";
-    }
-    if (normalized === "examples") {
-        return (DOC_RESOURCES.find((r) => r.uri === "kibi://docs/examples")?.text ?? "");
-    }
-    if (normalized === "errors") {
-        return (DOC_RESOURCES.find((r) => r.uri === "kibi://docs/errors")?.text ?? "");
-    }
-    if (normalized === "branching") {
-        return [
-            "# Branch Selection",
-            "",
-            "Kibi is branch-aware. By default, the MCP server detects the current git branch and attaches to the corresponding KB in `.kb/branches/<branch>`.",
-            "",
-            "## Forcing a Branch",
-            "You can override the detected branch by setting the `KIBI_BRANCH` environment variable before starting the server.",
-            "",
-            "Example:",
-            "```bash",
-            "KIBI_BRANCH=feature/auth bun run packages/mcp/src/server.ts",
-            "```",
-            "",
-            "## How it works",
-            "1. If `KIBI_BRANCH` is set, it uses that value.",
-            "2. If not set, it runs `git branch --show-current`.",
-            "3. If git detection fails, it falls back to `develop`.",
-            "4. The server logs the selection process to stderr on startup.",
-        ].join("\n");
-    }
-    return (DOC_RESOURCES.find((r) => r.uri === "kibi://docs/overview")?.text ?? "");
-}
-let prologProcess = null;
-let isInitialized = false;
-let activeBranchName = "develop";
-let ensurePrologTail = Promise.resolve();
-// Shutdown tracking state
-let isShuttingDown = false;
-let shutdownTimeout = null;
-const inFlightRequests = new Map();
-let diagnosticUsageLogPath = null;
-function extractToolCallPayload(args) {
-    const { _diagnostic_telemetry, ...businessArgs } = args;
-    const telemetry = _diagnostic_telemetry && typeof _diagnostic_telemetry === "object"
-        ? _diagnostic_telemetry
-        : null;
-    return { businessArgs, telemetry };
-}
-function appendUsageLogLine(entry) {
-    if (!DIAGNOSTIC_MODE_ENABLED || !diagnosticUsageLogPath) {
-        return;
-    }
-    const logDir = path.dirname(diagnosticUsageLogPath);
-    fs.mkdirSync(logDir, { recursive: true });
-    fs.appendFileSync(diagnosticUsageLogPath, `${JSON.stringify(entry)}\n`, {
-        encoding: "utf8",
-    });
-}
-function extractContradictionSignal(tool, args, result) {
-    if (tool !== "kb_upsert") {
-        return undefined;
-    }
-    const id = typeof args.id === "string" ? args.id : undefined;
-    if (!id) {
-        return undefined;
-    }
-    const structured = result && typeof result === "object"
-        ? result
-            .structuredContent
-        : undefined;
-    if (!structured || typeof structured !== "object") {
-        return undefined;
-    }
-    const rawCount = structured.contradiction_pairs_detected;
-    const count = typeof rawCount === "number" ? rawCount : Number(rawCount);
-    if (!Number.isFinite(count) || count < 0) {
-        return undefined;
-    }
-    return {
-        attempted_entity_id: id,
-        contradiction_pairs_detected: count,
-    };
-}
-async function probeContradictionsForReq(reqId) {
-    if (!prologProcess?.isRunning()) {
-        return { count: null, error: "prolog_process_not_running" };
-    }
-    const escaped = reqId.replace(/'/g, "\\'");
-    const goal = `aggregate_all(count, (contradicting_reqs(A, B, _), (A = '${escaped}' ; B = '${escaped}' ; A = 'file:///${escaped}' ; B = 'file:///${escaped}')), Count)`;
-    const result = await prologProcess.query(goal);
-    if (!result.success) {
-        return { count: null, error: result.error ?? "probe_query_failed" };
-    }
-    const count = Number(result.bindings.Count);
-    if (!Number.isFinite(count) || count < 0) {
-        return { count: null, error: "invalid_probe_count" };
-    }
-    return { count };
-}
-function ensureBranchKbExists(workspaceRoot, branch) {
-    if (!isValidBranchName(branch)) {
-        throw new Error(`Invalid branch name: ${branch}`);
-    }
-    const branchPath = resolveKbPath(workspaceRoot, branch);
-    if (fs.existsSync(branchPath)) {
-        return;
-    }
-    const templateBranch = ["develop", "main"].find((candidate) => candidate !== branch &&
-        fs.existsSync(resolveKbPath(workspaceRoot, candidate)));
-    if (!templateBranch) {
-        throw new Error(`No template branch KB found for '${branch}'. Expected '.kb/branches/develop' or '.kb/branches/main'.`);
-    }
-    // Use clean snapshot copy that excludes volatile artifacts
-    copyCleanSnapshot(resolveKbPath(workspaceRoot, templateBranch), branchPath);
-}
-function debugLog(...args) {
-    if (process.env.KIBI_MCP_DEBUG) {
-        console.error(...args);
-    }
-}
-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;
-}
-async function ensureProlog() {
-    const previous = ensurePrologTail;
-    let release;
-    ensurePrologTail = new Promise((resolve) => {
-        release = resolve;
-    });
-    await previous;
-    try {
-        return await ensurePrologUnsafe();
-    }
-    finally {
-        release();
-    }
-}
-function jsonSchemaToZod(schema) {
-    if (!schema || typeof schema !== "object") {
-        return z.any();
-    }
-    const obj = schema;
-    if (Array.isArray(obj.enum) && obj.enum.length > 0) {
-        const description = typeof obj.description === "string" ? obj.description : undefined;
-        const literals = obj.enum.filter((value) => typeof value === "string" ||
-            typeof value === "number" ||
-            typeof value === "boolean" ||
-            value === null);
-        if (literals.length === 0) {
-            return description ? z.any().describe(description) : z.any();
-        }
-        const literalSchemas = literals.map((value) => z.literal(value));
-        if (literalSchemas.length === 1) {
-            const single = literalSchemas[0];
-            return description ? single.describe(description) : single;
-        }
-        const union = z.union(literalSchemas);
-        return description ? union.describe(description) : union;
-    }
-    const schemaType = typeof obj.type === "string" ? obj.type : undefined;
-    switch (schemaType) {
-        case "object": {
-            const properties = obj.properties && typeof obj.properties === "object"
-                ? obj.properties
-                : {};
-            const required = new Set(Array.isArray(obj.required)
-                ? obj.required.filter((k) => typeof k === "string" && k.length > 0)
-                : []);
-            const shape = {};
-            for (const [key, value] of Object.entries(properties)) {
-                const propSchema = jsonSchemaToZod(value);
-                shape[key] = required.has(key) ? propSchema : propSchema.optional();
-            }
-            let objectSchema = z.object(shape);
-            if (obj.additionalProperties !== false) {
-                objectSchema = objectSchema.passthrough();
-            }
-            const description = typeof obj.description === "string" ? obj.description : undefined;
-            return description ? objectSchema.describe(description) : objectSchema;
-        }
-        case "array": {
-            const itemSchema = jsonSchemaToZod(obj.items);
-            let arraySchema = z.array(itemSchema);
-            const description = typeof obj.description === "string" ? obj.description : undefined;
-            if (typeof obj.minItems === "number") {
-                arraySchema = arraySchema.min(obj.minItems);
-            }
-            if (typeof obj.maxItems === "number") {
-                arraySchema = arraySchema.max(obj.maxItems);
-            }
-            return description ? arraySchema.describe(description) : arraySchema;
-        }
-        case "string": {
-            let s = z.string();
-            const description = typeof obj.description === "string" ? obj.description : undefined;
-            if (typeof obj.minLength === "number") {
-                s = s.min(obj.minLength);
-            }
-            if (typeof obj.maxLength === "number") {
-                s = s.max(obj.maxLength);
-            }
-            return description ? s.describe(description) : s;
-        }
-        case "number": {
-            let n = z.number();
-            const description = typeof obj.description === "string" ? obj.description : undefined;
-            if (typeof obj.minimum === "number") {
-                n = n.min(obj.minimum);
-            }
-            if (typeof obj.maximum === "number") {
-                n = n.max(obj.maximum);
-            }
-            return description ? n.describe(description) : n;
-        }
-        case "integer": {
-            let n = z.number().int();
-            const description = typeof obj.description === "string" ? obj.description : undefined;
-            if (typeof obj.minimum === "number") {
-                n = n.min(obj.minimum);
-            }
-            if (typeof obj.maximum === "number") {
-                n = n.max(obj.maximum);
-            }
-            return description ? n.describe(description) : n;
-        }
-        case "boolean": {
-            const b = z.boolean();
-            const description = typeof obj.description === "string" ? obj.description : undefined;
-            return description ? b.describe(description) : b;
-        }
-        default: {
-            const anySchema = z.any();
-            const description = typeof obj.description === "string" ? obj.description : undefined;
-            return description ? anySchema.describe(description) : anySchema;
-        }
-    }
-}
-function addTool(server, name, description, inputSchema, handler) {
-    const wrappedHandler = async (args) => {
-        let telemetry = null;
-        let businessArgs = {};
-        const startedAt = new Date();
-        try {
-            // Validate that args is a valid object
-            if (typeof args !== "object" || args === null) {
-                throw new Error(`Invalid arguments for tool ${name}: expected object, got ${typeof args}`);
-            }
-            if (DIAGNOSTIC_MODE_ENABLED) {
-                const payload = extractToolCallPayload(args);
-                telemetry = payload.telemetry;
-                businessArgs = payload.businessArgs;
-            }
-            else {
-                businessArgs = args;
-            }
-            // Check if shutting down before processing
-            if (isShuttingDown) {
-                throw new Error(`Tool ${name} rejected: server is shutting down`);
-            }
-            // Extract or generate requestId from args
-            const requestIdArg = businessArgs._requestId;
-            const requestId = typeof requestIdArg === "string"
-                ? requestIdArg
-                : `${name}-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
-            // Log tool call for debugging (to stderr to avoid breaking stdio protocol)
-            if (process.env.KIBI_MCP_DEBUG) {
-                console.error(`[KIBI-MCP] Tool called: ${name} (requestId: ${requestId}) with args:`, JSON.stringify(businessArgs));
-            }
-            // Track the handler promise in inFlightRequests Map
-            const handlerPromise = handler(businessArgs);
-            inFlightRequests.set(requestId, handlerPromise);
-            try {
-                // Execute handler
-                const result = await handlerPromise;
-                const finishedAt = new Date();
-                const contradictionSignal = extractContradictionSignal(name, businessArgs, result);
-                let contradictionSignalFinal = contradictionSignal;
-                if (name === "kb_upsert" && typeof businessArgs.id === "string") {
-                    const probe = businessArgs.type === "req"
-                        ? await probeContradictionsForReq(businessArgs.id)
-                        : { count: null, error: "non_req_entity" };
-                    contradictionSignalFinal = {
-                        attempted_entity_id: businessArgs.id,
-                        contradiction_pairs_detected: probe.count !== null ? probe.count : -1,
-                        probe_error: probe.error,
-                    };
-                }
-                appendUsageLogLine({
-                    timestamp: finishedAt.toISOString(),
-                    request_id: requestId,
-                    tool: name,
-                    telemetry,
-                    business_args: businessArgs,
-                    status: "success",
-                    started_at: startedAt.toISOString(),
-                    finished_at: finishedAt.toISOString(),
-                    duration_ms: finishedAt.getTime() - startedAt.getTime(),
-                    prolog_pid: prologProcess?.getPid() ?? null,
-                    active_branch: activeBranchName,
-                    contradiction_signal: contradictionSignalFinal,
-                });
-                return result;
-            }
-            catch (error) {
-                const finishedAt = new Date();
-                const err = error instanceof Error ? error : new Error(String(error));
-                appendUsageLogLine({
-                    timestamp: finishedAt.toISOString(),
-                    request_id: requestId,
-                    tool: name,
-                    telemetry,
-                    business_args: businessArgs,
-                    status: "error",
-                    started_at: startedAt.toISOString(),
-                    finished_at: finishedAt.toISOString(),
-                    duration_ms: finishedAt.getTime() - startedAt.getTime(),
-                    prolog_pid: prologProcess?.getPid() ?? null,
-                    active_branch: activeBranchName,
-                    error_message: err.message,
-                });
-                throw error;
-            }
-            finally {
-                // Always clean up from Map when done (success or failure)
-                inFlightRequests.delete(requestId);
-            }
-        }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error(String(error));
-            console.error(`[KIBI-MCP] Error in tool ${name}:`, err.message);
-            if (err.stack) {
-                debugLog(`[KIBI-MCP] Tool ${name} stack:`, err.stack);
-            }
-            throw new Error(`Tool ${name} failed: ${err.message}`, { cause: err });
-        }
-    };
-    server.registerTool(name, { description, inputSchema: jsonSchemaToZod(inputSchema) }, wrappedHandler);
-}
+import { setupDocsAndPrompts } from "./server/docs.js";
+import { registerAllTools } from "./server/tools.js";
+import { connectTransport, setupTransportHandlers, } from "./server/transport.js";
 export async function startServer() {
+    // Load environment configuration
     loadDefaultEnvFile();
-    if (DIAGNOSTIC_MODE_ENABLED) {
-        const workspaceRoot = resolveWorkspaceRoot();
-        diagnosticUsageLogPath = path.join(workspaceRoot, ".kb", "usage.log");
-        process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
-    }
+    // Create MCP server
     const server = new McpServer({ name: "kibi-mcp", version: "0.2.1" });
-    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,
-                },
-            ],
-        }));
-    }
-    const toolDef = (name) => {
-        const t = ACTIVE_TOOLS.find((t) => t.name === name);
-        if (!t)
-            throw new Error(`Unknown tool: ${name}`);
-        return t;
-    };
-    addTool(server, "kb_query", toolDef("kb_query").description, toolDef("kb_query").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbQuery(prolog, args);
-    });
-    addTool(server, "kb_upsert", toolDef("kb_upsert").description, toolDef("kb_upsert").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbUpsert(prolog, args);
-    });
-    addTool(server, "kb_delete", toolDef("kb_delete").description, toolDef("kb_delete").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbDelete(prolog, args);
-    });
-    addTool(server, "kb_check", toolDef("kb_check").description, toolDef("kb_check").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbCheck(prolog, args);
-    });
+    // Setup documentation resources and prompts
+    setupDocsAndPrompts(server);
+    // Register all KB tools
+    registerAllTools(server);
+    // Setup transport and connect
     const transport = new StdioServerTransport();
-    transport.onerror = (error) => {
-        // Stdio transport surfaces JSON parse / schema validation failures via onerror.
-        // Those errors should not crash the server: emit a JSON-RPC error (id omitted)
-        // and continue reading subsequent messages.
-        if (error.name === "SyntaxError") {
-            debugLog("[KIBI-MCP] Parse error from stdin:", error.message);
-            void transport
-                .send({
-                jsonrpc: "2.0",
-                error: { code: -32700, message: "Parse error" },
-            })
-                .catch((sendError) => {
-                console.error("[KIBI-MCP] Failed to send parse error response:", sendError);
-                initiateGracefulShutdown(1);
-            });
-            return;
-        }
-        if (error.name === "ZodError") {
-            debugLog("[KIBI-MCP] Invalid JSON-RPC message:", error.message);
-            void transport
-                .send({
-                jsonrpc: "2.0",
-                error: { code: -32600, message: "Invalid Request" },
-            })
-                .catch((sendError) => {
-                console.error("[KIBI-MCP] Failed to send invalid request response:", sendError);
-                initiateGracefulShutdown(1);
-            });
-            return;
-        }
-        console.error(`[KIBI-MCP] Transport error: ${error.message}`, error);
-        debugLog("[KIBI-MCP] Transport error stack:", error.stack);
-        initiateGracefulShutdown(1);
-    };
-    transport.onclose = () => {
-        debugLog("[KIBI-MCP] Transport closed");
-        initiateGracefulShutdown(0);
-    };
-    await server.connect(transport);
-    process.stdout.on("error", (error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        console.error("[KIBI-MCP] stdout error:", message);
-        debugLog("[KIBI-MCP] stdout error detail:", error);
-        initiateGracefulShutdown(1);
-    });
-    process.stderr.on("error", (error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        try {
-            console.error("[KIBI-MCP] stderr error:", message);
-        }
-        catch { }
-        initiateGracefulShutdown(1);
-    });
-    process.on("SIGTERM", () => {
-        debugLog("[KIBI-MCP] Received SIGTERM");
-        initiateGracefulShutdown(0);
-    });
-    process.on("SIGINT", () => {
-        debugLog("[KIBI-MCP] Received SIGINT");
-        initiateGracefulShutdown(0);
-    });
-    // Handle stdin EOF/close for clean shutdown when client disconnects
-    // Use debugLog so these are only noisy when KIBI_MCP_DEBUG is set.
-    try {
-        process.stdin.on("end", () => {
-            debugLog("[KIBI-MCP] stdin ended");
-            // fire-and-forget; initiateGracefulShutdown is idempotent
-            void initiateGracefulShutdown(0);
-        });
-        process.stdin.on("close", () => {
-            debugLog("[KIBI-MCP] stdin closed");
-            void initiateGracefulShutdown(0);
-        });
-    }
-    catch (e) {
-        // Defensive: do not let stdin handler setup throw during startup
-        debugLog("[KIBI-MCP] Failed to attach stdin handlers:", e);
-    }
+    setupTransportHandlers(server, transport);
+    await connectTransport(server, transport);
 }