list_directory
Retrieve a structured listing of files and directories within a specified path, marked with [FILE] and [DIR] prefixes. Use this tool to analyze directory structures and locate specific items efficiently within permitted directories.
Instructions
Get a detailed listing of all files and directories in a specified path. Results clearly distinguish between files and directories with [FILE] and [DIR] prefixes. This tool is essential for understanding directory structure and finding specific files within a directory. Only works within allowed directories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path of the directory to list |
Implementation Reference
- src/index.ts:490-518 (handler)Handler for the list_directory tool: parses arguments, validates path access, reads directory contents using fs.readdir with file types, sorts entries (directories first alphabetically, then files), formats output with [DIR] or [FILE] prefixes, logs the operation, and returns formatted text content.
case 'list_directory': { const parsed = ListDirectoryArgsSchema.safeParse(a) if (!parsed.success) { throw new FileSystemError(`Invalid arguments for ${name}`, 'INVALID_ARGS', undefined, { errors: parsed.error.format(), }) } const validPath = await validatePath(parsed.data.path, config) const entries = await fs.readdir(validPath, { withFileTypes: true }) // Sort directories first, then files, both alphabetically entries.sort((c, d) => { if (c.isDirectory() && !d.isDirectory()) return -1 if (!c.isDirectory() && d.isDirectory()) return 1 return c.name.localeCompare(d.name) }) const formatted = entries .map((entry) => `${entry.isDirectory() ? '[DIR]' : '[FILE]'} ${entry.name}`) .join('\n') await logger.debug(`Listed directory: ${validPath}`, { entryCount: entries.length }) endMetric() return { content: [{ type: 'text', text: formatted }], } } - src/index.ts:120-122 (schema)Zod schema for list_directory tool input, requiring a 'path' string parameter.
const ListDirectoryArgsSchema = z.object({ path: z.string().describe('Path of the directory to list'), }) - src/index.ts:279-287 (registration)Tool registration in the ListTools response: defines name, detailed description, and references the input schema.
{ name: 'list_directory', description: 'Get a detailed listing of all files and directories in a specified path. ' + 'Results clearly distinguish between files and directories with [FILE] and [DIR] ' + 'prefixes. This tool is essential for understanding directory structure and ' + 'finding specific files within a directory. Only works within allowed directories.', inputSchema: zodToJsonSchema(ListDirectoryArgsSchema) as ToolInput, },