list_directory
Lists files and directories at a specified path, with options to include hidden items and perform recursive searches.
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 handler function that executes the list_directory tool logic: validates the directory path, recursively lists files/directories using the helper function, and returns the formatted list as text content.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)Zod input schema defining parameters for the list_directory tool: path (required string), includeHidden (optional boolean), recursive (optional boolean).{ 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:87-113 (registration)Registers the list_directory tool on the MCP server using server.tool(), including schema and handler.function registerListDirectory(server: McpServer): void { 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 traverses directories, filters hidden files if not included, and collects file/directory listings with prefixes.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)Calls registerFileTools which includes registration of list_directory among file tools.registerFileTools(server);