list_files
Retrieve a detailed list of files and subdirectories within a specified directory path using the server's file management capabilities.
Instructions
List all files and subdirectories in a given directory.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| directory_path | Yes | Absolute path to the directory to list |
Implementation Reference
- src/index.ts:490-515 (handler)The execute handler for list_files tool. Validates the directory path, reads the directory contents using fs.readdirSync, determines file/dir type and size, formats output as list.execute: async ({ directory_path }) => { const absolutePath = validateAbsolutePath(directory_path, 'directory_path'); validateDirectoryExists(absolutePath); try { const items = fs.readdirSync(absolutePath); const results: string[] = []; items.forEach(item => { const itemPath = path.join(absolutePath, item); const stats = fs.statSync(itemPath); const type = stats.isDirectory() ? '[DIR]' : '[FILE]'; const size = stats.isFile() ? `(${stats.size} bytes)` : ''; results.push(`${type} ${item} ${size}`.trim()); }); if (results.length === 0) { return `Directory "${absolutePath}" is empty.`; } return results.join('\n'); } catch (error: any) { if (error instanceof UserError) throw error; throw new UserError(`Error listing directory "${absolutePath}": ${error.message}`); } }
- src/index.ts:487-489 (schema)Input schema using Zod: requires absolute directory_path as string.parameters: z.object({ directory_path: z.string().describe('Absolute path to the directory to list') }),
- src/index.ts:484-516 (registration)Registration of the list_files tool via server.addTool, including name, description, schema, and handler.server.addTool({ name: 'list_files', description: 'List all files and subdirectories in a given directory.', parameters: z.object({ directory_path: z.string().describe('Absolute path to the directory to list') }), execute: async ({ directory_path }) => { const absolutePath = validateAbsolutePath(directory_path, 'directory_path'); validateDirectoryExists(absolutePath); try { const items = fs.readdirSync(absolutePath); const results: string[] = []; items.forEach(item => { const itemPath = path.join(absolutePath, item); const stats = fs.statSync(itemPath); const type = stats.isDirectory() ? '[DIR]' : '[FILE]'; const size = stats.isFile() ? `(${stats.size} bytes)` : ''; results.push(`${type} ${item} ${size}`.trim()); }); if (results.length === 0) { return `Directory "${absolutePath}" is empty.`; } return results.join('\n'); } catch (error: any) { if (error instanceof UserError) throw error; throw new UserError(`Error listing directory "${absolutePath}": ${error.message}`); } } });
- src/utils.ts:12-20 (helper)Helper function validateAbsolutePath used in list_files to ensure directory_path is absolute.export function validateAbsolutePath(filePath: string, parameterName: string = 'path'): string { if (!path.isAbsolute(filePath)) { throw new UserError( `The ${parameterName} must be an absolute path. You provided a relative path: "${filePath}". ` + `Please provide the full absolute path (e.g., "/home/user/file.txt" on Linux/Mac or "C:\\Users\\user\\file.txt" on Windows).` ); } return filePath; }
- src/utils.ts:57-80 (helper)Helper function validateDirectoryExists used in list_files to check if the directory exists and is accessible.export function validateDirectoryExists(dirPath: string): void { try { const stats = fs.statSync(dirPath); if (!stats.isDirectory()) { throw new UserError( `The path "${dirPath}" exists but is not a directory. Please ensure you're providing the path to a directory.` ); } } catch (error: any) { if (error.code === 'ENOENT') { throw new UserError( `Directory not found: "${dirPath}". Please verify that the directory exists and the path is correct.` ); } else if (error.code === 'EACCES') { throw new UserError( `Permission denied: Cannot access directory "${dirPath}". Please check directory permissions.` ); } else { throw new UserError( `Error accessing directory "${dirPath}": ${error.message}` ); } } }