@gmickel/gno 0.3.0

package/src/mcp/tools/query.ts

@@ -0,0 +1,226 @@
+/**
+ * MCP gno_query tool - Hybrid search with expansion and reranking.
+ *
+ * @module src/mcp/tools/query
+ */
+
+import { join as pathJoin } from 'node:path';
+import { parseUri } from '../../app/constants';
+import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { getActivePreset } from '../../llm/registry';
+import type {
+  EmbeddingPort,
+  GenerationPort,
+  RerankPort,
+} from '../../llm/types';
+import { type HybridSearchDeps, searchHybrid } from '../../pipeline/hybrid';
+import type { SearchResult, SearchResults } from '../../pipeline/types';
+import {
+  createVectorIndexPort,
+  type VectorIndexPort,
+} from '../../store/vector';
+import type { ToolContext } from '../server';
+import { runTool, type ToolResult } from './index';
+
+interface QueryInput {
+  query: string;
+  collection?: string;
+  limit?: number;
+  minScore?: number;
+  lang?: string;
+  expand?: boolean;
+  rerank?: boolean;
+}
+
+/**
+ * Enrich results with absPath derived from each result's URI.
+ */
+function enrichWithAbsPath(
+  results: SearchResult[],
+  ctx: ToolContext
+): SearchResult[] {
+  return results.map((r) => {
+    const parsed = parseUri(r.uri);
+    if (!parsed) {
+      return r;
+    }
+
+    const collection = ctx.collections.find(
+      (c) => c.name === parsed.collection
+    );
+    if (!collection) {
+      return r;
+    }
+
+    return {
+      ...r,
+      source: {
+        ...r.source,
+        absPath: pathJoin(collection.path, r.source.relPath),
+      },
+    };
+  });
+}
+
+/**
+ * Format search results as text for MCP content.
+ */
+function formatSearchResults(data: SearchResults): string {
+  if (data.results.length === 0) {
+    return `No results found for "${data.meta.query}"`;
+  }
+
+  const lines: string[] = [];
+  const mode = data.meta.mode === 'bm25_only' ? 'BM25 only' : 'hybrid';
+  const flags: string[] = [];
+  if (data.meta.expanded) {
+    flags.push('expanded');
+  }
+  if (data.meta.reranked) {
+    flags.push('reranked');
+  }
+  if (data.meta.vectorsUsed) {
+    flags.push('vectors');
+  }
+
+  lines.push(
+    `Found ${data.results.length} results for "${data.meta.query}" (${mode}${flags.length > 0 ? `, ${flags.join(', ')}` : ''}):`
+  );
+  lines.push('');
+
+  for (const r of data.results) {
+    lines.push(`[${r.docid}] ${r.uri} (score: ${r.score.toFixed(3)})`);
+    if (r.title) {
+      lines.push(`  Title: ${r.title}`);
+    }
+    if (r.snippet) {
+      const snippetPreview = r.snippet.slice(0, 200).replace(/\n/g, ' ');
+      lines.push(`  ${snippetPreview}${r.snippet.length > 200 ? '...' : ''}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Handle gno_query tool call.
+ */
+export function handleQuery(
+  args: QueryInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    'gno_query',
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: query with validation, hybrid search, and result formatting
+    async () => {
+      // Validate collection exists if specified
+      if (args.collection) {
+        const exists = ctx.collections.some((c) => c.name === args.collection);
+        if (!exists) {
+          throw new Error(`Collection not found: ${args.collection}`);
+        }
+      }
+
+      const preset = getActivePreset(ctx.config);
+      const llm = new LlmAdapter(ctx.config);
+
+      let embedPort: EmbeddingPort | null = null;
+      let genPort: GenerationPort | null = null;
+      let rerankPort: RerankPort | null = null;
+      let vectorIndex: VectorIndexPort | null = null;
+
+      try {
+        // Create embedding port (for vector search) - optional
+        const embedResult = await llm.createEmbeddingPort(preset.embed);
+        if (embedResult.ok) {
+          embedPort = embedResult.value;
+        }
+
+        // Create generation port (for expansion) - optional
+        // expand defaults to true per spec
+        if (args.expand !== false) {
+          const genResult = await llm.createGenerationPort(preset.gen);
+          if (genResult.ok) {
+            genPort = genResult.value;
+          }
+        }
+
+        // Create rerank port - optional
+        // rerank defaults to true per spec
+        if (args.rerank !== false) {
+          const rerankResult = await llm.createRerankPort(preset.rerank);
+          if (rerankResult.ok) {
+            rerankPort = rerankResult.value;
+          }
+        }
+
+        // Create vector index (optional)
+        if (embedPort) {
+          const embedInitResult = await embedPort.init();
+          if (embedInitResult.ok) {
+            const dimensions = embedPort.dimensions();
+            const db = ctx.store.getRawDb();
+            const vectorResult = await createVectorIndexPort(db, {
+              model: preset.embed,
+              dimensions,
+            });
+            if (vectorResult.ok) {
+              vectorIndex = vectorResult.value;
+            }
+          }
+        }
+
+        const deps: HybridSearchDeps = {
+          store: ctx.store,
+          config: ctx.config,
+          vectorIndex,
+          embedPort,
+          genPort,
+          rerankPort,
+        };
+
+        // Note: per spec, lang is a "hint" for query, not a filter
+        // Pass as queryLanguageHint to affect expansion prompt selection
+        // but NOT retrieval filtering (that would be options.lang)
+        const result = await searchHybrid(deps, args.query, {
+          limit: args.limit ?? 5,
+          minScore: args.minScore,
+          collection: args.collection,
+          queryLanguageHint: args.lang, // Affects expansion prompt, not retrieval
+          noExpand: args.expand === false,
+          noRerank: args.rerank === false,
+        });
+
+        if (!result.ok) {
+          throw new Error(result.error.message);
+        }
+
+        // Enrich with absPath
+        const enrichedResults = enrichWithAbsPath(result.value.results, ctx);
+
+        return {
+          ...result.value,
+          results: enrichedResults,
+          meta: {
+            ...result.value.meta,
+            // Add queryLanguage hint if provided
+            ...(args.lang ? { queryLanguage: args.lang } : {}),
+          },
+        };
+      } finally {
+        if (embedPort) {
+          await embedPort.dispose();
+        }
+        if (genPort) {
+          await genPort.dispose();
+        }
+        if (rerankPort) {
+          await rerankPort.dispose();
+        }
+      }
+    },
+    formatSearchResults
+  );
+}

package/src/mcp/tools/search.ts

@@ -0,0 +1,119 @@
+/**
+ * MCP gno_search tool - BM25 full-text search.
+ *
+ * @module src/mcp/tools/search
+ */
+
+import { join as pathJoin } from 'node:path';
+import { parseUri } from '../../app/constants';
+import { searchBm25 } from '../../pipeline/search';
+import type { SearchResult, SearchResults } from '../../pipeline/types';
+import type { ToolContext } from '../server';
+import { runTool, type ToolResult } from './index';
+
+interface SearchInput {
+  query: string;
+  collection?: string;
+  limit?: number;
+  minScore?: number;
+  lang?: string;
+}
+
+/**
+ * Enrich results with absPath derived from each result's URI.
+ */
+function enrichWithAbsPath(
+  results: SearchResult[],
+  ctx: ToolContext
+): SearchResult[] {
+  return results.map((r) => {
+    const parsed = parseUri(r.uri);
+    if (!parsed) {
+      return r;
+    }
+
+    const collection = ctx.collections.find(
+      (c) => c.name === parsed.collection
+    );
+    if (!collection) {
+      return r;
+    }
+
+    return {
+      ...r,
+      source: {
+        ...r.source,
+        absPath: pathJoin(collection.path, r.source.relPath),
+      },
+    };
+  });
+}
+
+/**
+ * Format search results as text for MCP content.
+ */
+function formatSearchResults(data: SearchResults): string {
+  if (data.results.length === 0) {
+    return `No results found for "${data.meta.query}"`;
+  }
+
+  const lines: string[] = [];
+  lines.push(`Found ${data.results.length} results for "${data.meta.query}":`);
+  lines.push('');
+
+  for (const r of data.results) {
+    lines.push(`[${r.docid}] ${r.uri} (score: ${r.score.toFixed(3)})`);
+    if (r.title) {
+      lines.push(`  Title: ${r.title}`);
+    }
+    if (r.snippet) {
+      const snippetPreview = r.snippet.slice(0, 200).replace(/\n/g, ' ');
+      lines.push(`  ${snippetPreview}${r.snippet.length > 200 ? '...' : ''}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Handle gno_search tool call.
+ */
+export function handleSearch(
+  args: SearchInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    'gno_search',
+    async () => {
+      // Validate collection exists if specified
+      if (args.collection) {
+        const exists = ctx.collections.some((c) => c.name === args.collection);
+        if (!exists) {
+          throw new Error(`Collection not found: ${args.collection}`);
+        }
+      }
+
+      const result = await searchBm25(ctx.store, args.query, {
+        limit: args.limit ?? 5,
+        minScore: args.minScore,
+        collection: args.collection,
+        lang: args.lang,
+      });
+
+      if (!result.ok) {
+        throw new Error(result.error.message);
+      }
+
+      // Enrich with absPath
+      const enrichedResults = enrichWithAbsPath(result.value.results, ctx);
+
+      return {
+        ...result.value,
+        results: enrichedResults,
+      };
+    },
+    formatSearchResults
+  );
+}

package/src/mcp/tools/status.ts

@@ -0,0 +1,81 @@
+/**
+ * MCP gno_status tool - Index status and health.
+ *
+ * @module src/mcp/tools/status
+ */
+
+import type { IndexStatus } from '../../store/types';
+import type { ToolContext } from '../server';
+import { runTool, type ToolResult } from './index';
+
+type StatusInput = Record<string, never>;
+
+/**
+ * Format status as text for MCP content.
+ */
+function formatStatus(status: IndexStatus): string {
+  const lines: string[] = [];
+
+  lines.push(`Index: ${status.indexName}`);
+  lines.push(`Config: ${status.configPath}`);
+  lines.push(`Database: ${status.dbPath}`);
+  lines.push(`Health: ${status.healthy ? 'OK' : 'DEGRADED'}`);
+  lines.push('');
+
+  if (status.collections.length === 0) {
+    lines.push('No collections configured.');
+  } else {
+    lines.push('Collections:');
+    for (const c of status.collections) {
+      lines.push(
+        `  ${c.name}: ${c.activeDocuments} docs, ${c.totalChunks} chunks` +
+          (c.embeddedChunks > 0 ? `, ${c.embeddedChunks} embedded` : '')
+      );
+    }
+  }
+
+  lines.push('');
+  lines.push(
+    `Total: ${status.activeDocuments} documents, ${status.totalChunks} chunks`
+  );
+
+  if (status.embeddingBacklog > 0) {
+    lines.push(`Embedding backlog: ${status.embeddingBacklog} chunks`);
+  }
+
+  if (status.recentErrors > 0) {
+    lines.push(`Recent errors: ${status.recentErrors} (last 24h)`);
+  }
+
+  if (status.lastUpdatedAt) {
+    lines.push(`Last updated: ${status.lastUpdatedAt}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Handle gno_status tool call.
+ */
+export function handleStatus(
+  _args: StatusInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    'gno_status',
+    async () => {
+      const result = await ctx.store.getStatus();
+      if (!result.ok) {
+        throw new Error(result.error.message);
+      }
+
+      // Override configPath with actual path from context
+      return {
+        ...result.value,
+        configPath: ctx.actualConfigPath,
+      };
+    },
+    formatStatus
+  );
+}

package/src/mcp/tools/vsearch.ts

@@ -0,0 +1,198 @@
+/**
+ * MCP gno_vsearch tool - Vector/semantic similarity search.
+ *
+ * @module src/mcp/tools/vsearch
+ */
+
+import { join as pathJoin } from 'node:path';
+import { parseUri } from '../../app/constants';
+import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { getActivePreset } from '../../llm/registry';
+import type { SearchResult, SearchResults } from '../../pipeline/types';
+import {
+  searchVectorWithEmbedding,
+  type VectorSearchDeps,
+} from '../../pipeline/vsearch';
+import { createVectorIndexPort } from '../../store/vector';
+import type { ToolContext } from '../server';
+import { runTool, type ToolResult } from './index';
+
+interface VsearchInput {
+  query: string;
+  collection?: string;
+  limit?: number;
+  minScore?: number;
+  lang?: string;
+}
+
+/**
+ * Enrich results with absPath derived from each result's URI.
+ */
+function enrichWithAbsPath(
+  results: SearchResult[],
+  ctx: ToolContext
+): SearchResult[] {
+  return results.map((r) => {
+    const parsed = parseUri(r.uri);
+    if (!parsed) {
+      return r;
+    }
+
+    const collection = ctx.collections.find(
+      (c) => c.name === parsed.collection
+    );
+    if (!collection) {
+      return r;
+    }
+
+    return {
+      ...r,
+      source: {
+        ...r.source,
+        absPath: pathJoin(collection.path, r.source.relPath),
+      },
+    };
+  });
+}
+
+/**
+ * Format search results as text for MCP content.
+ */
+function formatSearchResults(data: SearchResults): string {
+  if (data.results.length === 0) {
+    return `No results found for "${data.meta.query}"`;
+  }
+
+  const lines: string[] = [];
+  lines.push(
+    `Found ${data.results.length} results for "${data.meta.query}" (vector search):`
+  );
+  lines.push('');
+
+  for (const r of data.results) {
+    lines.push(`[${r.docid}] ${r.uri} (score: ${r.score.toFixed(3)})`);
+    if (r.title) {
+      lines.push(`  Title: ${r.title}`);
+    }
+    if (r.snippet) {
+      const snippetPreview = r.snippet.slice(0, 200).replace(/\n/g, ' ');
+      lines.push(`  ${snippetPreview}${r.snippet.length > 200 ? '...' : ''}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Handle gno_vsearch tool call.
+ */
+export function handleVsearch(
+  args: VsearchInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    'gno_vsearch',
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: vector search with validation and result formatting
+    async () => {
+      // Validate collection exists if specified
+      if (args.collection) {
+        const exists = ctx.collections.some((c) => c.name === args.collection);
+        if (!exists) {
+          throw new Error(`Collection not found: ${args.collection}`);
+        }
+      }
+
+      // Get model from active preset
+      const preset = getActivePreset(ctx.config);
+      const modelUri = preset.embed;
+
+      // Create LLM adapter for embeddings
+      const llm = new LlmAdapter(ctx.config);
+      const embedResult = await llm.createEmbeddingPort(modelUri);
+      if (!embedResult.ok) {
+        throw new Error(
+          `Failed to load embedding model: ${embedResult.error.message}. ` +
+            'Ensure models are downloaded with: gno models pull'
+        );
+      }
+
+      const embedPort = embedResult.value;
+
+      try {
+        // Embed query
+        const queryEmbedResult = await embedPort.embed(args.query);
+        if (!queryEmbedResult.ok) {
+          throw new Error(queryEmbedResult.error.message);
+        }
+        const queryEmbedding = new Float32Array(queryEmbedResult.value);
+        const dimensions = queryEmbedding.length;
+
+        // Create vector index port
+        const db = ctx.store.getRawDb();
+        const vectorResult = await createVectorIndexPort(db, {
+          model: modelUri,
+          dimensions,
+        });
+
+        if (!vectorResult.ok) {
+          throw new Error(
+            `Vector index not available: ${vectorResult.error.message}. ` +
+              'Run: gno embed'
+          );
+        }
+
+        const vectorIndex = vectorResult.value;
+
+        if (!vectorIndex.searchAvailable) {
+          const reason = vectorIndex.loadError
+            ? `sqlite-vec not loaded: ${vectorIndex.loadError}`
+            : 'sqlite-vec not available';
+          throw new Error(
+            `Vector search unavailable (${reason}). ` +
+              'Ensure sqlite-vec is installed for your platform.'
+          );
+        }
+
+        const deps: VectorSearchDeps = {
+          store: ctx.store,
+          vectorIndex,
+          embedPort,
+          config: ctx.config,
+        };
+
+        const result = await searchVectorWithEmbedding(
+          deps,
+          args.query,
+          queryEmbedding,
+          {
+            limit: args.limit ?? 5,
+            minScore: args.minScore,
+            collection: args.collection,
+          }
+        );
+
+        if (!result.ok) {
+          throw new Error(result.error.message);
+        }
+
+        // Enrich with absPath
+        const enrichedResults = enrichWithAbsPath(result.value.results, ctx);
+
+        return {
+          ...result.value,
+          results: enrichedResults,
+          meta: {
+            ...result.value.meta,
+            // Add queryLanguage hint if provided (per spec, lang is a hint for vsearch)
+            ...(args.lang ? { queryLanguage: args.lang } : {}),
+          },
+        };
+      } finally {
+        await embedPort.dispose();
+      }
+    },
+    formatSearchResults
+  );
+}

package/src/pipeline/chunk-lookup.ts

@@ -0,0 +1,44 @@
+/**
+ * Chunk lookup optimization.
+ * Provides O(1) chunk lookup by (hash, seq) instead of O(n) linear scan.
+ *
+ * Performance tradeoff: Pays O(k) Map build cost per hash on first access
+ * to guarantee O(1) lookups thereafter. For one-off lookups, .find() might
+ * be marginally faster, but we prefer consistent O(1) access across
+ * pipelines where multiple lookups per hash are common.
+ *
+ * @module src/pipeline/chunk-lookup
+ */
+
+import type { ChunkRow } from '../store/types';
+
+/**
+ * Create O(1) chunk lookup function from batch-fetched chunks.
+ * Lazily indexes chunks by seq on first access per hash.
+ * First-wins semantics preserves original .find() behavior for duplicate seq.
+ *
+ * @param chunksMap - Map from getChunksBatch()
+ * @returns Lookup function (hash, seq) => ChunkRow | undefined
+ */
+export function createChunkLookup(
+  chunksMap: Map<string, ChunkRow[]>
+): (hash: string, seq: number) => ChunkRow | undefined {
+  // Lazy cache: hash -> (seq -> chunk)
+  const indexCache = new Map<string, Map<number, ChunkRow>>();
+
+  return (hash: string, seq: number): ChunkRow | undefined => {
+    let bySeq = indexCache.get(hash);
+    if (!bySeq) {
+      const chunks = chunksMap.get(hash) ?? [];
+      bySeq = new Map<number, ChunkRow>();
+      // First-wins: preserve .find() behavior for degenerate duplicate seq
+      for (const ch of chunks) {
+        if (!bySeq.has(ch.seq)) {
+          bySeq.set(ch.seq, ch);
+        }
+      }
+      indexCache.set(hash, bySeq);
+    }
+    return bySeq.get(seq);
+  };
+}