kibi-mcp 0.1.0

package/dist/tools-config.js

@@ -0,0 +1,448 @@
+/*
+ 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/>.
+*/
+/*
+ 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
+*/
+export const TOOLS = [
+    {
+        name: "kb_query",
+        description: "Read entities from the KB with filters. Use for discovery and lookup before edits. Do not use for writes. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                type: {
+                    type: "string",
+                    enum: [
+                        "req",
+                        "scenario",
+                        "test",
+                        "adr",
+                        "flag",
+                        "event",
+                        "symbol",
+                        "fact",
+                    ],
+                    description: "Optional entity type filter. Allowed: req, scenario, test, adr, flag, event, symbol, fact. Example: 'req'.",
+                },
+                id: {
+                    type: "string",
+                    description: "Optional exact entity ID. Example: 'REQ-001'. If omitted, returns matching entities by other filters.",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional tag filter. Matches entities that contain any provided tag. Example: ['security','billing'].",
+                },
+                sourceFile: {
+                    type: "string",
+                    description: "Optional source-file substring filter. Example: 'src/auth/login.ts'. Uses KB source linkage, not file-system scanning.",
+                },
+                limit: {
+                    type: "number",
+                    default: 100,
+                    description: "Optional max rows to return after filtering. Default: 100 when omitted. Example: 25.",
+                },
+                offset: {
+                    type: "number",
+                    default: 0,
+                    description: "Optional zero-based pagination offset. Default: 0. Example: 50 to skip first 50 rows.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_upsert",
+        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`) so consistency and contradiction checks remain queryable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
+        inputSchema: {
+            type: "object",
+            required: ["type", "id", "properties"],
+            properties: {
+                type: {
+                    type: "string",
+                    enum: [
+                        "req",
+                        "scenario",
+                        "test",
+                        "adr",
+                        "flag",
+                        "event",
+                        "symbol",
+                        "fact",
+                    ],
+                    description: "Entity type to create/update. Allowed: req, scenario, test, adr, flag, event, symbol, fact. Example: 'req'.",
+                },
+                id: {
+                    type: "string",
+                    description: "Unique entity ID (string). Example: 'REQ-123'. Existing ID updates the entity; new ID creates it.",
+                },
+                properties: {
+                    type: "object",
+                    description: "Entity fields to persist. Must include title and status. If created_at, updated_at, or source are omitted, server fills defaults.",
+                    properties: {
+                        title: {
+                            type: "string",
+                            description: "Required short title. Example: 'Protect account settings endpoint'.",
+                        },
+                        status: {
+                            type: "string",
+                            enum: [
+                                "active",
+                                "draft",
+                                "archived",
+                                "deleted",
+                                "approved",
+                                "rejected",
+                                "pending",
+                                "in_progress",
+                                "superseded",
+                            ],
+                            description: "Required lifecycle state. Allowed values are fixed enum options. Example: 'active'.",
+                        },
+                        source: {
+                            type: "string",
+                            description: "Optional provenance string. Example: 'docs/requirements/REQ-123.md'. Defaults to 'mcp://kibi/upsert'.",
+                        },
+                        tags: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional categorization tags. Example: ['security','api'].",
+                        },
+                        owner: {
+                            type: "string",
+                            description: "Optional owner name/team. Example: 'platform-team'.",
+                        },
+                        priority: {
+                            type: "string",
+                            description: "Optional priority label. Example: 'high'.",
+                        },
+                        severity: {
+                            type: "string",
+                            description: "Optional severity label. Example: 'critical'.",
+                        },
+                        links: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional references. Example: ['REQ-010','https://example.com/spec'].",
+                        },
+                        text_ref: {
+                            type: "string",
+                            description: "Optional text anchor/reference. Example: 'requirements.md#L40'.",
+                        },
+                    },
+                    required: ["title", "status"],
+                },
+                relationships: {
+                    type: "array",
+                    description: "Optional relationship rows to create in the same call. For requirement encoding, prefer `constrains` + `requires_property` edges from req IDs to shared fact IDs to maximize reuse and detect conflicts. Side effect: asserts edges in KB.",
+                    items: {
+                        type: "object",
+                        required: ["type", "from", "to"],
+                        properties: {
+                            type: {
+                                type: "string",
+                                enum: [
+                                    "depends_on",
+                                    "specified_by",
+                                    "verified_by",
+                                    "validates",
+                                    "implements",
+                                    "covered_by",
+                                    "constrained_by",
+                                    "constrains",
+                                    "requires_property",
+                                    "guards",
+                                    "publishes",
+                                    "consumes",
+                                    "supersedes",
+                                    "relates_to",
+                                ],
+                                description: "Relationship type enum. Use only supported values. Direction semantics follow KB model (e.g., implements symbol->req, verified_by req->test).",
+                            },
+                            from: {
+                                type: "string",
+                                description: "Source entity ID (must exist). Example: 'SYM-login-handler'.",
+                            },
+                            to: {
+                                type: "string",
+                                description: "Target entity ID (must exist). Example: 'REQ-001'.",
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+    {
+        name: "kb_delete",
+        description: "Delete entities by ID. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. Side effects: mutates and saves KB; skips entities with dependents.",
+        inputSchema: {
+            type: "object",
+            required: ["ids"],
+            properties: {
+                ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Required list of entity IDs to delete. Example: ['REQ-001','TEST-002']. At least one ID is required.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_check",
+        description: "Run KB validation rules and return violations. Use before or after mutations. Do not use for point lookups. No write side effects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                rules: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional rule subset. Allowed: must-priority-coverage, no-dangling-refs, no-cycles, required-fields, symbol-coverage. If omitted, server runs all.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_branch_ensure",
+        description: "Ensure a branch KB exists, creating it from develop when missing. Use when targeting non-develop branches. Do not use to switch git branches. Side effects: creates .kb/branches/<branch>.",
+        inputSchema: {
+            type: "object",
+            required: ["branch"],
+            properties: {
+                branch: {
+                    type: "string",
+                    description: "Required git branch name. Example: 'feature/auth-hardening'. Path traversal patterns are rejected.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_branch_gc",
+        description: "Find or delete stale branch KB directories not present in git. Use for repository hygiene. Do not use if you need historical branch KBs. Side effects: can delete branch KB folders when dry_run is false.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                dry_run: {
+                    type: "boolean",
+                    default: true,
+                    description: "Optional safety flag. true = report only; false = delete stale branch KBs. Default: true.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_query_relationships",
+        description: "Read relationship edges with optional from/to/type filters. Use for traceability traversal. Do not use to create links. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                from: {
+                    type: "string",
+                    description: "Optional source entity ID filter. Example: 'REQ-001'.",
+                },
+                to: {
+                    type: "string",
+                    description: "Optional target entity ID filter. Example: 'TEST-010'.",
+                },
+                type: {
+                    type: "string",
+                    enum: [
+                        "depends_on",
+                        "specified_by",
+                        "verified_by",
+                        "validates",
+                        "implements",
+                        "covered_by",
+                        "constrained_by",
+                        "constrains",
+                        "requires_property",
+                        "guards",
+                        "publishes",
+                        "consumes",
+                        "supersedes",
+                        "relates_to",
+                    ],
+                    description: "Optional relationship type filter. Allowed enum values only. Example: 'implements'.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_derive",
+        description: "Run deterministic inference predicates and return rows. Use for impact, coverage, and consistency analysis. Do not use for entity CRUD. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            required: ["rule"],
+            properties: {
+                rule: {
+                    type: "string",
+                    enum: [
+                        "transitively_implements",
+                        "transitively_depends",
+                        "impacted_by_change",
+                        "affected_symbols",
+                        "coverage_gap",
+                        "untested_symbols",
+                        "stale",
+                        "orphaned",
+                        "conflicting",
+                        "deprecated_still_used",
+                        "current_adr",
+                        "adr_chain",
+                        "superseded_by",
+                        "domain_contradictions",
+                    ],
+                    description: "Required inference rule name. Allowed values are the enum options. Example: 'coverage_gap'.",
+                },
+                params: {
+                    type: "object",
+                    description: "Optional rule-specific parameters. Example: { changed: 'REQ-001' } for impacted_by_change.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_impact",
+        description: "Return entities impacted by a changed entity ID. Use for quick change blast radius checks. Do not use for general querying. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            required: ["entity"],
+            properties: {
+                entity: {
+                    type: "string",
+                    description: "Required changed entity ID. Example: 'REQ-001'.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_coverage_report",
+        description: "Compute aggregate traceability coverage for requirements and/or symbols. Use for health snapshots. Do not use for raw entity dumps. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                type: {
+                    type: "string",
+                    enum: ["req", "symbol"],
+                    description: "Optional focus scope: 'req' or 'symbol'. Omit to include both.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_symbols_refresh",
+        description: "Refresh generated symbol coordinates in the symbols manifest. Use after refactors that move symbols. Do not use for semantic edits. Side effects: may rewrite symbols.yaml unless dryRun is true.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                dryRun: {
+                    type: "boolean",
+                    default: false,
+                    description: "Optional preview mode. true = report only, false = apply file updates. Default: false.",
+                },
+            },
+        },
+    },
+    {
+        name: "kb_list_entity_types",
+        description: "List supported entity type names. Use when building valid tool arguments. Do not use for entity data retrieval. No mutation side effects.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "kb_list_relationship_types",
+        description: "List supported relationship type names. Use before asserting or filtering relationships. Do not use for graph traversal. No mutation side effects.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "kbcontext",
+        description: "Return KB entities linked to a source file plus first-hop relationships. Use for file-centric traceability. Do not use for cross-repo search. No mutation side effects.",
+        inputSchema: {
+            type: "object",
+            required: ["sourceFile"],
+            properties: {
+                sourceFile: {
+                    type: "string",
+                    description: "Required source path substring. Example: 'src/auth/login.ts'.",
+                },
+                branch: {
+                    type: "string",
+                    description: "Optional branch hint for clients. Must match the server's active branch or will return an error.",
+                },
+            },
+        },
+    },
+    {
+        name: "get_help",
+        description: "Returns documentation for this MCP server. Call this first if you are unsure how to proceed or which tool to use. Available topics: overview, tools, workflow, constraints, examples, errors.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                topic: {
+                    type: "string",
+                    enum: [
+                        "overview",
+                        "tools",
+                        "workflow",
+                        "constraints",
+                        "examples",
+                        "errors",
+                        "branching",
+                    ],
+                    description: "Optional documentation section. Omit to return overview. Example: 'workflow'.",
+                },
+            },
+        },
+    },
+    {
+        name: "analyze_shared_facts",
+        description: "Analyze requirements and suggest shared domain facts for extraction. LLMs call this to identify missed semantic opportunities before upserting. Lightweight heuristic: finds overlapping capitalized terms and repeated phrases across requirements.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                min_frequency: {
+                    type: "number",
+                    default: 2,
+                    description: "Minimum frequency threshold for shared concepts. Default: 2. Example: 3 to only show concepts mentioned in 3+ requirements.",
+                },
+            },
+        },
+    },
+];

package/dist/workspace.js

@@ -0,0 +1,126 @@
+/*
+ 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/>.
+*/
+/*
+ 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 path from "node:path";
+const WORKSPACE_ENV_KEYS = [
+    "KIBI_WORKSPACE",
+    "KIBI_PROJECT_ROOT",
+    "KIBI_ROOT",
+];
+const KB_PATH_ENV_KEYS = ["KIBI_KB_PATH", "KB_PATH"];
+export function resolveWorkspaceRoot(startDir = process.cwd()) {
+    const envRoot = readFirstEnv(WORKSPACE_ENV_KEYS);
+    if (envRoot) {
+        return path.resolve(envRoot);
+    }
+    const kbRoot = findUpwards(startDir, ".kb");
+    if (kbRoot) {
+        return kbRoot;
+    }
+    const gitRoot = findUpwards(startDir, ".git");
+    if (gitRoot) {
+        return gitRoot;
+    }
+    return path.resolve(startDir);
+}
+export function resolveWorkspaceRootInfo(startDir = process.cwd()) {
+    const envRoot = readFirstEnv(WORKSPACE_ENV_KEYS);
+    if (envRoot) {
+        return { root: path.resolve(envRoot), reason: "env" };
+    }
+    const kbRoot = findUpwards(startDir, ".kb");
+    if (kbRoot) {
+        return { root: kbRoot, reason: "kb" };
+    }
+    const gitRoot = findUpwards(startDir, ".git");
+    if (gitRoot) {
+        return { root: gitRoot, reason: "git" };
+    }
+    return { root: path.resolve(startDir), reason: "cwd" };
+}
+export function resolveKbPath(workspaceRoot, branch) {
+    const envPath = readFirstEnv(KB_PATH_ENV_KEYS);
+    if (envPath) {
+        const resolved = path.resolve(envPath);
+        if (isBranchPath(resolved)) {
+            return resolved;
+        }
+        return path.join(resolved, "branches", branch);
+    }
+    return path.join(workspaceRoot, ".kb", "branches", branch);
+}
+export function resolveEnvFilePath(envFileName, workspaceRoot) {
+    if (path.isAbsolute(envFileName)) {
+        return envFileName;
+    }
+    return path.resolve(workspaceRoot, envFileName);
+}
+function readFirstEnv(keys) {
+    for (const key of keys) {
+        const value = process.env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+function findUpwards(startDir, marker) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(current, marker);
+        if (fs.existsSync(candidate)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function isBranchPath(p) {
+    const parent = path.basename(path.dirname(p));
+    return parent === "branches";
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "kibi-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Model Context Protocol server for Kibi knowledge base",
+  "main": "./dist/server.js",
+  "bin": {
+    "kibi-mcp": "./bin/kibi-mcp"
+  },
+  "scripts": {
+    "test": "bun test",
+    "dev": "bun run bin/kibi-mcp",
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "files": ["dist", "bin"],
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "exports": {
+    ".": "./dist/server.js",
+    "./src/*": "./src/*.ts"
+  },
+  "dependencies": {
+    "kibi-cli": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "ajv": "^8.18.0",
+    "js-yaml": "^4.1.0",
+    "mcpcat": "^0.1.12",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "latest"
+  },
+  "license": "AGPL-3.0-or-later",
+  "author": "Piotr Franczyk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Looted/kibi.git"
+  }
+}