Litelead-mcp

getUserById Tool

Overview

The getUserById tool retrieves a single user record by its document ID from the Firebase/Firestore database.

Location

tools/getUserById.js

Description

Retrieves a specific user by document ID. The user is retrieved from the Firestore path: /Accounts/{accountId}/Users/{userId}.

Input Schema

{
  userId: string;  // REQUIRED: User document ID
}

Parameters

Parameter Type Required Default Description
userId string Yes - Firestore document ID of the user

Output Schema

{
  user: User | null;
}

User Object

{
  id: string;                    // Firestore document ID
  path: string;                  // Full Firestore path
  userId: number;                // Unique user ID
  email: string;                 // User email address
  name: string;                  // User name
  role: string;                  // Role reference or ID
  active: boolean;               // Whether user is active
  // ... other user fields
}

Usage Examples

Basic Usage

// Get a specific user by ID
const result = await getUserById(context, {
  userId: "user123"
});

if (result.user) {
  console.log(result.user.name);     // User name
  console.log(result.user.email);    // User email
} else {
  console.log("User not found");
}

Checking User Status

const result = await getUserById(context, {
  userId: "user123"
});

if (result.user) {
  if (result.user.active) {
    console.log(`${result.user.name} (${result.user.email}) is active`);
  } else {
    console.log(`${result.user.name} is inactive`);
  }
} else {
  console.log("User does not exist");
}

Implementation Details

Data Transformation

The tool transforms the Firestore document by:

  1. Adding the document id and full path
  2. Preserving all other fields as-is
return {
  user: {
    id: docSnap.id,
    path: docSnap.ref.path,
    ...docSnap.data(),
  },
};

Validation

The tool validates that userId is provided:

if (!userId) {
  throw new Error("The 'userId' parameter is required.");
}

Not Found Handling

If the user document doesn’t exist, the tool returns { user: null } instead of throwing an error.

Error Handling

Common Errors

Error Cause Solution
“The ‘userId’ parameter is required.” Missing userId Provide userId in params
“Failed to fetch user with id [id].” Firestore error Check Firebase connection and permissions

Error Response

Errors are logged with the user ID and re-thrown:

catch (error) {
  console.error(`Error fetching user with id ${userId}:`, error);
  throw new Error(`Failed to fetch user with id ${userId}.`);
}

Performance Considerations

  1. Direct Document Access: Uses getDoc() for efficient single document retrieval
  2. No Pagination: This is a single-document fetch, no pagination overhead
  3. Indexed Reads: Document ID lookups are always indexed

Firestore Collection Structure

/Accounts/{accountId}/Users/{userId}
  - userId: number
  - email: string
  - name: string
  - role: string
  - active: boolean

See Also