FileScopeMCP

Instructions

Implementation Reference

• src/file-utils.ts:763-788 (handler)

  Primary handler function for the 'create_file_tree' tool. Normalizes the input base directory and orchestrates the scanning process to build and return the complete FileNode tree structure.
  export async function createFileTree(baseDir: string): Promise<FileNode> { const normalizedBaseDir = path.normalize(baseDir); const nodes = await scanDirectory(normalizedBaseDir); // The first node should be the root directory if (nodes.isDirectory && nodes.path === normalizedBaseDir) { return nodes; } // If for some reason we didn't get a root node, create one const rootNode: FileNode = { path: normalizedBaseDir, name: path.basename(normalizedBaseDir), isDirectory: true, children: [] }; // Add all nodes that don't have a parent for (const node of nodes.children || []) { if (path.dirname(node.path) === normalizedBaseDir) { rootNode.children?.push(node); } } return rootNode; }
• src/file-utils.ts:409-625 (helper)

  Core helper function that recursively scans directories, applies exclusion rules, extracts import dependencies, analyzes package dependencies, calculates file importance scores, and constructs the hierarchical FileNode tree.
  export async function scanDirectory(baseDir: string, currentDir: string = baseDir): Promise<FileNode> { log(`\n📁 SCAN DIRECTORY: ${currentDir}`); log(` - Base dir: ${baseDir}`); // Handle special case for current directory const normalizedBaseDir = path.normalize(baseDir); const normalizedDirPath = path.normalize(currentDir); log(` - Normalized base dir: ${normalizedBaseDir}`); log(` - Normalized current dir: ${normalizedDirPath}`); // Create root node for this directory const rootNode: FileNode = { path: normalizedDirPath, name: path.basename(normalizedDirPath), isDirectory: true, children: [] }; // Read directory entries let entries: fs.Dirent[]; try { entries = await fsPromises.readdir(normalizedDirPath, { withFileTypes: true }); log(` - Read ${entries.length} entries in directory`); } catch (error) { log(` - ❌ Error reading directory ${normalizedDirPath}:`, error); return rootNode; } // Process each entry let excluded = 0; let included = 0; let dirProcessed = 0; let fileProcessed = 0; log(`\n Processing ${entries.length} entries in ${normalizedDirPath}...`); // ==================== CRITICAL CODE ==================== // Log the global config status before processing entries log(`\n🔍 BEFORE PROCESSING: Is config loaded? ${getConfig() !== null ? 'YES ✅' : 'NO ❌'}`); if (getConfig()) { const excludePatternsLength = getConfig()?.excludePatterns?.length || 0; log(` - Exclude patterns count: ${excludePatternsLength}`); if (excludePatternsLength > 0) { log(` - First few patterns: ${getConfig()?.excludePatterns?.slice(0, 3).join(', ')}`); } } // ====================================================== for (const entry of entries) { const fullPath = path.join(normalizedDirPath, entry.name); const normalizedFullPath = path.normalize(fullPath); log(`\n Entry: ${entry.name} (${entry.isDirectory() ? 'directory' : 'file'})`); log(` - Full path: ${normalizedFullPath}`); // Here's the critical exclusion check log(` 🔍 Checking if path should be excluded: ${normalizedFullPath}`); const shouldExclude = isExcluded(normalizedFullPath, normalizedBaseDir); log(` 🔍 Exclusion check result: ${shouldExclude ? 'EXCLUDE ✅' : 'INCLUDE ❌'}`); if (shouldExclude) { log(` - ✅ Skipping excluded path: ${normalizedFullPath}`); excluded++; continue; } log(` - ✅ Including path: ${normalizedFullPath}`); included++; if (entry.isDirectory()) { log(` - Processing directory: ${normalizedFullPath}`); const childNode = await scanDirectory(normalizedBaseDir, fullPath); rootNode.children?.push(childNode); dirProcessed++; } else { log(` - Processing file: ${normalizedFullPath}`); fileProcessed++; const ext = path.extname(entry.name); const importPattern = IMPORT_PATTERNS[ext]; const dependencies: string[] = []; const packageDependencies: PackageDependency[] = []; if (importPattern) { try { const content = await fsPromises.readFile(fullPath, 'utf-8'); const matches = content.match(importPattern); log(`Found ${matches?.length || 0} potential imports in ${normalizedFullPath}`); if (matches) { for (const match of matches) { const importPath = extractImportPath(match); if (importPath) { // Skip if the importPath looks like an unresolved template literal if (isUnresolvedTemplateLiteral(importPath)) { log(`Skipping unresolved template literal: ${importPath}`); continue; } try { let resolvedPath; if (['.js', '.jsx', '.ts', '.tsx'].includes(ext)) { resolvedPath = resolveImportPath(importPath, normalizedFullPath, normalizedBaseDir); } else { resolvedPath = path.resolve(path.dirname(fullPath), importPath); } log(`Resolved path: ${resolvedPath}`); // Handle package imports if (resolvedPath.includes('node_modules') || importPath.startsWith('@') || (!importPath.startsWith('.') && !importPath.startsWith('/'))) { // Create a package dependency object with more information const pkgDep = PackageDependency.fromPath(resolvedPath); // Set the package name directly from the import path if it's empty if (!pkgDep.name) { // Skip if the importPath looks like an unresolved template literal if (isUnresolvedTemplateLiteral(importPath)) { log(`Skipping package dependency with template literal name: ${importPath}`); continue; } // For imports like '@scope/package' if (importPath.startsWith('@')) { const parts = importPath.split('/'); if (parts.length >= 2) { pkgDep.scope = parts[0]; pkgDep.name = `${parts[0]}/${parts[1]}`; } } // For imports like 'package' else if (importPath.includes('/')) { pkgDep.name = importPath.split('/')[0]; } else { pkgDep.name = importPath; } } // Skip if the resolved package name is a template literal if (isUnresolvedTemplateLiteral(pkgDep.name)) { log(`Skipping package with template literal name: ${pkgDep.name}`); continue; } // Try to extract version information if (pkgDep.name) { const version = await extractPackageVersion(pkgDep.name, normalizedBaseDir); if (version) { pkgDep.version = version; } // Check if it's a dev dependency try { const packageJsonPath = path.join(normalizedBaseDir, 'package.json'); const content = await fsPromises.readFile(packageJsonPath, 'utf-8'); const packageData = JSON.parse(content); if (packageData.devDependencies && packageData.devDependencies[pkgDep.name]) { pkgDep.isDevDependency = true; } } catch (error) { // Ignore package.json errors } } packageDependencies.push(pkgDep); continue; } // Try with different extensions for TypeScript/JavaScript files const possibleExtensions = ['.ts', '.tsx', '.js', '.jsx', '']; for (const extension of possibleExtensions) { const pathToCheck = resolvedPath + extension; try { await fsPromises.access(pathToCheck); log(`Found existing path: ${pathToCheck}`); dependencies.push(pathToCheck); break; } catch { // File doesn't exist with this extension, try next one } } } catch (error) { log(`Failed to resolve path for ${importPath}:`, error); } } } } } catch (error) { log(`Failed to read or process file ${fullPath}:`, error); } } const fileNode: FileNode = { path: normalizedFullPath, name: entry.name, isDirectory: false, importance: calculateInitialImportance(normalizedFullPath, normalizedBaseDir), dependencies: dependencies, packageDependencies: packageDependencies, dependents: [], summary: undefined }; rootNode.children?.push(fileNode); } } // Log summary for this directory log(`\n 📊 DIRECTORY SCAN SUMMARY for ${normalizedDirPath}:`); log(` - Total entries: ${entries.length}`); log(` - Excluded: ${excluded}`); log(` - Included: ${included}`); log(` - Directories processed: ${dirProcessed}`); log(` - Files processed: ${fileProcessed}`); log(` 📁 END SCAN DIRECTORY: ${currentDir}\n`); return rootNode; }
• src/types.ts:24-35 (schema)

  FileNode class defines the data structure used for representing files and directories in the file tree output of the create_file_tree tool.
  export class FileNode { path: string = ''; name: string = ''; isDirectory: boolean = false; children?: FileNode[]; dependencies?: string[]; // Outgoing dependencies (local files this file imports) packageDependencies?: PackageDependency[]; // Outgoing dependencies (package files this file imports) dependents?: string[]; // Incoming dependencies (files that import this file) importance?: number; // 0-10 scale summary?: string; // Human-readable summary of the file mermaidDiagram?: MermaidDiagram; // Optional Mermaid diagram for this node }