list_directory
View all files and folders in a specific directory path, with clear labels to distinguish between files [FILE] and directories [DIR].
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 that implements the 'list_directory' tool logic. It validates the input path for security restrictions, reads the directory entries, and returns formatted list distinguishing files [FILE] and directories [DIR].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 input schema for the 'list_directory' tool, validating a single 'path' parameter.export const ListDirectoryArgsSchema = z.object({ path: z.string(), });
- src/server.ts:157-162 (registration)Tool registration in the MCP server's ListTools handler, defining name, description, and input schema for 'list_directory'.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)Server-side dispatch handler for the 'list_directory' tool call, parsing args, invoking the handler, and formatting 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)Security helper function used by listDirectory to validate paths are within allowed directories, handles symlinks and non-existent files.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}`); } } }