list_directory
View all files and directories in a specified path with clear [FILE] and [DIR] labels to distinguish content types within allowed directories.
Instructions
Get a detailed listing of all files and directories in a specified path. Results distinguish between files and directories with [FILE] and [DIR] prefixes. Only works within allowed directories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Implementation Reference
- src/tools/filesystem.ts:95-99 (handler)The core handler function for the list_directory tool. It validates the path, reads directory entries using fs.readdir with file types, and formats each entry as [DIR] or [FILE] followed by the name.export async function listDirectory(dirPath: string): Promise<string[]> { const validPath = await validatePath(dirPath); const entries = await fs.readdir(validPath, { withFileTypes: true }); return entries.map((entry) => `${entry.isDirectory() ? "[DIR]" : "[FILE]"} ${entry.name}`); }
- src/tools/schemas.ts:49-51 (schema)Zod schema defining the input for list_directory: an object with a required 'path' string.export const ListDirectoryArgsSchema = z.object({ path: z.string(), });
- src/server.ts:156-163 (registration)Registration of the list_directory tool in the ListToolsRequestHandler, providing name, description, and input schema.{ name: "list_directory", description: "Get a detailed listing of all files and directories in a specified path. " + "Results distinguish between files and directories with [FILE] and [DIR] prefixes. " + "Only works within allowed directories.", inputSchema: zodToJsonSchema(ListDirectoryArgsSchema), },
- src/server.ts:294-300 (registration)Dispatch logic in CallToolRequestHandler: parses arguments using the schema and invokes the listDirectory handler, formatting the response.case "list_directory": { const parsed = ListDirectoryArgsSchema.parse(args); const entries = await listDirectory(parsed.path); return { content: [{ type: "text", text: entries.join('\n') }], }; }
- src/tools/filesystem.ts:24-62 (helper)Shared helper function validatePath used by listDirectory (and other filesystem tools) to ensure paths are within allowed directories, handling symlinks and non-existent files securely.export async function validatePath(requestedPath: string): Promise<string> { const expandedPath = expandHome(requestedPath); const absolute = path.isAbsolute(expandedPath) ? path.resolve(expandedPath) : path.resolve(process.cwd(), expandedPath); const normalizedRequested = normalizePath(absolute); // Check if path is within allowed directories const isAllowed = allowedDirectories.some(dir => normalizedRequested.startsWith(normalizePath(dir))); if (!isAllowed) { throw new Error(`Access denied - path outside allowed directories: ${absolute}`); } // Handle symlinks by checking their real path try { const realPath = await fs.realpath(absolute); const normalizedReal = normalizePath(realPath); const isRealPathAllowed = allowedDirectories.some(dir => normalizedReal.startsWith(normalizePath(dir))); if (!isRealPathAllowed) { throw new Error("Access denied - symlink target outside allowed directories"); } return realPath; } catch (error) { // For new files that don't exist yet, verify parent directory const parentDir = path.dirname(absolute); try { const realParentPath = await fs.realpath(parentDir); const normalizedParent = normalizePath(realParentPath); const isParentAllowed = allowedDirectories.some(dir => normalizedParent.startsWith(normalizePath(dir))); if (!isParentAllowed) { throw new Error("Access denied - parent directory outside allowed directories"); } return absolute; } catch { throw new Error(`Parent directory does not exist: ${parentDir}`); } } }