Listar Usuários

Instructions

Implementation Reference

• src/clerk-tools.ts:32-73 (handler)

  The core execution logic for the 'list-users' tool. Calls Clerk's getUserList API, processes and maps user data, handles pagination and errors.

  export async function listUsers(params: {
    limit?: number;
    offset?: number;
    orderBy?: 'created_at' | 'updated_at';
  }) {
    try {
      const { limit = 10, offset = 0, orderBy = 'created_at' } = params;
  
      const response = await clerk.users.getUserList({
        limit,
        offset,
        orderBy: orderBy === 'created_at' ? '-created_at' : '-updated_at'
      });
  
      const users = response.data.map(user => ({
        id: user.id,
        email: user.emailAddresses[0]?.emailAddress || null,
        firstName: user.firstName,
        lastName: user.lastName,
        username: user.username,
        createdAt: user.createdAt,
        updatedAt: user.updatedAt,
        locked: user.locked,
        banned: user.banned
      }));
  
      return {
        success: true,
        data: {
          users,
          total: response.totalCount,
          limit,
          offset
        }
      };
    } catch (error: any) {
      return {
        success: false,
        error: error.message || 'Erro ao listar usuários'
      };
    }
  }

• src/clerk-tools.ts:15-19 (schema)

  Input schema validation for the 'list-users' tool using Zod, defining optional pagination and ordering parameters.

  export const listUsersSchema = {
    limit: z.number().min(1).max(100).optional().default(10),
    offset: z.number().min(0).optional().default(0),
    orderBy: z.enum(['created_at', 'updated_at']).optional().default('created_at')
  };

• src/server.ts:28-61 (registration)

  Registration of the 'list-users' tool in the HTTP MCP server, including title, description, input/output schemas, and thin handler wrapper that calls the core listUsers function.

    'list-users',
    {
      title: 'Listar Usuários',
      description: 'Lista todos os usuários cadastrados no Clerk com paginação',
      inputSchema: listUsersSchema,
      outputSchema: {
        success: z.boolean(),
        data: z.object({
          users: z.array(z.object({
            id: z.string(),
            email: z.string().nullable(),
            firstName: z.string().nullable(),
            lastName: z.string().nullable(),
            username: z.string().nullable(),
            createdAt: z.number(),
            updatedAt: z.number(),
            locked: z.boolean(),
            banned: z.boolean()
          })),
          total: z.number(),
          limit: z.number(),
          offset: z.number()
        }).optional(),
        error: z.string().optional()
      }
    },
    async (params) => {
      const result = await listUsers(params);
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        structuredContent: result
      };
    }
  );

• src/server-stdio.ts:26-60 (registration)

  Registration of the 'list-users' tool in the STDIO MCP server, identical to the HTTP version.

  server.registerTool(
    'list-users',
    {
      title: 'Listar Usuários',
      description: 'Lista todos os usuários cadastrados no Clerk com paginação',
      inputSchema: listUsersSchema,
      outputSchema: {
        success: z.boolean(),
        data: z.object({
          users: z.array(z.object({
            id: z.string(),
            email: z.string().nullable(),
            firstName: z.string().nullable(),
            lastName: z.string().nullable(),
            username: z.string().nullable(),
            createdAt: z.number(),
            updatedAt: z.number(),
            locked: z.boolean(),
            banned: z.boolean()
          })),
          total: z.number(),
          limit: z.number(),
          offset: z.number()
        }).optional(),
        error: z.string().optional()
      }
    },
    async (params) => {
      const result = await listUsers(params);
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        structuredContent: result
      };
    }
  );