knowledge-mcp-server 1.0.0

package/dist/search.js

@@ -0,0 +1,299 @@
+import { getAncestors, getRelated } from "./graph.js";
+import { classifyQuery, expandSynonyms } from "./query-classifier.js";
+import { cosineSimilarity, embedQuery, bm25Score, tokenize } from "./embeddings.js";
+import { formatSearchResults, } from "./formatter.js";
+import { rerank } from "./reranker.js";
+import { log } from "./logger.js";
+// Stage 1: Query classification (rule-based)
+function classifyAndMerge(options, classifierConfig) {
+    const classification = classifyQuery(options.query, classifierConfig);
+    // Merge explicit filters with classified ones
+    const domains = options.domains?.length ? options.domains : classification.domains;
+    const phases = options.phases?.length ? options.phases : classification.phases;
+    return { domains, phases, queryType: classification.queryType };
+}
+// Stage 2: Metadata pre-filter (uses phaseIndex for O(1) phase lookups)
+function metadataFilter(graph, domains, phases, tags, type) {
+    let candidates = null;
+    // Domain filter
+    if (domains.length > 0) {
+        candidates = new Set();
+        for (const domain of domains) {
+            const domainDocs = graph.domainIndex.get(domain.toLowerCase());
+            if (domainDocs) {
+                for (const id of domainDocs)
+                    candidates.add(id);
+            }
+        }
+    }
+    // Phase filter (using phaseIndex instead of iterating all documents)
+    if (phases.length > 0) {
+        const phaseFiltered = new Set();
+        for (const phase of phases) {
+            const phaseDocs = graph.phaseIndex.get(phase);
+            if (phaseDocs) {
+                for (const id of phaseDocs)
+                    phaseFiltered.add(id);
+            }
+        }
+        if (candidates) {
+            candidates = new Set([...candidates].filter((id) => phaseFiltered.has(id)));
+        }
+        else {
+            candidates = phaseFiltered;
+        }
+    }
+    // Tag filter
+    if (tags && tags.length > 0) {
+        const tagFiltered = new Set();
+        for (const tag of tags) {
+            const tagDocs = graph.tagIndex.get(tag.toLowerCase());
+            if (tagDocs) {
+                for (const id of tagDocs)
+                    tagFiltered.add(id);
+            }
+        }
+        if (candidates) {
+            candidates = new Set([...candidates].filter((id) => tagFiltered.has(id)));
+        }
+        else {
+            candidates = tagFiltered;
+        }
+    }
+    // Type filter
+    if (type) {
+        const typeDocs = graph.typeIndex.get(type);
+        const typeFiltered = typeDocs ? new Set(typeDocs) : new Set();
+        if (candidates) {
+            candidates = new Set([...candidates].filter((id) => typeFiltered.has(id)));
+        }
+        else {
+            candidates = typeFiltered;
+        }
+    }
+    // No filters → all documents
+    if (!candidates) {
+        candidates = new Set(graph.documents.keys());
+    }
+    return candidates;
+}
+// Determine which fields a query matched against
+function detectMatchedOn(query, doc) {
+    const queryTokens = new Set(tokenize(query));
+    const parts = [];
+    const titleTokens = tokenize(doc.title);
+    if (titleTokens.some((t) => queryTokens.has(t)))
+        parts.push("title");
+    const tagTokens = doc.tags.flatMap((t) => tokenize(t));
+    if (tagTokens.some((t) => queryTokens.has(t)))
+        parts.push("tags");
+    const bodyTokens = tokenize(doc.contentBody.slice(0, 2000));
+    if (bodyTokens.some((t) => queryTokens.has(t)))
+        parts.push("body");
+    return parts.length > 0 ? parts.join("+") : "semantic";
+}
+// Reciprocal Rank Fusion constant
+const RRF_K = 60;
+// Stage 3: Hybrid scoring — vector + BM25 merged via RRF when embeddings available
+async function scoreDocuments(graph, candidates, query, bm25Index, synonymMap) {
+    let queryVector = null;
+    // Expand synonyms for BM25 (vector embeddings handle semantic similarity natively)
+    const expandedQuery = expandSynonyms(query, synonymMap);
+    // Always compute BM25 scores (using synonym-expanded query)
+    const bm25Scored = [];
+    for (const id of candidates) {
+        const doc = graph.documents.get(id);
+        if (!doc)
+            continue;
+        const score = bm25Score(expandedQuery, id, bm25Index);
+        bm25Scored.push({ doc, score });
+    }
+    bm25Scored.sort((a, b) => b.score - a.score);
+    // Try vector similarity
+    if (graph.embeddings.available) {
+        queryVector = await embedQuery(query);
+    }
+    if (queryVector) {
+        // Hybrid: compute vector scores, merge with RRF
+        const vectorScored = [];
+        for (const id of candidates) {
+            const docVector = graph.embeddings.vectors.get(id);
+            const doc = graph.documents.get(id);
+            if (!doc)
+                continue;
+            const score = docVector ? cosineSimilarity(queryVector, docVector) : 0;
+            vectorScored.push({ doc, score });
+        }
+        vectorScored.sort((a, b) => b.score - a.score);
+        // Build rank maps
+        const vectorRank = new Map();
+        const bm25Rank = new Map();
+        for (let i = 0; i < vectorScored.length; i++) {
+            vectorRank.set(vectorScored[i].doc.id, i + 1);
+        }
+        for (let i = 0; i < bm25Scored.length; i++) {
+            bm25Rank.set(bm25Scored[i].doc.id, i + 1);
+        }
+        // Merge via RRF
+        const merged = [];
+        const allIds = new Set([...vectorRank.keys(), ...bm25Rank.keys()]);
+        for (const id of allIds) {
+            const doc = graph.documents.get(id);
+            if (!doc)
+                continue;
+            const vr = vectorRank.get(id) ?? vectorScored.length + 1;
+            const br = bm25Rank.get(id) ?? bm25Scored.length + 1;
+            const score = 1 / (RRF_K + vr) + 1 / (RRF_K + br);
+            merged.push({ doc, score });
+        }
+        merged.sort((a, b) => b.score - a.score);
+        return { scored: merged, queryVector, searchMethod: "vector+bm25" };
+    }
+    // BM25-only fallback
+    return { scored: bm25Scored, queryVector, searchMethod: "bm25_fallback" };
+}
+// Stage 4: Hierarchical expansion + graph walk
+function expandResults(graph, topResults, maxTotal, bm25Index, queryVector, query, maxRelated, searchMethod) {
+    const seen = new Set();
+    const formattedDocs = [];
+    // 4a: Collect unique ancestors (never dropped)
+    const ancestorDocs = [];
+    for (const { doc } of topResults) {
+        const ancestors = getAncestors(graph, doc.id);
+        for (const a of ancestors) {
+            if (!seen.has(a.id)) {
+                seen.add(a.id);
+                ancestorDocs.push(a);
+            }
+        }
+    }
+    for (const a of ancestorDocs) {
+        formattedDocs.push({ doc: a, relevance: "ancestor" });
+    }
+    // Primary results (with annotations)
+    for (const { doc, score } of topResults) {
+        if (!seen.has(doc.id)) {
+            seen.add(doc.id);
+            formattedDocs.push({
+                doc,
+                relevance: "primary",
+                similarity: score,
+                matchedOn: detectMatchedOn(query, doc),
+                scoringMethod: searchMethod,
+            });
+        }
+    }
+    // 4b: Related-link expansion (skip if maxRelated is 0)
+    if (maxRelated <= 0)
+        return formattedDocs;
+    // Compute median primary score for BM25 threshold
+    const primaryScores = topResults.map((r) => r.score).sort((a, b) => a - b);
+    const medianPrimaryScore = primaryScores.length > 0 ? primaryScores[Math.floor(primaryScores.length / 2)] : 0;
+    const relatedCandidates = [];
+    const topForExpansion = topResults.slice(0, 4);
+    for (const { doc } of topForExpansion) {
+        const related = getRelated(graph, doc.id);
+        for (const r of related) {
+            if (!seen.has(r.id)) {
+                // Score the related doc — use embeddings if available, BM25 fallback
+                let score;
+                let useVector = false;
+                const docVector = queryVector ? graph.embeddings.vectors.get(r.id) : undefined;
+                if (queryVector && docVector) {
+                    score = cosineSimilarity(queryVector, docVector);
+                    useVector = true;
+                }
+                else {
+                    score = bm25Score(query, r.id, bm25Index);
+                }
+                // Score threshold: filter out low-relevance related docs
+                const minScore = useVector ? 0.3 : 0.4 * medianPrimaryScore;
+                if (score >= minScore) {
+                    relatedCandidates.push({ doc: r, score, sourceId: doc.id });
+                }
+            }
+        }
+    }
+    // Sort related by score, take up to budget
+    relatedCandidates.sort((a, b) => b.score - a.score);
+    const budget = maxTotal - formattedDocs.length;
+    const relatedToAdd = relatedCandidates.slice(0, Math.min(maxRelated, budget));
+    for (const { doc, score, sourceId } of relatedToAdd) {
+        if (!seen.has(doc.id)) {
+            seen.add(doc.id);
+            formattedDocs.push({
+                doc,
+                relevance: "graph-expanded",
+                similarity: score > 0 ? score : undefined,
+                expandedFrom: sourceId,
+                scoringMethod: searchMethod,
+            });
+        }
+    }
+    return formattedDocs;
+}
+export async function knowledgeSearch(graph, bm25Index, options, classifierConfig) {
+    const maxResults = options.maxResults || 10;
+    const detailLevel = options.detailLevel || "normal";
+    const searchStart = Date.now();
+    // Stage 1: Classify query
+    const { domains, phases, queryType } = classifyAndMerge(options, classifierConfig);
+    // Stage 2: Metadata pre-filter
+    const candidates = metadataFilter(graph, domains, phases, options.tags, options.type);
+    // Stage 3: Score documents
+    const { scored: rawScored, queryVector, searchMethod, } = await scoreDocuments(graph, candidates, options.query, bm25Index, classifierConfig.synonymMap);
+    // Re-rank top candidates (title match, decision boost, staleness, exact phrase)
+    const reranked = rerank(rawScored.slice(0, 20), options.query, queryType);
+    const remaining = rawScored.slice(20);
+    // Filter drafts (unless explicitly included), penalize deprecated (0.5x score)
+    const scored = [...reranked, ...remaining]
+        .filter((s) => options.includeDrafts || s.doc.status !== "draft")
+        .map((s) => (s.doc.status === "deprecated" ? { ...s, score: s.score * 0.5 } : s));
+    scored.sort((a, b) => b.score - a.score);
+    // Adaptive top-N based on query type
+    let topN;
+    let maxRelated;
+    switch (queryType) {
+        case "broad":
+            topN = Math.min(4, scored.length);
+            maxRelated = 2;
+            break;
+        case "decision":
+            topN = Math.min(3, scored.length);
+            maxRelated = 0;
+            break;
+        case "specific":
+        default:
+            topN = Math.min(6, scored.length);
+            maxRelated = 3;
+            break;
+    }
+    const topResults = scored.slice(0, topN);
+    // Stage 4: Expand with ancestors + related
+    const formatted = expandResults(graph, topResults, maxResults, bm25Index, queryVector, options.query, maxRelated, searchMethod);
+    // Compute facets from all scored candidates (not just top-N)
+    const facets = {
+        domains: new Map(),
+        types: new Map(),
+        phases: new Map(),
+    };
+    for (const { doc } of scored) {
+        facets.domains.set(doc.domain, (facets.domains.get(doc.domain) || 0) + 1);
+        facets.types.set(doc.type, (facets.types.get(doc.type) || 0) + 1);
+        for (const p of doc.phase) {
+            const key = `phase-${p}`;
+            facets.phases.set(key, (facets.phases.get(key) || 0) + 1);
+        }
+    }
+    log.info("search", {
+        query: options.query,
+        queryType,
+        method: searchMethod,
+        candidates: candidates.size,
+        results: formatted.length,
+        ms: Date.now() - searchStart,
+    });
+    // Stage 5: Format for Claude
+    return formatSearchResults(options.query, formatted, detailLevel, searchMethod, facets);
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

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

package/dist/validator.d.ts

@@ -0,0 +1,23 @@
+import type { KnowledgeGraph } from "./graph.js";
+export interface ValidationReport {
+    orphans: string[];
+    brokenRelated: Array<{
+        doc: string;
+        ref: string;
+    }>;
+    brokenChildren: Array<{
+        doc: string;
+        ref: string;
+    }>;
+    circularParents: string[];
+    noTags: string[];
+    emptySummaries: string[];
+    staleDocs: string[];
+    embeddingCoverage: {
+        total: number;
+        covered: number;
+        percent: number;
+    };
+}
+export declare function validateGraph(graph: KnowledgeGraph): ValidationReport;
+export declare function formatValidationReport(report: ValidationReport): string;

package/dist/validator.js

@@ -0,0 +1,97 @@
+const SIX_MONTHS_MS = 180 * 24 * 60 * 60 * 1000;
+export function validateGraph(graph) {
+    const now = Date.now();
+    const report = {
+        orphans: [],
+        brokenRelated: [],
+        brokenChildren: [],
+        circularParents: [],
+        noTags: [],
+        emptySummaries: [],
+        staleDocs: [],
+        embeddingCoverage: { total: 0, covered: 0, percent: 0 },
+    };
+    for (const doc of graph.documents.values()) {
+        // Orphan check: has a parentId that doesn't exist (and isn't a top-level domain doc)
+        if (doc.parentId && doc.parentId !== "root" && !graph.documents.has(doc.parentId)) {
+            report.orphans.push(doc.id);
+        }
+        // Broken related references
+        for (const ref of doc.related) {
+            if (!graph.documents.has(ref)) {
+                report.brokenRelated.push({ doc: doc.id, ref });
+            }
+        }
+        // Broken children references
+        for (const ref of doc.childrenIds) {
+            if (!graph.documents.has(ref)) {
+                report.brokenChildren.push({ doc: doc.id, ref });
+            }
+        }
+        // Circular parent chain detection
+        const visited = new Set();
+        let current = doc.id;
+        let circular = false;
+        while (current) {
+            if (visited.has(current)) {
+                circular = true;
+                break;
+            }
+            visited.add(current);
+            current = graph.documents.get(current)?.parentId ?? null;
+        }
+        if (circular) {
+            report.circularParents.push(doc.id);
+        }
+        // Docs with zero tags
+        if (doc.tags.length === 0) {
+            report.noTags.push(doc.id);
+        }
+        // Summary nodes without children
+        if (doc.type === "summary" && doc.childrenIds.length === 0) {
+            report.emptySummaries.push(doc.id);
+        }
+        // Stale docs (>6 months since last update)
+        if (doc.lastUpdated) {
+            const docDate = new Date(doc.lastUpdated).getTime();
+            if (!isNaN(docDate) && now - docDate > SIX_MONTHS_MS) {
+                report.staleDocs.push(doc.id);
+            }
+        }
+    }
+    // Embedding coverage
+    const total = graph.documents.size;
+    const covered = [...graph.documents.keys()].filter((id) => graph.embeddings.vectors.has(id)).length;
+    report.embeddingCoverage = {
+        total,
+        covered,
+        percent: total > 0 ? Math.round((covered / total) * 100) : 0,
+    };
+    return report;
+}
+export function formatValidationReport(report) {
+    const lines = ["Knowledge Graph Validation Report", "=".repeat(38), ""];
+    const addSection = (title, items) => {
+        lines.push(`${title}: ${items.length === 0 ? "none" : items.length}`);
+        for (const item of items) {
+            lines.push(`  - ${item}`);
+        }
+    };
+    addSection("Orphaned documents", report.orphans);
+    addSection("Broken related references", report.brokenRelated.map((r) => `${r.doc} → ${r.ref}`));
+    addSection("Broken children references", report.brokenChildren.map((r) => `${r.doc} → ${r.ref}`));
+    addSection("Circular parent chains", report.circularParents);
+    addSection("Documents with no tags", report.noTags);
+    addSection("Empty summary nodes (no children)", report.emptySummaries);
+    addSection("Stale documents (>6 months)", report.staleDocs);
+    lines.push("");
+    lines.push(`Embedding coverage: ${report.embeddingCoverage.covered}/${report.embeddingCoverage.total} (${report.embeddingCoverage.percent}%)`);
+    const issueCount = report.orphans.length +
+        report.brokenRelated.length +
+        report.brokenChildren.length +
+        report.circularParents.length;
+    lines.push("");
+    lines.push(issueCount === 0 ? "No integrity issues found." : `${issueCount} integrity issue(s) found.`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=validator.js.map

package/dist/validator.js.map

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

package/dist/writer.d.ts

@@ -0,0 +1,36 @@
+import { type DocumentStatus } from "./loader.js";
+import { type Bm25Index } from "./embeddings.js";
+import type { KnowledgeGraph } from "./graph.js";
+export type TfIdfIndex = Bm25Index;
+export interface WriteParams {
+    id: string;
+    title: string;
+    type: string;
+    domain: string;
+    subdomain?: string;
+    tags: string[];
+    phase: number[];
+    related?: string[];
+    children?: string[];
+    content: string;
+    status?: DocumentStatus;
+    superseded_by?: string;
+    decision_status?: "proposed" | "accepted" | "deprecated" | "superseded" | "finalized";
+    alternatives_considered?: string[];
+    decision_date?: string;
+}
+export interface WriteResult {
+    id: string;
+    filePath: string;
+    parentId: string | null;
+    status: "created" | "updated";
+    tfidfIndex: Bm25Index;
+    warnings: string[];
+}
+export interface DeleteResult {
+    id: string;
+    warnings: string[];
+    tfidfIndex: Bm25Index;
+}
+export declare function writeDocument(graph: KnowledgeGraph, tfidfIndex: Bm25Index, knowledgeDir: string, params: WriteParams, validDomains?: string[] | null, validPhaseIds?: number[] | null): WriteResult;
+export declare function deleteDocument(graph: KnowledgeGraph, tfidfIndex: Bm25Index, knowledgeDir: string, id: string): DeleteResult;