Attio MCP Server

Instructions

Implementation Reference

• src/handlers/tool-configs/lists.ts:57-87 (handler)

  The handler function for the 'get-list-entries' tool, including UUID validation for listId and delegation to the core getListEntries function.

  getListEntries: {
    name: 'get-list-entries',
    handler: async (listId: string, limit?: number, offset?: number) => {
      // UUID validation - hard fail for invalid list IDs
      if (!isValidUUID(listId)) {
        return {
          isError: true,
          content: [
            {
              type: 'text',
              text: `Invalid list_id: must be a UUID. Got: ${listId}`,
            },
          ],
        };
      }
      return await getListEntries(listId, limit, offset);
    },
    formatResult: (
      results:
        | AttioListEntry[]
        | { isError: boolean; content: Array<Record<string, unknown>> }
    ) => {
      // Handle validation error response
      if (results && typeof results === 'object' && 'isError' in results) {
        return 'Error: Invalid list ID';
      }
  
      // Return JSON string
      return JSON.stringify(Array.isArray(results) ? results : []);
    },
  } as GetListEntriesToolConfig,

• src/handlers/tool-configs/lists.ts:271-304 (schema)

  Tool definition including name, description, and input schema for the 'get-list-entries' tool.

  {
    name: 'get-list-entries',
    description: formatToolDescription({
      capability:
        'Retrieve all records in a list with pagination (companies, people in pipelines).',
      boundaries: 'filter entries or modify list memberships.',
      constraints:
        'Requires list UUID (not slug); default limit 20, max per page varies by API.',
      recoveryHint:
        'Use filter-list-entries for attribute-based filtering instead.',
    }),
    inputSchema: {
      type: 'object',
      properties: {
        listId: {
          type: 'string',
          description: 'UUID of the list to get entries for',
          example: '550e8400-e29b-41d4-a716-446655440000',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of entries to fetch (default: 20)',
          example: 50,
        },
        offset: {
          type: 'number',
          description: 'Number of entries to skip for pagination (default: 0)',
          example: 0,
        },
      },
      required: ['listId'],
      additionalProperties: false,
    },
  },

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

  Central registry where listsToolConfigs (including get-list-entries) is registered under ResourceType.LISTS in TOOL_CONFIGS.

  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
      };

• src/objects/lists/entries.ts:30-37 (helper)

  Core helper function getListEntries called by the tool handler, which delegates to the generic API operation.

  export async function getListEntries(
    listId: string,
    limit: number = 20,
    offset: number = 0,
    filters?: ListEntryFilters
  ): Promise<AttioListEntry[]> {
    return getGenericListEntries(listId, limit, offset, filters);
  }