knowledge-mcp-server 1.0.0

package/dist/loader.js

@@ -0,0 +1,151 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { log } from "./logger.js";
+function parseFrontmatter(raw) {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!match) {
+        return { frontmatter: {}, body: raw };
+    }
+    try {
+        const frontmatter = parseYaml(match[1]);
+        const body = match[2].trim();
+        return { frontmatter, body };
+    }
+    catch {
+        return { frontmatter: {}, body: raw };
+    }
+}
+export const VALID_TYPES = ["summary", "detail", "decision", "reference"];
+export function deriveParentId(id) {
+    if (id === "root")
+        return null;
+    const segments = id.split("/");
+    if (segments.length <= 1)
+        return "root";
+    return segments.slice(0, -1).join("/");
+}
+export function collectMarkdownFiles(dir) {
+    const files = [];
+    const entries = readdirSync(dir);
+    for (const entry of entries) {
+        if (entry.startsWith("."))
+            continue;
+        const fullPath = join(dir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+            files.push(...collectMarkdownFiles(fullPath));
+        }
+        else if (entry.endsWith(".md")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+const ID_PATTERN = /^[a-z][a-z0-9-]*(\/[a-z][a-z0-9-]*)*$/;
+function validateFrontmatter(fm, filePath, validDomains) {
+    const warnings = [];
+    if (!fm.id) {
+        warnings.push(`${filePath}: missing required field 'id'`);
+        return warnings; // Can't validate further without ID
+    }
+    if (!ID_PATTERN.test(fm.id)) {
+        warnings.push(`${filePath}: invalid ID format "${fm.id}"`);
+    }
+    if (fm.domain && validDomains && !validDomains.includes(fm.domain)) {
+        warnings.push(`${filePath}: invalid domain "${fm.domain}"`);
+    }
+    if (fm.type && !VALID_TYPES.includes(fm.type)) {
+        warnings.push(`${filePath}: invalid type "${fm.type}"`);
+    }
+    const phases = fm.phase ? (Array.isArray(fm.phase) ? fm.phase : [fm.phase]) : [];
+    for (const p of phases) {
+        if (p < 1 || !Number.isInteger(p)) {
+            warnings.push(`${filePath}: invalid phase value ${p}`);
+        }
+    }
+    if (fm.type === "decision" && !fm.decision_status) {
+        warnings.push(`${filePath}: decision document missing 'decision_status' field`);
+    }
+    return warnings;
+}
+export function loadDocuments(knowledgeDir, validDomains) {
+    const docs = new Map();
+    const files = collectMarkdownFiles(knowledgeDir);
+    const childrenFromFrontmatter = new Map();
+    for (const filePath of files) {
+        const raw = readFileSync(filePath, "utf-8");
+        const { frontmatter, body } = parseFrontmatter(raw);
+        // Validate schema
+        const validationWarnings = validateFrontmatter(frontmatter, filePath, validDomains);
+        if (validationWarnings.length > 0) {
+            for (const w of validationWarnings)
+                log.warn("schema_validation", { warning: w });
+        }
+        if (!frontmatter.id)
+            continue;
+        const id = frontmatter.id;
+        // Check for duplicate IDs
+        if (docs.has(id)) {
+            log.warn("duplicate_id", { id, file: filePath, existingFile: docs.get(id).filePath });
+        }
+        const phase = frontmatter.phase
+            ? Array.isArray(frontmatter.phase)
+                ? frontmatter.phase
+                : [frontmatter.phase]
+            : [];
+        if (frontmatter.children) {
+            childrenFromFrontmatter.set(id, frontmatter.children);
+        }
+        // Parse status: support both "status" and legacy "decision_status" fields
+        const rawStatus = frontmatter.status ||
+            (frontmatter.decision_status === "deprecated" ? "deprecated" : undefined);
+        const status = rawStatus === "draft" ? "draft" : rawStatus === "deprecated" ? "deprecated" : "active";
+        // Parse decision_status into typed enum value
+        const rawDecisionStatus = frontmatter.decision_status;
+        const validDecisionStatuses = ["proposed", "accepted", "deprecated", "superseded", "finalized"];
+        const decisionStatus = rawDecisionStatus && validDecisionStatuses.includes(rawDecisionStatus)
+            ? rawDecisionStatus
+            : undefined;
+        const doc = {
+            id,
+            title: frontmatter.title || id,
+            type: frontmatter.type || "detail",
+            domain: frontmatter.domain || id.split("/")[0],
+            subdomain: frontmatter.subdomain,
+            tags: frontmatter.tags || [],
+            phase,
+            related: frontmatter.related || [],
+            parentId: deriveParentId(id),
+            childrenIds: [],
+            contentBody: body,
+            filePath: relative(join(knowledgeDir, ".."), filePath),
+            wordCount: frontmatter.word_count || body.split(/\s+/).filter(Boolean).length,
+            status,
+            supersededBy: frontmatter.superseded_by,
+            lastUpdated: frontmatter.last_updated,
+            decisionStatus,
+            alternativesConsidered: frontmatter.alternatives_considered,
+            decisionDate: frontmatter.decision_date,
+        };
+        docs.set(id, doc);
+    }
+    // Populate childrenIds from frontmatter `children` fields
+    for (const [parentId, children] of childrenFromFrontmatter) {
+        const parent = docs.get(parentId);
+        if (parent) {
+            parent.childrenIds = children.filter((c) => docs.has(c));
+        }
+    }
+    // For docs without explicit children, derive from parentId
+    for (const doc of docs.values()) {
+        if (doc.parentId && docs.has(doc.parentId)) {
+            const parent = docs.get(doc.parentId);
+            if (!parent.childrenIds.includes(doc.id)) {
+                parent.childrenIds.push(doc.id);
+            }
+        }
+    }
+    return docs;
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"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"}

package/dist/logger.d.ts

@@ -0,0 +1,6 @@
+export declare const log: {
+    debug: (event: string, data?: Record<string, unknown>) => void;
+    info: (event: string, data?: Record<string, unknown>) => void;
+    warn: (event: string, data?: Record<string, unknown>) => void;
+    error: (event: string, data?: Record<string, unknown>) => void;
+};

package/dist/logger.js

@@ -0,0 +1,15 @@
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+const currentLevel = process.env.LOG_LEVEL in LEVELS ? process.env.LOG_LEVEL : "info";
+function emit(level, event, data) {
+    if (LEVELS[level] < LEVELS[currentLevel])
+        return;
+    const entry = { ts: new Date().toISOString(), level, event, ...data };
+    process.stderr.write(JSON.stringify(entry) + "\n");
+}
+export const log = {
+    debug: (event, data) => emit("debug", event, data),
+    info: (event, data) => emit("info", event, data),
+    warn: (event, data) => emit("warn", event, data),
+    error: (event, data) => emit("error", event, data),
+};
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAW,CAAC;AAGjE,MAAM,YAAY,GACf,OAAO,CAAC,GAAG,CAAC,SAAmB,IAAI,MAAM,CAAC,CAAC,CAAE,OAAO,CAAC,GAAG,CAAC,SAAmB,CAAC,CAAC,CAAC,MAAM,CAAC;AAEzF,SAAS,IAAI,CAAC,KAAY,EAAE,KAAa,EAAE,IAA8B;IACvE,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC;QAAE,OAAO;IACjD,MAAM,KAAK,GAAG,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,CAAC;IACtE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,KAAK,EAAE,CAAC,KAAa,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC;IACpF,IAAI,EAAE,CAAC,KAAa,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC;IAClF,IAAI,EAAE,CAAC,KAAa,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC;IAClF,KAAK,EAAE,CAAC,KAAa,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC;CACrF,CAAC"}

package/dist/query-classifier.d.ts

@@ -0,0 +1,23 @@
+import type { KnowledgeConfig } from "./config.js";
+export interface QueryClassification {
+    domains: string[];
+    phases: number[];
+    queryType: "broad" | "specific" | "decision";
+}
+export interface ClassifierConfig {
+    domainKeywords: Record<string, string[]>;
+    phasePatterns: Array<{
+        pattern: RegExp;
+        phase: number;
+        dynamic?: boolean;
+    }>;
+    synonymMap: Record<string, string[]>;
+}
+/**
+ * Build a ClassifierConfig from a KnowledgeConfig.
+ * When config is null (zero-config mode), returns empty config —
+ * search still works via BM25 + embeddings, just without domain pre-filtering.
+ */
+export declare function buildClassifierConfig(config: KnowledgeConfig | null): ClassifierConfig;
+export declare function expandSynonyms(query: string, synonymMap: Record<string, string[]>): string;
+export declare function classifyQuery(query: string, config: ClassifierConfig): QueryClassification;

package/dist/query-classifier.js

@@ -0,0 +1,111 @@
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Build a ClassifierConfig from a KnowledgeConfig.
+ * When config is null (zero-config mode), returns empty config —
+ * search still works via BM25 + embeddings, just without domain pre-filtering.
+ */
+export function buildClassifierConfig(config) {
+    const domainKeywords = config?.query_hints ?? {};
+    // Always include generic "phase N" pattern (dynamic extraction)
+    const phasePatterns = [
+        { pattern: /\bphase\s*(\d+)\b/i, phase: 0, dynamic: true },
+    ];
+    // Add configured phase name + alias patterns
+    if (config?.phases) {
+        for (const p of config.phases) {
+            phasePatterns.push({
+                pattern: new RegExp(`\\b${escapeRegex(p.name)}\\b`, "i"),
+                phase: p.id,
+            });
+            if (p.aliases) {
+                for (const alias of p.aliases) {
+                    phasePatterns.push({
+                        pattern: new RegExp(`\\b${escapeRegex(alias)}\\b`, "i"),
+                        phase: p.id,
+                    });
+                }
+            }
+        }
+    }
+    const synonymMap = config?.synonyms ?? {};
+    return { domainKeywords, phasePatterns, synonymMap };
+}
+// These are linguistically universal — not project-specific
+const DECISION_KEYWORDS = [
+    "why did we",
+    "why do we",
+    "decision",
+    "chose",
+    "choose",
+    "trade-off",
+    "tradeoff",
+    "vs",
+    "versus",
+    "compared to",
+    "alternative",
+    "rationale",
+];
+export function expandSynonyms(query, synonymMap) {
+    const lower = query.toLowerCase();
+    const tokens = lower.split(/\s+/);
+    const expansions = [];
+    for (const token of tokens) {
+        const clean = token.replace(/[^a-z0-9-]/g, "");
+        const synonyms = synonymMap[clean];
+        if (synonyms) {
+            expansions.push(...synonyms);
+        }
+    }
+    if (expansions.length === 0)
+        return query;
+    return `${query} ${expansions.join(" ")}`;
+}
+export function classifyQuery(query, config) {
+    const lower = query.toLowerCase();
+    const domains = [];
+    const phases = [];
+    // Domain classification from config keywords
+    for (const [domain, keywords] of Object.entries(config.domainKeywords)) {
+        for (const kw of keywords) {
+            if (lower.includes(kw.toLowerCase())) {
+                if (!domains.includes(domain)) {
+                    domains.push(domain);
+                }
+                break;
+            }
+        }
+    }
+    // Phase detection
+    for (const { pattern, phase, dynamic } of config.phasePatterns) {
+        if (dynamic) {
+            // Dynamic "phase N" pattern — extract the number
+            const match = pattern.exec(lower);
+            if (match) {
+                const n = parseInt(match[1], 10);
+                if (n > 0 && !phases.includes(n)) {
+                    phases.push(n);
+                }
+            }
+        }
+        else if (pattern.test(lower) && !phases.includes(phase)) {
+            phases.push(phase);
+        }
+    }
+    // Query type detection (universal heuristics, not project-specific)
+    let queryType = "specific";
+    if (DECISION_KEYWORDS.some((kw) => lower.includes(kw))) {
+        queryType = "decision";
+    }
+    else if (lower.startsWith("how does") ||
+        lower.startsWith("what is") ||
+        lower.startsWith("overview") ||
+        lower.startsWith("explain") ||
+        lower.includes("tell me about") ||
+        domains.length === 0) {
+        queryType = "broad";
+    }
+    return { domains, phases, queryType };
+}
+//# sourceMappingURL=query-classifier.js.map

package/dist/query-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-classifier.js","sourceRoot":"","sources":["../src/query-classifier.ts"],"names":[],"mappings":"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"}

package/dist/reranker.d.ts

@@ -0,0 +1,7 @@
+import type { KnowledgeDocument } from "./loader.js";
+interface ScoredDoc {
+    doc: KnowledgeDocument;
+    score: number;
+}
+export declare function rerank(docs: ScoredDoc[], query: string, queryType: "broad" | "specific" | "decision"): ScoredDoc[];
+export {};

package/dist/reranker.js

@@ -0,0 +1,38 @@
+import { tokenize } from "./embeddings.js";
+const SIX_MONTHS_MS = 180 * 24 * 60 * 60 * 1000;
+export function rerank(docs, query, queryType) {
+    if (docs.length === 0)
+        return docs;
+    const queryLower = query.toLowerCase().trim();
+    const queryTokens = tokenize(query);
+    const queryTokenSet = new Set(queryTokens);
+    const now = Date.now();
+    return docs
+        .map(({ doc, score }) => {
+        let adjusted = score;
+        // Title match bonus: query tokens found in title
+        const titleTokens = tokenize(doc.title);
+        const titleOverlap = titleTokens.filter((t) => queryTokenSet.has(t)).length;
+        if (titleOverlap > 0) {
+            adjusted += 0.15 * (titleOverlap / Math.max(queryTokenSet.size, 1));
+        }
+        // Decision-type boost when query is decision-oriented
+        if (queryType === "decision" && doc.type === "decision") {
+            adjusted += 0.1;
+        }
+        // Staleness penalty: docs older than 6 months get a small penalty
+        if (doc.lastUpdated) {
+            const docDate = new Date(doc.lastUpdated).getTime();
+            if (!isNaN(docDate) && now - docDate > SIX_MONTHS_MS) {
+                adjusted -= 0.05;
+            }
+        }
+        // Exact phrase bonus: query substring appears in content body
+        if (queryLower.length > 3 && doc.contentBody.toLowerCase().includes(queryLower)) {
+            adjusted += 0.1;
+        }
+        return { doc, score: adjusted };
+    })
+        .sort((a, b) => b.score - a.score);
+}
+//# sourceMappingURL=reranker.js.map

package/dist/reranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.js","sourceRoot":"","sources":["../src/reranker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAO3C,MAAM,aAAa,GAAG,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhD,MAAM,UAAU,MAAM,CACpB,IAAiB,EACjB,KAAa,EACb,SAA4C;IAE5C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IAC9C,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEvB,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE;QACtB,IAAI,QAAQ,GAAG,KAAK,CAAC;QAErB,iDAAiD;QACjD,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAC5E,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,QAAQ,IAAI,IAAI,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACtE,CAAC;QAED,sDAAsD;QACtD,IAAI,SAAS,KAAK,UAAU,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACxD,QAAQ,IAAI,GAAG,CAAC;QAClB,CAAC;QAED,kEAAkE;QAClE,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;YACpB,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC;YACpD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,GAAG,GAAG,OAAO,GAAG,aAAa,EAAE,CAAC;gBACrD,QAAQ,IAAI,IAAI,CAAC;YACnB,CAAC;QACH,CAAC;QAED,8DAA8D;QAC9D,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAChF,QAAQ,IAAI,GAAG,CAAC;QAClB,CAAC;QAED,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClC,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/dist/search.d.ts

@@ -0,0 +1,17 @@
+import type { KnowledgeGraph } from "./graph.js";
+import { type ClassifierConfig } from "./query-classifier.js";
+import { type Bm25Index } from "./embeddings.js";
+import { type DetailLevel } from "./formatter.js";
+export type TfIdfIndex = Bm25Index;
+interface SearchOptions {
+    query: string;
+    domains?: string[];
+    phases?: number[];
+    tags?: string[];
+    type?: string;
+    maxResults?: number;
+    detailLevel?: DetailLevel;
+    includeDrafts?: boolean;
+}
+export declare function knowledgeSearch(graph: KnowledgeGraph, bm25Index: Bm25Index, options: SearchOptions, classifierConfig: ClassifierConfig): Promise<string>;
+export {};