list_directory

Instructions

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}`);
          }
      }
  }