@vpxa/kb 0.1.1

package/packages/server/dist/tools/search.tool.js

@@ -0,0 +1,331 @@
+import { graphAugmentSearch } from "@kb/tools";
+import { z } from "zod";
+function reciprocalRankFusion(vectorResults, ftsResults, k = 60) {
+  const merged = /* @__PURE__ */ new Map();
+  for (let i = 0; i < vectorResults.length; i++) {
+    const r = vectorResults[i];
+    merged.set(r.record.id, { record: r.record, score: 1 / (k + i + 1) });
+  }
+  for (let i = 0; i < ftsResults.length; i++) {
+    const r = ftsResults[i];
+    const existing = merged.get(r.record.id);
+    if (existing) {
+      existing.score += 1 / (k + i + 1);
+    } else {
+      merged.set(r.record.id, { record: r.record, score: 1 / (k + i + 1) });
+    }
+  }
+  return [...merged.values()].sort((a, b) => b.score - a.score).map(({ record, score }) => ({ record, score }));
+}
+function applyProximityReranking(results, query) {
+  const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length >= 2);
+  if (terms.length < 2) return results;
+  return results.map((r) => {
+    const content = r.record.content.toLowerCase();
+    const positions = terms.map((term) => {
+      const pos = [];
+      let idx = content.indexOf(term);
+      while (idx !== -1) {
+        pos.push(idx);
+        idx = content.indexOf(term, idx + 1);
+      }
+      return pos;
+    });
+    if (positions.some((p) => p.length === 0)) return r;
+    let minSpan = content.length;
+    for (const startPos of positions[0]) {
+      let spanStart = startPos;
+      let spanEnd = startPos + terms[0].length;
+      for (let t = 1; t < positions.length; t++) {
+        let nearest = positions[t][0];
+        let nearestDist = Math.abs(nearest - startPos);
+        for (let pi = 1; pi < positions[t].length; pi++) {
+          const dist = Math.abs(positions[t][pi] - startPos);
+          if (dist < nearestDist) {
+            nearestDist = dist;
+            nearest = positions[t][pi];
+          }
+        }
+        spanStart = Math.min(spanStart, nearest);
+        spanEnd = Math.max(spanEnd, nearest + terms[t].length);
+      }
+      minSpan = Math.min(minSpan, spanEnd - spanStart);
+    }
+    const proximityBoost = 1 + 0.25 / (1 + minSpan / 200);
+    return { record: r.record, score: r.score * proximityBoost };
+  }).sort((a, b) => b.score - a.score);
+}
+function extractDistinctiveTerms(results, query, maxTerms = 8) {
+  const queryTerms = new Set(
+    query.toLowerCase().split(/\s+/).filter((t) => t.length >= 2)
+  );
+  const termCounts = /* @__PURE__ */ new Map();
+  const totalDocs = results.length;
+  for (const r of results) {
+    const origWords = new Set(
+      r.record.content.split(/[^a-zA-Z0-9_]+/).filter((w) => w.length >= 3 && !STOP_WORDS.has(w.toLowerCase()))
+    );
+    for (const w of origWords) {
+      const lower = w.toLowerCase();
+      if (/[_A-Z]/.test(w)) {
+        termCounts.set(`__id__${lower}`, 1);
+      }
+    }
+    const words = new Set(
+      r.record.content.toLowerCase().split(/[^a-zA-Z0-9_]+/).filter((w) => w.length >= 3 && !STOP_WORDS.has(w))
+    );
+    for (const w of words) {
+      termCounts.set(w, (termCounts.get(w) ?? 0) + 1);
+    }
+  }
+  const scored = [];
+  for (const [term, count] of termCounts) {
+    if (term.startsWith("__id__")) continue;
+    if (queryTerms.has(term)) continue;
+    if (count > totalDocs * 0.8) continue;
+    const idf = Math.log(totalDocs / count);
+    const identifierBonus = termCounts.has(`__id__${term}`) ? 1 : 0;
+    const lenBonus = term.length > 8 ? 0.5 : 0;
+    scored.push({ term, score: idf + identifierBonus + lenBonus });
+  }
+  return scored.sort((a, b) => b.score - a.score).slice(0, maxTerms).map((s) => s.term);
+}
+const STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "are",
+  "but",
+  "not",
+  "you",
+  "all",
+  "can",
+  "had",
+  "her",
+  "was",
+  "one",
+  "our",
+  "out",
+  "has",
+  "have",
+  "from",
+  "this",
+  "that",
+  "with",
+  "they",
+  "been",
+  "said",
+  "each",
+  "which",
+  "their",
+  "will",
+  "other",
+  "about",
+  "many",
+  "then",
+  "them",
+  "these",
+  "some",
+  "would",
+  "make",
+  "like",
+  "into",
+  "could",
+  "time",
+  "very",
+  "when",
+  "come",
+  "just",
+  "know",
+  "take",
+  "people",
+  "also",
+  "back",
+  "after",
+  "only",
+  "more",
+  "than",
+  "over",
+  "such",
+  "import",
+  "export",
+  "const",
+  "function",
+  "return",
+  "true",
+  "false",
+  "null",
+  "undefined",
+  "string",
+  "number",
+  "boolean",
+  "void",
+  "type",
+  "interface"
+]);
+function registerSearchTool(server, embedder, store, graphStore) {
+  server.registerTool(
+    "search",
+    {
+      description: "Search the knowledge base with hybrid vector + keyword matching (BM25 + RRF fusion). Best for finding code, docs, and prior decisions. Supports semantic, keyword, and hybrid modes.",
+      inputSchema: {
+        query: z.string().describe("Natural language search query"),
+        limit: z.number().min(1).max(20).default(5).describe("Maximum results to return"),
+        search_mode: z.enum(["hybrid", "semantic", "keyword"]).default("hybrid").describe(
+          "Search strategy: hybrid (vector + FTS + RRF fusion, default), semantic (vector only), keyword (FTS only)"
+        ),
+        content_type: z.enum([
+          "markdown",
+          "code-typescript",
+          "code-javascript",
+          "code-python",
+          "config-json",
+          "config-yaml",
+          "config-toml",
+          "config-dotenv",
+          "infrastructure",
+          "documentation",
+          "test",
+          "script",
+          "curated-knowledge",
+          "produced-knowledge",
+          "other"
+        ]).optional().describe("Filter by content type"),
+        origin: z.enum(["indexed", "curated", "produced"]).optional().describe("Filter by knowledge origin"),
+        category: z.string().optional().describe("Filter by category (e.g., decisions, patterns, conventions)"),
+        tags: z.array(z.string()).optional().describe("Filter by tags (returns results matching ANY of the specified tags)"),
+        min_score: z.number().min(0).max(1).default(0.25).describe("Minimum similarity score"),
+        graph_hops: z.number().min(0).max(3).default(0).describe(
+          "Number of graph hops to augment results with (0 = no graph context, 1-3 = enrich results with connected entities)"
+        )
+      }
+    },
+    async ({
+      query,
+      limit,
+      search_mode,
+      content_type,
+      origin,
+      category,
+      tags,
+      min_score,
+      graph_hops
+    }) => {
+      try {
+        const filterOpts = {
+          limit,
+          minScore: min_score,
+          contentType: content_type,
+          origin,
+          category,
+          tags
+        };
+        let results;
+        if (search_mode === "keyword") {
+          results = await store.ftsSearch(query, filterOpts);
+          results = results.slice(0, limit);
+        } else if (search_mode === "semantic") {
+          const vector = await embedder.embedQuery(query);
+          results = await store.search(vector, filterOpts);
+        } else {
+          const vector = await embedder.embedQuery(query);
+          const [vectorResults, ftsResults] = await Promise.all([
+            store.search(vector, { ...filterOpts, limit: limit * 2 }),
+            store.ftsSearch(query, { ...filterOpts, limit: limit * 2 }).catch(() => [])
+          ]);
+          results = reciprocalRankFusion(vectorResults, ftsResults).slice(0, limit);
+        }
+        if (results.length > 1) {
+          results = applyProximityReranking(results, query);
+        }
+        if (results.length === 0) {
+          return {
+            content: [{ type: "text", text: "No results found for the given query." }]
+          };
+        }
+        let graphSections;
+        let graphWarning;
+        if (graph_hops > 0 && !graphStore) {
+          graphWarning = "> **Note:** `graph_hops` was set but no graph store is available. Graph augmentation skipped.";
+        }
+        if (graph_hops > 0 && graphStore) {
+          try {
+            const hits = results.map((r) => ({
+              recordId: r.record.id,
+              score: r.score,
+              sourcePath: r.record.sourcePath
+            }));
+            const augmented = await graphAugmentSearch(graphStore, hits, {
+              hops: graph_hops,
+              maxPerHit: 5
+            });
+            graphSections = /* @__PURE__ */ new Map();
+            for (const aug of augmented) {
+              if (aug.graphContext.nodes.length > 0) {
+                const entities = aug.graphContext.nodes.slice(0, 5).map((n) => `  - **${n.name}** (${n.type})`).join("\n");
+                const rels = aug.graphContext.edges.slice(0, 5).map((e) => `  - ${e.fromId} \u2014[${e.type}]\u2192 ${e.toId}`).join("\n");
+                const parts = [
+                  `- **Graph Context** (${graph_hops} hop${graph_hops > 1 ? "s" : ""}):`
+                ];
+                if (entities) parts.push(`  Entities:
+${entities}`);
+                if (rels) parts.push(`  Relationships:
+${rels}`);
+                graphSections.set(aug.recordId, parts.join("\n"));
+              }
+            }
+          } catch (err) {
+            console.error("[KB] Graph augmentation failed (non-fatal):", err);
+            graphWarning = "> **Note:** Graph augmentation failed. Results shown without graph context.";
+          }
+        }
+        const formatted = results.map((r, i) => {
+          const rec = r.record;
+          const header = `### Result ${i + 1} (score: ${r.score.toFixed(3)})`;
+          const meta = [
+            `- **Source**: ${rec.sourcePath}`,
+            rec.headingPath ? `- **Section**: ${rec.headingPath}` : null,
+            `- **Type**: ${rec.contentType}`,
+            rec.startLine ? `- **Lines**: ${rec.startLine}-${rec.endLine}` : null,
+            rec.origin !== "indexed" ? `- **Origin**: ${rec.origin}` : null,
+            rec.category ? `- **Category**: ${rec.category}` : null,
+            rec.tags?.length ? `- **Tags**: ${rec.tags.join(", ")}` : null,
+            graphSections?.get(rec.id) ?? null
+          ].filter(Boolean).join("\n");
+          return `${header}
+${meta}
+
+${rec.content}`;
+        }).join("\n\n---\n\n");
+        const modeLabel = search_mode === "hybrid" ? "hybrid (vector + keyword RRF)" : search_mode === "keyword" ? "keyword (FTS)" : "semantic (vector)";
+        const distinctiveTerms = extractDistinctiveTerms(results, query);
+        const termsHint = distinctiveTerms.length > 0 ? `
+_Distinctive terms: ${distinctiveTerms.map((t) => `\`${t}\``).join(", ")}_` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${graphWarning ? `${graphWarning}
+
+` : ""}${formatted}
+
+---
+_Search mode: ${modeLabel} | ${results.length} results_${termsHint}
+_Next: Use \`lookup\` to see all chunks from a specific file, or \`analyze_structure\` to understand the codebase layout._`
+            }
+          ]
+        };
+      } catch (err) {
+        console.error("[KB] Search failed:", err);
+        return {
+          content: [{ type: "text", text: `Search failed: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerSearchTool
+};
+//# sourceMappingURL=search.tool.js.map

package/packages/server/dist/tools/status.tool.d.ts

@@ -0,0 +1,4 @@
+import type { IGraphStore, IKnowledgeStore } from '@kb/store';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerStatusTool(server: McpServer, store: IKnowledgeStore, graphStore?: IGraphStore): void;
+//# sourceMappingURL=status.tool.d.ts.map

package/packages/server/dist/tools/status.tool.js

@@ -0,0 +1,68 @@
+function registerStatusTool(server, store, graphStore) {
+  server.registerTool(
+    "status",
+    {
+      description: "Get the current status and statistics of the knowledge base index."
+    },
+    async () => {
+      try {
+        const stats = await store.getStats();
+        const paths = await store.listSourcePaths();
+        const text = [
+          "## Knowledge Base Status",
+          "",
+          `- **Total Records**: ${stats.totalRecords}`,
+          `- **Total Files**: ${stats.totalFiles}`,
+          `- **Last Indexed**: ${stats.lastIndexedAt ?? "Never"}`,
+          "",
+          "### Content Types",
+          ...Object.entries(stats.contentTypeBreakdown).map(
+            ([type, count]) => `- ${type}: ${count}`
+          ),
+          "",
+          "### Indexed Files",
+          ...paths.slice(0, 50).map((p) => `- ${p}`),
+          paths.length > 50 ? `
+... and ${paths.length - 50} more files` : ""
+        ];
+        if (graphStore) {
+          try {
+            const graphStats = await graphStore.getStats();
+            text.push(
+              "",
+              "### Knowledge Graph",
+              `- **Nodes**: ${graphStats.nodeCount}`,
+              `- **Edges**: ${graphStats.edgeCount}`,
+              ...Object.entries(graphStats.nodeTypes).map(
+                ([type, count]) => `  - ${type}: ${count}`
+              )
+            );
+          } catch {
+            text.push("", "### Knowledge Graph", "- Graph store unavailable");
+          }
+        }
+        const output = text.join("\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: output + "\n\n---\n_Next: Use `search` to query indexed content, `graph(stats)` to explore the knowledge graph, or `reindex` to refresh the index._"
+            }
+          ]
+        };
+      } catch (err) {
+        console.error("[KB] Status failed:", err);
+        return {
+          content: [
+            { type: "text", text: `Status check failed: ${err.message}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerStatusTool
+};
+//# sourceMappingURL=status.tool.js.map

package/packages/server/dist/tools/toolkit.tools.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MCP tool registrations for @kb/tools capabilities.
+ */
+import type { IEmbedder } from '@kb/embeddings';
+import type { IKnowledgeStore } from '@kb/store';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCompactTool(server: McpServer, embedder: IEmbedder): void;
+export declare function registerScopeMapTool(server: McpServer, embedder: IEmbedder, store: IKnowledgeStore): void;
+export declare function registerFindTool(server: McpServer, embedder: IEmbedder, store: IKnowledgeStore): void;
+export declare function registerParseOutputTool(server: McpServer): void;
+export declare function registerWorksetTool(server: McpServer): void;
+export declare function registerCheckTool(server: McpServer): void;
+export declare function registerBatchTool(server: McpServer, embedder: IEmbedder, store: IKnowledgeStore): void;
+export declare function registerSymbolTool(server: McpServer, embedder: IEmbedder, store: IKnowledgeStore): void;
+export declare function registerEvalTool(server: McpServer): void;
+export declare function registerTestRunTool(server: McpServer): void;
+export declare function registerStashTool(server: McpServer): void;
+export declare function registerGitContextTool(server: McpServer): void;
+export declare function registerDiffParseTool(server: McpServer): void;
+export declare function registerRenameTool(server: McpServer): void;
+export declare function registerCodemodTool(server: McpServer): void;
+export declare function registerFileSummaryTool(server: McpServer): void;
+export declare function registerCheckpointTool(server: McpServer): void;
+export declare function registerDataTransformTool(server: McpServer): void;
+export declare function registerTraceTool(server: McpServer, embedder: IEmbedder, store: IKnowledgeStore): void;
+export declare function registerFindExamplesTool(server: McpServer, embedder: IEmbedder, store: IKnowledgeStore): void;
+export declare function registerProcessTool(server: McpServer): void;
+export declare function registerWatchTool(server: McpServer): void;
+export declare function registerDeadSymbolsTool(server: McpServer, embedder: IEmbedder, store: IKnowledgeStore): void;
+export declare function registerDelegateTool(server: McpServer): void;
+export declare function registerLaneTool(server: McpServer): void;
+export declare function registerHealthTool(server: McpServer): void;
+export declare function registerQueueTool(server: McpServer): void;
+export declare function registerWebFetchTool(server: McpServer): void;
+//# sourceMappingURL=toolkit.tools.d.ts.map