list_directory
Lists files and directories at a specified path, with options to include hidden items and show contents recursively.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| includeHidden | No | ||
| recursive | No |
Implementation Reference
- src/tools/file-tools.ts:94-111 (handler)The main execution handler for the list_directory tool. Validates the directory path, collects listing results using a recursive helper, formats output as text content, and handles errors.async ({ path: dirPath, includeHidden, recursive }) => { return wrapToolExecution(async () => { const validatedPath = await validatePathExists(dirPath); const results: string[] = []; await listDirectoryRecursive(validatedPath, "", includeHidden, recursive, results); return { content: [{ type: "text" as const, text: results.length > 0 ? results.join("\n") : "Directory is empty" }] }; }, { errorCode: ERROR_CODES.FILE_OPERATION, context: "Failed to list directory" }); }
- src/tools/file-tools.ts:89-93 (schema)Input schema using Zod validation for the tool parameters: required path (string), optional includeHidden and recursive (booleans with defaults).{ path: z.string().min(1, "Path is required"), includeHidden: z.boolean().optional().default(DEFAULTS.INCLUDE_HIDDEN_FILES), recursive: z.boolean().optional().default(DEFAULTS.RECURSIVE_SEARCH) },
- src/tools/file-tools.ts:88-112 (registration)Direct registration of the list_directory tool on the McpServer instance, specifying name, input schema, and handler function.server.tool("list_directory", { path: z.string().min(1, "Path is required"), includeHidden: z.boolean().optional().default(DEFAULTS.INCLUDE_HIDDEN_FILES), recursive: z.boolean().optional().default(DEFAULTS.RECURSIVE_SEARCH) }, async ({ path: dirPath, includeHidden, recursive }) => { return wrapToolExecution(async () => { const validatedPath = await validatePathExists(dirPath); const results: string[] = []; await listDirectoryRecursive(validatedPath, "", includeHidden, recursive, results); return { content: [{ type: "text" as const, text: results.length > 0 ? results.join("\n") : "Directory is empty" }] }; }, { errorCode: ERROR_CODES.FILE_OPERATION, context: "Failed to list directory" }); } );
- src/tools/file-tools.ts:118-142 (helper)Recursive helper function that reads directory entries, skips hidden files if specified, formats file/dir listings with prefixes, and collects results in an array.async function listDirectoryRecursive( currentPath: string, baseRelative: string, includeHidden: boolean, recursive: boolean, results: string[] ): Promise<void> { const entries = await readdir(currentPath, { withFileTypes: true }); for (const entry of entries) { if (!includeHidden && entry.name.startsWith('.')) { continue; } const relativePath = path.join(baseRelative, entry.name); const fullPath = path.join(currentPath, entry.name); const prefix = entry.isDirectory() ? "[DIR]" : "[FILE]"; results.push(`${prefix} ${relativePath}`); if (recursive && entry.isDirectory()) { await listDirectoryRecursive(fullPath, relativePath, includeHidden, recursive, results); } } }
- src/index.ts:65-65 (registration)Top-level call to registerFileTools on the MCP server, which includes registration of list_directory among file tools.registerFileTools(server);