mcp-adr-analysis-server
Version:
MCP server for analyzing Architectural Decision Records and project architecture
148 lines • 4.82 kB
TypeScript
/**
* Search Codebase Tool
*
* Atomic tool for searching codebase files based on query patterns.
* Extracted from ResearchOrchestrator per ADR-018 (Atomic Tools Architecture).
*
* This tool provides dependency-injected codebase search functionality:
* - Returns raw data (matches, files) without analysis/conclusions
* - Supports configurable file system and analyzer dependencies
* - No LLM calls or orchestration logic
* - Testable without complex ESM mocking
*
* @see ResearchOrchestrator (deprecated) - Full multi-source orchestration
* @since 3.0.0
* @category Tools
* @category Research
*/
import { promises as fs } from 'fs';
import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
import type { TreeSitterAnalyzer } from '../utils/tree-sitter-analyzer.js';
/**
* File match result with relevance scoring
*/
export interface FileMatch {
/** Full path to the file */
path: string;
/** File content (if includeContent was true) */
content?: string;
/** Relevance score 0-1 */
relevance: number;
/** Tree-sitter parse analysis (if available) */
parseAnalysis?: {
language: string;
hasInfrastructure: boolean;
functionCount: number;
importCount: number;
};
}
/**
* Codebase search result
*/
export interface CodebaseSearchResult {
/** Array of matching files with relevance scores */
matches: FileMatch[];
/** Total number of files discovered */
totalFiles: number;
/** Keywords extracted from query */
keywords: string[];
/** Project path searched */
projectPath: string;
/** Search duration in milliseconds */
duration: number;
}
/**
* Dependencies for search_codebase function (injectable for testing)
*/
export interface SearchCodebaseDependencies {
/** File system operations */
fs: typeof fs;
/** Tree-sitter analyzer (optional) */
analyzer?: TreeSitterAnalyzer;
}
/**
* Default dependencies for production use
*/
export declare const defaultDeps: SearchCodebaseDependencies;
/**
* Minimum relevance threshold for including files in results (0-1)
* Files with relevance below this threshold will be filtered out
*/
export declare const DEFAULT_RELEVANCE_THRESHOLD = 0.2;
/**
* Search codebase for files matching query
*
* @description Atomic tool that searches project files based on query patterns.
* Returns raw file matches with relevance scores. Does NOT perform LLM analysis
* or synthesis - returns structured data only.
*
* Search strategy:
* 1. Extract keywords from query
* 2. Use scanProjectStructure for intent-based file discovery (Docker, K8s, etc.)
* 3. Use findFiles for glob-based keyword matching
* 4. Read and score file relevance (optional tree-sitter enhancement)
* 5. Return sorted results
*
* @param args - Search parameters
* @param args.query - Search query (e.g., "Docker configuration", "authentication")
* @param args.projectPath - Path to project root (defaults to cwd)
* @param args.scope - Optional file scope patterns (e.g., ["src/**", "config/**"])
* @param args.includeContent - Include file content in results (default: false)
* @param args.maxFiles - Maximum files to return (default: 20)
* @param args.enableTreeSitter - Use tree-sitter for enhanced analysis (default: true)
* @param deps - Injectable dependencies (for testing)
*
* @returns Promise<CodebaseSearchResult> Raw search results with matches and scores
*
* @throws {McpAdrError} When query is empty or search fails
*
* @example
* ```typescript
* // Basic search
* const result = await searchCodebase({
* query: "Docker configuration",
* projectPath: "/path/to/project"
* });
*
* console.log(`Found ${result.matches.length} files`);
* result.matches.forEach(match => {
* console.log(`${match.path}: ${(match.relevance * 100).toFixed(1)}%`);
* });
* ```
*
* @example
* ```typescript
* // Search with content and custom scope
* const result = await searchCodebase({
* query: "authentication methods",
* scope: ["src/**", "lib/**"],
* includeContent: true,
* maxFiles: 10
* });
* ```
*
* @since 3.0.0
* @category Research
* @category Atomic Tools
*/
export declare function searchCodebase(args: {
query: string;
projectPath?: string;
scope?: string[];
includeContent?: boolean;
maxFiles?: number;
enableTreeSitter?: boolean;
relevanceThreshold?: number;
}, deps?: SearchCodebaseDependencies): Promise<CodebaseSearchResult>;
/**
* MCP tool wrapper for search_codebase
*/
export declare function searchCodebaseTool(args: {
query: string;
projectPath?: string;
scope?: string[];
includeContent?: boolean;
maxFiles?: number;
enableTreeSitter?: boolean;
}): Promise<CallToolResult>;
//# sourceMappingURL=search-codebase-tool.d.ts.map