fs_list_directory

Instructions

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
      ]
    };