AiDex

Instructions

Implementation Reference

• src/server/tools.ts:1328-1408 (handler)

  The MCP tool handler for aidex_files that formats and returns file listings grouped by directory with type statistics
  function handleFiles(args: Record<string, unknown>): { content: Array<{ type: string; text: string }> } { const path = args.path as string; if (!path) { return { content: [{ type: 'text', text: 'Error: path parameter is required' }], }; } const result = files({ path, type: args.type as string | undefined, pattern: args.pattern as string | undefined, modifiedSince: args.modified_since as string | undefined, }); if (!result.success) { return { content: [{ type: 'text', text: `Error: ${result.error}` }], }; } if (result.files.length === 0) { return { content: [{ type: 'text', text: 'No files found in project.' }], }; } // Build summary let message = `# Project Files (${result.totalFiles})\n\n`; // Type statistics message += `## By Type\n`; for (const [type, count] of Object.entries(result.byType).sort()) { message += `- **${type}:** ${count}\n`; } message += '\n'; // Group files by directory const byDir = new Map<string, typeof result.files>(); for (const file of result.files) { const dir = file.path.includes('/') ? file.path.substring(0, file.path.lastIndexOf('/')) : '.'; if (!byDir.has(dir)) { byDir.set(dir, []); } byDir.get(dir)!.push(file); } // List files (limit output for large projects) const MAX_ENTRIES = 200; let entriesShown = 0; message += `## Files\n`; for (const [dir, dirFiles] of [...byDir.entries()].sort()) { if (entriesShown >= MAX_ENTRIES) { message += `\n... and ${result.totalFiles - entriesShown} more files\n`; break; } // Show directory if (dir !== '.') { message += `\n📁 ${dir}/\n`; entriesShown++; } // Show files in directory for (const file of dirFiles) { if (entriesShown >= MAX_ENTRIES) break; const fileName = file.path.includes('/') ? file.path.substring(file.path.lastIndexOf('/') + 1) : file.path; const icon = file.type === 'dir' ? '📁' : '📄'; const indexed = file.indexed ? ' ✓' : ''; message += ` ${icon} ${fileName} (${file.type})${indexed}\n`; entriesShown++; } } return { content: [{ type: 'text', text: message.trimEnd() }], }; }
• src/commands/files.ts:47-147 (handler)

  Core implementation of the files command that queries the database for project files with optional filtering by type, pattern, and modified timestamp
  export function files(params: FilesParams): FilesResult { const { path: projectPath, type, pattern, modifiedSince } = params; // Validate project path const dbPath = join(projectPath, INDEX_DIR, 'index.db'); if (!existsSync(dbPath)) { return { success: false, files: [], totalFiles: 0, byType: {}, error: `No ${PRODUCT_NAME} index found at ${projectPath}. Run ${TOOL_PREFIX}init first.`, }; } // Open database const db = openDatabase(dbPath, true); const queries = createQueries(db); try { // Parse time filter const modifiedSinceTs = modifiedSince ? parseTimeOffset(modifiedSince) : null; // If time filter is specified, get recently indexed files from the files table let recentlyIndexedPaths: Set<string> | null = null; let indexedFilesMap: Map<string, FileRow> | null = null; if (modifiedSinceTs !== null) { // Get all indexed files and filter by last_indexed const allIndexedFiles = queries.getAllFiles(); recentlyIndexedPaths = new Set<string>(); indexedFilesMap = new Map<string, FileRow>(); for (const file of allIndexedFiles) { indexedFilesMap.set(file.path, file); if (file.last_indexed >= modifiedSinceTs) { recentlyIndexedPaths.add(file.path); } } } // Get files, optionally filtered by type let projectFiles: ProjectFileRow[]; if (type && isValidType(type)) { projectFiles = queries.getProjectFilesByType(type as ProjectFileRow['type']); } else { projectFiles = queries.getProjectFiles(); } // Apply glob pattern filter if specified if (pattern) { const regex = globToRegex(pattern); projectFiles = projectFiles.filter(f => regex.test(f.path)); } // Apply time filter if specified (only show files indexed after the timestamp) if (recentlyIndexedPaths !== null) { projectFiles = projectFiles.filter(f => recentlyIndexedPaths!.has(f.path)); } // Build type statistics const byType: Record<string, number> = {}; for (const file of projectFiles) { byType[file.type] = (byType[file.type] || 0) + 1; } // Convert to output format const result: ProjectFile[] = projectFiles.map(f => { const indexed = f.indexed === 1; const indexedFile = indexedFilesMap?.get(f.path); return { path: f.path, type: f.type, extension: f.extension, indexed, lastIndexed: indexedFile?.last_indexed, }; }); db.close(); return { success: true, files: result, totalFiles: result.length, byType, }; } catch (error) { db.close(); return { success: false, files: [], totalFiles: 0, byType: {}, error: error instanceof Error ? error.message : String(error), }; } }
• src/server/tools.ts:317-342 (registration)

  MCP tool registration for aidex_files with its input schema defining parameters for path, type, pattern, and modified_since filtering
  name: `${TOOL_PREFIX}files`, description: 'List all files and directories in the indexed project. Returns the complete project structure with file types (code, config, doc, asset, test, other) and whether each file is indexed for code search. Use modified_since to find files changed in this session.', inputSchema: { type: 'object', properties: { path: { type: 'string', description: `Path to project with ${INDEX_DIR} directory`, }, type: { type: 'string', enum: ['dir', 'code', 'config', 'doc', 'asset', 'test', 'other'], description: 'Filter by file type', }, pattern: { type: 'string', description: 'Glob pattern to filter files (e.g., "src/**/*.ts")', }, modified_since: { type: 'string', description: 'Only files indexed after this time. Supports: "2h", "30m", "1d", "1w", or ISO date. Use to find files changed this session.', }, }, required: ['path'], }, },
• src/server/tools.ts:606-607 (registration)

  Handler routing that maps the aidex_files tool name to the handleFiles function in the tool call dispatcher
  case `${TOOL_PREFIX}files`: return handleFiles(args);
• src/commands/files.ts:20-41 (schema)

  Type definitions for the files command including input parameters (FilesParams), output file data (ProjectFile), and result structure (FilesResult)
  export interface FilesParams { path: string; type?: string; // Filter by type: dir, code, config, doc, asset, test, other pattern?: string; // Glob pattern filter modifiedSince?: string; // Only files indexed after this time (2h, 30m, 1d, 1w, or ISO date) } export interface ProjectFile { path: string; type: string; extension: string | null; indexed: boolean; lastIndexed?: number; // Timestamp when file was last indexed (only for code files) } export interface FilesResult { success: boolean; files: ProjectFile[]; totalFiles: number; byType: Record<string, number>; error?: string; }