Litelead-mcp

getStaffById Tool

Overview

The getStaffById tool retrieves a single staff member record by its document ID from the Firebase/Firestore database.

Location

tools/getStaffById.js

Description

Retrieves a specific staff member by document ID. The staff member is retrieved from the Firestore path: /Accounts/{accountId}/Staff/{staffId}.

Input Schema

{
  staffId: string;  // REQUIRED: Staff document ID
}

Parameters

Parameter Type Required Default Description
staffId string Yes - Firestore document ID of the staff member

Output Schema

{
  staff: Staff | null;
}

Staff Object

{
  id: string;                    // Firestore document ID
  path: string;                  // Full Firestore path
  active?: boolean;              // Whether the staff member is active
  createdAt?: string | null;     // Creation timestamp (locale string)
  createdBy?: string;            // ID of the user who created this record
  email?: string;                // Staff member email (optional)
  mobilePhone?: string;          // Mobile phone number
  name?: string;                 // Staff member name (optional)
  ownedBy?: string;              // Owner ID
  phone?: string;                // Landline phone number
}

Usage Examples

Basic Usage

// Get a specific staff member by ID
const result = await getStaffById(context, {
  staffId: "staff123"
});

if (result.staff) {
  console.log(result.staff.name);    // Staff member name
  console.log(result.staff.email);   // Staff member email
} else {
  console.log("Staff member not found");
}

Checking Staff Status

const result = await getStaffById(context, {
  staffId: "staff123"
});

if (result.staff) {
  if (result.staff.active) {
    console.log(`${result.staff.name} is active`);
  } else {
    console.log(`${result.staff.name} is inactive`);
  }
} else {
  console.log("Staff member 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 {
  staff: {
    id: docSnap.id,
    path: docSnap.ref.path,
    ...docSnap.data(),
  },
};

Validation

The tool validates that staffId is provided:

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

Not Found Handling

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

Error Handling

Common Errors

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

Error Response

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

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

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}/Staff/{staffId}
  - staffId: number
  - name: string
  - email: string
  - role: string
  - active: boolean

See Also