get-record-list-memberships

Instructions

Implementation Reference

• src/objects/lists/membership.ts:12-112 (handler)

  Core implementation of the get-record-list-memberships tool. Queries Attio API endpoints for list entries associated with the given record ID across companies, people, and deals objects. Handles validation, batching, and error recovery.

  export async function getRecordListMemberships(
    recordId: string,
    objectType?: string,
    includeEntryValues: boolean = false,
    batchSize: number = 5
  ): Promise<ListMembership[]> {
    if (!recordId || typeof recordId !== 'string' || !isValidUUID(recordId)) {
      return [];
    }
  
    if (
      objectType &&
      !Object.values(ResourceType).includes(objectType as ResourceType)
    ) {
      const validTypes = Object.values(ResourceType).join(', ');
      throw new Error(
        `Invalid object type: "${objectType}". Must be one of: ${validTypes}`
      );
    }
  
    try {
      const api = getLazyAttioClient();
      const memberships: ListMembership[] = [];
  
      const objectTypes = objectType
        ? [objectType]
        : ['companies', 'people', 'deals'];
      const maxTypes = Math.max(1, batchSize);
      const typesToQuery = objectTypes.slice(0, maxTypes);
  
      for (const objType of typesToQuery) {
        try {
          const response = await api.get(
            `/objects/${objType}/records/${recordId}/entries`
          );
          const rawEntries = Array.isArray(response?.data?.data)
            ? (response.data.data as Array<Record<string, unknown>>)
            : [];
  
          for (const entry of rawEntries) {
            const listId =
              (entry.list_id as string | undefined) ||
              (
                (entry.list as Record<string, unknown> | undefined)?.id as
                  | { list_id?: string }
                  | undefined
              )?.list_id ||
              'unknown';
            const listName =
              ((entry.list as Record<string, unknown> | undefined)?.name as
                | string
                | undefined) || 'Unknown List';
            const entryIdValue = entry.id as
              | string
              | { entry_id?: string }
              | undefined;
            const entryId =
              typeof entryIdValue === 'string'
                ? entryIdValue
                : (entryIdValue?.entry_id ?? 'unknown');
  
            memberships.push({
              listId,
              listName,
              entryId,
              entryValues: includeEntryValues
                ? ((entry.values as ListEntryValues | undefined) ?? {})
                : undefined,
            });
          }
  
          if (objectType) {
            break;
          }
        } catch (error: unknown) {
          if (isNotFoundError(error)) {
            continue;
          }
          if (process.env.NODE_ENV === 'development') {
            createScopedLogger('lists', 'getRecordListMemberships').warn(
              `Error checking ${objType} entries for record ${recordId}`,
              { error: getErrorMessage(error) ?? String(error) }
            );
          }
        }
      }
  
      return memberships;
    } catch (error: unknown) {
      if (isNotFoundError(error)) {
        return [];
      }
      if (process.env.NODE_ENV === 'development') {
        createScopedLogger('lists', 'getRecordListMemberships').warn(
          `Error in getRecordListMemberships for record ${recordId}`,
          { error: getErrorMessage(error) ?? String(error) }
        );
      }
      return [];
    }
  }

• src/handlers/tool-configs/lists.ts:38-45 (registration)

  Tool configuration registering the handler function, name, and result formatter for the get-record-list-memberships tool.

  getRecordListMemberships: {
    name: 'get-record-list-memberships',
    handler: getRecordListMemberships,
    formatResult: (results: ListMembership[] | null | undefined) => {
      // Return JSON string - dispatcher will convert to JSON content
      return JSON.stringify(Array.isArray(results) ? results : []);
    },
  } as ToolConfig,

• src/handlers/tool-configs/lists.ts:206-247 (schema)

  Input schema and description definition for the get-record-list-memberships tool, including parameters like recordId, objectType, includeEntryValues, and batchSize.

    name: 'get-record-list-memberships',
    description: formatToolDescription({
      capability:
        'Find all lists containing a specific company or person record.',
      boundaries: 'modify list memberships or retrieve list entries.',
      constraints:
        'Requires recordId; processes 5 lists in parallel by default (max 20).',
      recoveryHint:
        'If record not found, verify recordId with records_search first.',
    }),
    inputSchema: {
      type: 'object',
      properties: {
        recordId: {
          type: 'string',
          description: 'ID of the record to find in lists',
          example: '550e8400-e29b-41d4-a716-446655440000',
        },
        objectType: {
          type: 'string',
          description: 'Type of record (e.g., "companies", "people")',
          enum: ['companies', 'people'],
        },
        includeEntryValues: {
          type: 'boolean',
          description:
            'Whether to include entry values in the response (e.g., stage, status)',
          default: false,
        },
        batchSize: {
          type: 'number',
          description:
            'Number of lists to process in parallel (1-20, default: 5)',
          minimum: 1,
          maximum: 20,
          default: 5,
        },
      },
      required: ['recordId'],
      additionalProperties: false,
    },
  },

• src/handlers/tools/registry.ts:70-90 (registration)

  Central tool registry where listsToolConfigs (including get-record-list-memberships) is registered under ResourceType.LISTS for both universal and legacy modes.

  export const TOOL_CONFIGS = USE_UNIVERSAL_TOOLS_ONLY
    ? {
        // Universal tools for consolidated operations (Issue #352)
        UNIVERSAL: universalToolConfigs,
        // Lists are relationship containers - always expose them (Issue #470)
        [ResourceType.LISTS]: listsToolConfigs,
        // Workspace members for user discovery (Issue #684)
        [ResourceType.WORKSPACE_MEMBERS]: workspaceMembersToolConfigs,
      }
    : {
        // Legacy resource-specific tools (deprecated, use DISABLE_UNIVERSAL_TOOLS=true to enable)
        [ResourceType.COMPANIES]: companyToolConfigs,
        [ResourceType.PEOPLE]: peopleToolConfigs,
        [ResourceType.DEALS]: dealToolConfigs,
        [ResourceType.LISTS]: listsToolConfigs,
        [ResourceType.TASKS]: tasksToolConfigs,
        [ResourceType.RECORDS]: recordToolConfigs,
        [ResourceType.WORKSPACE_MEMBERS]: workspaceMembersToolConfigs,
        GENERAL: generalToolConfigs,
        // Add other resource types as needed
      };