fs_list_directory
List directory contents with detailed file information including type, size, and permissions for development environment navigation and file management.
Instructions
List contents of a directory with detailed information about each entry (name, type, size, permissions, etc.)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute or relative path to the directory | |
| recursive | No | List subdirectories recursively | |
| showHidden | No | Show hidden files (starting with .) |
Implementation Reference
- src/tools/filesystem.ts:206-275 (handler)The core handler function that executes the fs_list_directory tool: reads directory entries, computes stats, supports recursive listing and hidden file filtering, returns JSON-formatted directory listing.export async function listDirectory(args: z.infer<typeof listDirectorySchema>): Promise<ToolResponse> { try { const entries = await fs.readdir(args.path, { withFileTypes: true }); let files: any[] = []; for (const entry of entries) { // Skip hidden files if not requested if (!args.showHidden && entry.name.startsWith('.')) { continue; } const fullPath = path.join(args.path, entry.name); const stats = await fs.stat(fullPath); const fileInfo = { name: entry.name, path: fullPath, type: entry.isDirectory() ? 'directory' : entry.isSymbolicLink() ? 'symlink' : 'file', size: stats.size, modified: stats.mtime, permissions: stats.mode }; files.push(fileInfo); // Recurse into subdirectories if requested if (args.recursive && entry.isDirectory()) { const subResult = await listDirectory({ path: fullPath, recursive: true, showHidden: args.showHidden }); // Parse the sub-result and add to files const subData = JSON.parse(subResult.content[0].text); if (subData.success) { files = files.concat(subData.entries); } } } return { content: [ { type: "text" as const, text: JSON.stringify({ success: true, path: args.path, count: files.length, entries: files }, null, 2) } ] }; } catch (error) { return { content: [ { type: "text" as const, text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2) } ], isError: true }; } }
- src/tools/filesystem.ts:35-39 (schema)Zod input validation schema for the fs_list_directory tool parameters.export const listDirectorySchema = z.object({ path: z.string().describe('Absolute or relative path to the directory'), recursive: z.boolean().default(false).describe('List subdirectories recursively'), showHidden: z.boolean().default(false).describe('Show hidden files (starting with .)') });
- src/tools/filesystem.ts:542-565 (registration)MCP tool definition object for 'fs_list_directory' (part of filesystemTools array), including name, description, and inputSchema; used in listTools response for tool discovery.{ name: 'fs_list_directory', description: 'List contents of a directory with detailed information about each entry (name, type, size, permissions, etc.)', inputSchema: { type: 'object', properties: { path: { type: 'string', description: 'Absolute or relative path to the directory' }, recursive: { type: 'boolean', default: false, description: 'List subdirectories recursively' }, showHidden: { type: 'boolean', default: false, description: 'Show hidden files (starting with .)' } }, required: ['path'] } },
- src/index.ts:321-324 (handler)Dispatch handler in main server: validates input using listDirectorySchema and calls the listDirectory implementation for fs_list_directory tool calls.if (name === 'fs_list_directory') { const validated = listDirectorySchema.parse(args); return await listDirectory(validated); }
- src/index.ts:284-296 (registration)Server request handler for listing tools; includes filesystemTools (containing fs_list_directory definition) in the response, effectively registering the tool.this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ ...filesystemTools, ...shellTools, ...dockerTools, ...mongodbTools, ...redisTools, ...gitTools, ...processTools, ...networkTools ] };