kotadb 2.2.0-next.20260204230500 → 2.2.0-next.20260205005118

package/src/mcp/server.ts

@@ -16,6 +16,7 @@ import { Sentry } from "../instrument.js";
 import {
 	ANALYZE_CHANGE_IMPACT_TOOL,
 	GENERATE_TASK_CONTEXT_TOOL,
+	GET_INDEX_STATISTICS_TOOL,
 	INDEX_REPOSITORY_TOOL,
 	LIST_RECENT_FILES_TOOL,
 	SEARCH_TOOL,
@@ -35,6 +36,7 @@ import {
 	// Execute functions
 	executeAnalyzeChangeImpact,
 	executeGenerateTaskContext,
+	executeGetIndexStatistics,
 	executeIndexRepository,
 	executeListRecentFiles,
 	executeSearch,

package/src/mcp/tools.ts

@@ -6,12 +6,14 @@
  */
 
 import {
+	getIndexStatistics,
 	listRecentFiles,
 	queryDependencies,
 	queryDependents,
 	resolveFilePath,
 	runIndexingWorkflow,
 	searchFiles,
+	extractLineSnippets,
 } from "@api/queries";
 import { getDomainKeyFiles } from "@api/expertise-queries.js";
 import { getGlobalDatabase } from "@db/sqlite/index.js";
@@ -111,8 +113,20 @@ export function isValidToolset(value: string): value is ToolsetTier {
 export const SEARCH_TOOL: ToolDefinition = {
 	tier: "core",
 	name: "search",
-	description:
-		"Search indexed code, symbols, decisions, patterns, and failures. Supports multiple search scopes simultaneously with scope-specific filters and output formats.",
+	description: `Search indexed code, symbols, decisions, patterns, and failures.
+
+OUTPUT MODES:
+- 'paths': File paths only (~100 bytes/result)
+- 'compact': Summary info (~200 bytes/result) - DEFAULT for code scope
+- 'snippet': Matching lines with context (~2KB/result)
+- 'full': Complete content (~100KB/result) - Use with caution for code scope
+
+TIPS:
+- Use 'snippet' for code exploration (shows matches in context)
+- Use 'compact' for quick file discovery
+- Use 'full' only for small result sets (symbols, decisions, etc.)
+
+Supports multiple search scopes simultaneously with scope-specific filters.`,
 	inputSchema: {
 		type: "object",
 		properties: {
@@ -196,8 +210,14 @@ export const SEARCH_TOOL: ToolDefinition = {
 			},
 			output: {
 				type: "string",
-				enum: ["full", "paths", "compact"],
-				description: "Output format (default: 'full')",
+				enum: ["full", "paths", "compact", "snippet"],
+				description: "Output format: 'paths' (file paths only), 'compact' (summary), 'snippet' (matches with context), 'full' (complete content). Default varies by scope: code='compact', others='full'. WARNING: 'full' + code scope = large results.",
+			},
+			context_lines: {
+				type: "number",
+				description: "Lines of context before/after matches (snippet mode only, default: 3, max: 10)",
+				minimum: 0,
+				maximum: 10,
 			},
 		},
 		required: ["query"],
@@ -353,6 +373,21 @@ export const ANALYZE_CHANGE_IMPACT_TOOL: ToolDefinition = {
 	},
 };
 
+/**
+ * Tool: get_index_statistics
+ */
+export const GET_INDEX_STATISTICS_TOOL: ToolDefinition = {
+	tier: "core",
+	name: "get_index_statistics",
+	description:
+		"Get statistics about indexed data (files, symbols, references, decisions, patterns, failures). Useful for understanding what data is available for search.",
+	inputSchema: {
+		type: "object",
+		properties: {},
+		required: [],
+	},
+};
+
 /**
  * Tool: validate_implementation_spec
  */
@@ -770,6 +805,7 @@ export function getToolDefinitions(): ToolDefinition[] {
 		LIST_RECENT_FILES_TOOL,
 		SEARCH_DEPENDENCIES_TOOL,
 		ANALYZE_CHANGE_IMPACT_TOOL,
+		GET_INDEX_STATISTICS_TOOL,
 		VALIDATE_IMPLEMENTATION_SPEC_TOOL,
 		SYNC_EXPORT_TOOL,
 		SYNC_IMPORT_TOOL,
@@ -958,11 +994,122 @@ async function searchSymbols(
 	}));
 }
 
+/**
+ * Generate contextual tips based on search query and parameters.
+ * Uses static pattern matching (no NLP) to detect suboptimal usage patterns.
+ * 
+ * Tip frequency: MODERATE - show tips frequently including "nice to know" suggestions.
+ * 
+ * @param query - Search query string
+ * @param scopes - Search scopes used
+ * @param filters - Normalized filters applied
+ * @param scopeResults - Results by scope
+ * @returns Array of tip strings (empty if search is optimal)
+ */
+function generateSearchTips(
+	query: string,
+	scopes: string[],
+	filters: NormalizedFilters,
+	scopeResults: Record<string, unknown[]>
+): string[] {
+	const tips: string[] = [];
+	const queryLower = query.toLowerCase();
+	
+	// Pattern 1: Query contains structural keywords but not using symbols scope
+	const structuralKeywords = ['function', 'class', 'interface', 'type', 'method', 'component'];
+	const hasStructuralKeyword = structuralKeywords.some(kw => queryLower.includes(kw));
+	
+	if (hasStructuralKeyword && !scopes.includes('symbols')) {
+		const matchedKeyword = structuralKeywords.find(kw => queryLower.includes(kw)) || 'function';
+		tips.push(
+			`You searched for "${query}" in code. Try scope: ['symbols'] with filters: {symbol_kind: ['${matchedKeyword}']} for precise structural discovery.`
+		);
+	}
+	
+	// Pattern 2: Query looks like a file path but using code search
+	const looksLikeFilePath = /^[\w\-./]+\.(ts|tsx|js|jsx|py|rs|go|java)$/i.test(query);
+	if (looksLikeFilePath && scopes.includes('code')) {
+		tips.push(
+			`Query "${query}" looks like a file path. Consider using search_dependencies tool to find files that depend on this file or its dependencies.`
+		);
+	}
+	
+	// Pattern 3: Symbol search without exported_only filter
+	if (scopes.includes('symbols') && filters.exported_only === undefined) {
+		const symbolCount = scopeResults['symbols']?.length || 0;
+		if (symbolCount > 10) {
+			tips.push(
+				`Found ${symbolCount} symbols. Add filters: {exported_only: true} to narrow to public API only.`
+			);
+		}
+	}
+	
+	// Pattern 4: No repository filter with large result set
+	if (!filters.repositoryId) {
+		const totalResults = Object.values(scopeResults).reduce((sum, arr) => sum + arr.length, 0);
+		if (totalResults > 20) {
+			tips.push(
+				`Found ${totalResults} results across all repositories. Add filters: {repository: "owner/repo"} to narrow to a specific repository.`
+			);
+		}
+	}
+	
+	// Pattern 5: Code search without glob/language filters
+	if (scopes.includes('code') && !filters.glob && !filters.language) {
+		const codeCount = scopeResults['code']?.length || 0;
+		if (codeCount > 15) {
+			tips.push(
+				`Found ${codeCount} code results. Try filters: {glob: "**/*.ts"} or {language: "typescript"} to narrow file types.`
+			);
+		}
+	}
+	
+	// Pattern 6: Suggest decisions scope for "why" questions
+	if (/\b(why|reason|decision|chose|choice)\b/i.test(query) && !scopes.includes('decisions')) {
+		tips.push(
+			`Query contains "why/reason/decision". Try scope: ['decisions'] to search architectural decisions and rationale.`
+		);
+	}
+	
+	// Pattern 7: Suggest patterns scope for "how" questions
+	if (/\b(how|pattern|best practice|convention)\b/i.test(query) && !scopes.includes('patterns')) {
+		tips.push(
+			`Query asks "how to". Try scope: ['patterns'] to search coding patterns and conventions from this codebase.`
+		);
+	}
+	
+	// Pattern 8: Suggest failures scope for error-related queries
+	if (/\b(error|bug|fail|issue|problem|fix)\b/i.test(query) && !scopes.includes('failures')) {
+		tips.push(
+			`Query mentions errors/issues. Try scope: ['failures'] to learn from past mistakes and avoid repeated failures.`
+		);
+	}
+	
+	// Pattern 9: Single scope when multi-scope could be useful
+	if (scopes.length === 1 && scopes[0] === 'code') {
+		tips.push(
+			`Tip: You can search multiple scopes simultaneously. Try scope: ['code', 'symbols'] for broader discovery.`
+		);
+	}
+	
+	// Pattern 10: Suggest compact format for large result sets
+	const totalResults = Object.values(scopeResults).reduce((sum, arr) => sum + arr.length, 0);
+	if (totalResults > 30 && !tips.some(t => t.includes('output: "compact"'))) {
+		tips.push(
+			`Returning ${totalResults} full results. Use output: "compact" for summary view or output: "paths" for file paths only.`
+		);
+	}
+	
+	return tips;
+}
+
 function formatSearchResults(
 	query: string,
 	scopes: string[],
 	scopeResults: Record<string, unknown[]>,
-	format: string
+	format: string,
+	filters: NormalizedFilters,
+	contextLines?: number
 ): Record<string, unknown> {
 	const response: Record<string, unknown> = {
 		query,
@@ -998,6 +1145,36 @@ function formatSearchResults(
 				}
 				return item;
 			});
+		} else if (format === "snippet") {
+			// Snippet extraction with context
+			if (scope === "code") {
+				(response.results as Record<string, unknown>)[scope] = items.map((item: any) => {
+					const matches = extractLineSnippets(
+						item.content || "",
+						query,
+						contextLines || 3
+					);
+					return {
+						path: item.path,
+						matches: matches
+					};
+				});
+			} else {
+				// For non-code scopes, fall back to compact format
+				// (snippets only meaningful for code files)
+				(response.results as Record<string, unknown>)[scope] = items.map((item: any) => {
+					if (scope === "symbols") {
+						return { name: item.name, kind: item.kind, file: item.location.file };
+					} else if (scope === "decisions") {
+						return { title: item.title, scope: item.scope };
+					} else if (scope === "patterns") {
+						return { pattern_type: item.pattern_type, file_path: item.file_path };
+					} else if (scope === "failures") {
+						return { title: item.title, problem: item.problem };
+					}
+					return item;
+				});
+			}
 		} else {
 			// Full details
 			(response.results as Record<string, unknown>)[scope] = items;
@@ -1007,6 +1184,13 @@ function formatSearchResults(
 		(response.counts as Record<string, unknown>).total = ((response.counts as Record<string, unknown>).total as number) + items.length;
 	}
 
+	
+	// Generate and add tips if applicable
+	const tips = generateSearchTips(query, scopes, filters, scopeResults);
+	if (tips.length > 0) {
+		response.tips = tips;
+	}
+	
 	return response;
 }
 
@@ -1057,13 +1241,30 @@ export async function executeSearch(
 	}
 
 	if (p.output !== undefined) {
-		if (typeof p.output !== "string" || !["full", "paths", "compact"].includes(p.output)) {
-			throw new Error("Parameter 'output' must be one of: full, paths, compact");
+		if (typeof p.output !== "string" || !["full", "paths", "compact", "snippet"].includes(p.output)) {
+			throw new Error("Parameter 'output' must be one of: full, paths, compact, snippet");
 		}
 	}
 
+	if (p.context_lines !== undefined && typeof p.context_lines !== "number") {
+		throw new Error("Parameter 'context_lines' must be a number");
+	}
+
+	if (p.context_lines !== undefined && (p.context_lines < 0 || p.context_lines > 10)) {
+		throw new Error("Parameter 'context_lines' must be between 0 and 10");
+	}
+
 	const limit = Math.min(Math.max((p.limit as number) || 20, 1), 100);
-	const output = (p.output as string) || "full";
+	// Determine default output based on scopes
+	let defaultOutput = "full";
+	if (scopes.length === 1 && scopes[0] === "code") {
+		defaultOutput = "compact";  // Code-only searches default to compact
+	} else if (scopes.includes("code") && scopes.length > 1) {
+		defaultOutput = "compact";  // Multi-scope including code defaults to compact
+	}
+
+	const output = (p.output as string) || defaultOutput;
+	const contextLines = Math.min(Math.max((p.context_lines as number) || 3, 0), 10);
 	const filters = normalizeFilters(p.filters);
 
 	// Route to scope handlers in parallel
@@ -1142,7 +1343,7 @@ export async function executeSearch(
 	await Promise.all(searchPromises);
 
 	// Format output
-	const response = formatSearchResults(p.query as string, scopes, results, output);
+	const response = formatSearchResults(p.query as string, scopes, results, output, filters, contextLines);
 
 	logger.info("Unified search completed", {
 		query: p.query,
@@ -1634,6 +1835,26 @@ export async function executeAnalyzeChangeImpact(
 	return result;
 }
 
+/**
+ * Execute get_index_statistics tool
+ */
+export async function executeGetIndexStatistics(
+	params: unknown,
+	requestId: string | number,
+	userId: string,
+): Promise<unknown> {
+	// No parameters to validate
+	
+	logger.info("Getting index statistics", { request_id: String(requestId), user_id: userId });
+	
+	const stats = getIndexStatistics();
+	
+	return {
+		...stats,
+		summary: `${stats.symbols.toLocaleString()} symbols, ${stats.files.toLocaleString()} files, ${stats.repositories} repositories indexed`,
+	};
+}
+
 /**
 
 /**