File System Explorer MCP Server

Instructions

Implementation Reference

• src/index.ts:216-268 (handler)

  The main execution logic for the list_directory tool within the CallToolRequestSchema handler. Parses arguments using the schema, validates and lists directory contents with file types, sizes, and modification times, formats output with icons.

  case "list_directory": {
    const { path: dirPath } = ListDirectoryArgsSchema.parse(args);
    const safePath = validatePath(dirPath);
    
    const entries = await fs.readdir(safePath, { withFileTypes: true });
    const items = await Promise.all(
      entries.map(async (entry) => {
        const fullPath = path.join(safePath, entry.name);
        try {
          const stats = await fs.stat(fullPath);
          return {
            name: entry.name,
            type: entry.isDirectory() ? 'directory' : 'file',
            size: entry.isFile() ? formatFileSize(stats.size) : null,
            modified: stats.mtime.toISOString()
          };
        } catch (error) {
          return {
            name: entry.name,
            type: entry.isDirectory() ? 'directory' : 'file',
            size: null,
            modified: null,
            error: 'Unable to read stats'
          };
        }
      })
    );
  
    return {
      content: [
        {
          type: "text",
          text: `Directory listing for: ${safePath}\n\n` +
                items
                  .sort((a, b) => {
                    // Sort directories first, then files
                    if (a.type !== b.type) {
                      return a.type === 'directory' ? -1 : 1;
                    }
                    return a.name.localeCompare(b.name);
                  })
                  .map(item => {
                    const icon = item.type === 'directory' ? '📁' : '📄';
                    const size = item.size ? ` (${item.size})` : '';
                    const modified = item.modified ? 
                      ` - Modified: ${new Date(item.modified).toLocaleString()}` : '';
                    return `${icon} ${item.name}${size}${modified}`;
                  })
                  .join('\n')
        }
      ]
    };
  }

• src/index.ts:32-34 (schema)

  Zod schema defining the input validation for list_directory tool arguments, specifically the 'path' parameter.

  const ListDirectoryArgsSchema = z.object({
    path: z.string().describe("The directory path to list")
  });

• src/index.ts:144-157 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and input schema for list_directory.

  {
    name: "list_directory",
    description: "List the contents of a directory",
    inputSchema: {
      type: "object",
      properties: {
        path: {
          type: "string",
          description: "The directory path to list"
        }
      },
      required: ["path"]
    }
  },