Litelead-mcp

getRoleById Tool

Overview

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

Location

tools/getRoleById.js

Description

Retrieves a specific role by document ID. The role is retrieved from the Firestore path: /Accounts/{accountId}/Roles/{roleId}.

Input Schema

{
  roleId: string;  // REQUIRED: Role document ID
}

Parameters

Parameter Type Required Default Description
roleId string Yes - Firestore document ID of the role

Output Schema

{
  role: Role | null;
}

Role Object

{
  id: string;                    // Firestore document ID
  path: string;                  // Full Firestore path
  roleId: number;                // Unique role ID
  name: string;                  // Role name
  updatedAt: string | Date;      // Last update timestamp
  permissions: object;           // Role permissions configuration
  // ... other role fields
}

Usage Examples

Basic Usage

// Get a specific role by ID
const result = await getRoleById(context, {
  roleId: "role123"
});

if (result.role) {
  console.log(result.role.name);         // Role name
  console.log(result.role.permissions);  // Role permissions
} else {
  console.log("Role not found");
}

Checking Role Permissions

const result = await getRoleById(context, {
  roleId: "role123"
});

if (result.role) {
  console.log(`Role: ${result.role.name}`);
  console.log("Permissions:", result.role.permissions);
} else {
  console.log("Role does not exist");
}

Implementation Details

Data Transformation

The tool transforms the Firestore document by:

  1. Adding the document id and full path
  2. Converting updatedAt timestamp to Date object
  3. Preserving all other fields as-is
const data = docSnap.data();
return {
  role: {
    id: docSnap.id,
    path: docSnap.ref.path,
    ...data,
    updatedAt: safeToDate(data.updatedAt) || data.updatedAt,
  },
};

Validation

The tool validates that roleId is provided:

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

Not Found Handling

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

Error Handling

Common Errors

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

Error Response

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

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

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}/Roles/{roleId}
  - roleId: number
  - name: string
  - updatedAt: timestamp
  - permissions: object

See Also