Litelead-mcp

getUsers Tool

Overview

The getUsers tool retrieves user account records from the Firebase/Firestore database with support for pagination and sorting.

Location

tools/getUsers.js

Description

Retrieves users for the authenticated account with cursor-based pagination support. Users represent account members with specific roles and permissions. Users are retrieved from the Firestore path: /Accounts/{accountId}/Users.

Input Schema

{
  limit?: number;                    // Number of records to retrieve (1-100, default: 50)
  cursor?: string;                   // Document ID for cursor-based pagination
  orderBy?: string;                  // Field to order by (default: "email")
  orderDirection?: "asc" | "desc";   // Sort direction (default: "asc")
  cursorDirection?: "next" | "previous";  // Direction for pagination (default: "next")
  includeTotal?: boolean;            // Include total count of all users (default: false)
}

Parameters

Parameter Type Required Default Description
limit number No 50 Maximum number of users to return (1-100)
cursor string No - Document ID to start pagination from
orderBy string No “email” Field name to sort by
orderDirection enum No “asc” Sort direction: “asc” or “desc”
cursorDirection enum No “next” Pagination direction: “next” or “previous”
includeTotal boolean No false Whether to include total count (expensive)

Output Schema

{
  users: User[];
  pagination: PaginationMetadata;
}

User Object

{
  id: string;                    // Firestore document ID
  path: string;                  // Full Firestore path
  email: string;                 // User email address
  name: string | null;           // User display name
  permissions: string[];         // Array of permission strings
  readonly: boolean;             // Whether user has read-only access (default: false)
  role: string;                  // User role identifier
  uid: string;                   // Firebase Authentication UID
}

Pagination Metadata

{
  limit: number;                 // Applied limit
  hasMore: boolean;              // Whether more results exist
  nextCursor: string | null;     // Cursor for next page
  previousCursor: string | null; // Cursor for previous page
  total?: number | null;         // Total count (if includeTotal was true)
}

Usage Examples

Basic Usage

// Get first 10 users
const result = await getUsers(context, {
  limit: 10
});

console.log(result.users);         // Array of 10 users
console.log(result.pagination);    // Pagination metadata

Paginated Retrieval

// First page
const page1 = await getUsers(context, {
  limit: 20,
  orderBy: "email",
  orderDirection: "asc"
});

// Next page
const page2 = await getUsers(context, {
  limit: 20,
  cursor: page1.pagination.nextCursor,
  cursorDirection: "next"
});

Sort by Name

// Get users sorted by name
const result = await getUsers(context, {
  limit: 10,
  orderBy: "name",
  orderDirection: "asc"
});

Filter by Role (Client-Side)

// Get all users and filter by role
const result = await getUsers(context, { limit: 100 });
const admins = result.users.filter(user => user.role === "admin");
const readOnlyUsers = result.users.filter(user => user.readonly);

With Total Count

const result = await getUsers(context, {
  limit: 10,
  includeTotal: true
});

console.log(`Account has ${result.pagination.total} total users`);

Implementation Details

Data Transformation

The tool transforms Firestore documents by:

  1. Adding the document id and full path
  2. Preserving all other fields as-is
const transformUser = (doc) => ({
  id: doc.id,
  path: doc.ref.path,
  ...doc.data(),
});

Default Ordering

By default, users are ordered by email in ascending order for consistent alphabetical listing.

Permissions Array

The permissions field contains an array of permission strings that define what actions the user can perform. Common permissions include:

Error Handling

Common Errors

Error Cause Solution
“Error fetching users: [message]” Firestore query failed Check Firebase connection and permissions
“Failed to fetch users.” Query error Verify authentication and account access
Validation error Invalid input parameters Ensure parameters match the input schema

Error Response

Errors are logged and a generic error message is thrown:

catch (error) {
  console.error("Error fetching users:", error);
  throw new Error("Failed to fetch users.");
}

Performance Considerations

  1. Limit Size: Keep limit between 1-100 for optimal performance
  2. Total Count: Setting includeTotal: true requires an additional query
  3. Sorting: Email sorting is efficient as it’s typically indexed
  4. User Count: Most accounts have fewer than 100 users, making full retrieval feasible

Firestore Collection Structure

/Accounts/{accountId}/Users/{userId}
  - email: string
  - name: string | null
  - permissions: string[]
  - readonly: boolean
  - role: string
  - uid: string

Use Cases

  1. User Management: List all users in an account for administration
  2. Permission Checking: Retrieve user permissions for access control
  3. Team Overview: Display team members with their roles
  4. Audit Logging: Track which users have access to the account
  5. User Selection: Provide user lists for assignment dropdowns

See Also